Webhook de transação - Documentação Pluggou

Webhook de transação

Sempre que ocorre uma mudança de status em uma transação, a Pluggou envia um webhook para todos os endpoints ativos cadastrados na sua conta. Para entender o funcionamento geral dos webhooks (headers, segurança, tempo limite, retentativas e idempotência), consulte o guia geral de Webhooks.

Exemplo de webhook recebido

curl -X POST https://seusite.com/webhook \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Event-ID: f47ac10b-58cc-4372-a567-0e02b2c3d479" \
  -H "X-Webhook-Code: whk_a8Kd92mNx7Pq3rT5vW1yZ0bC4eF6gH8jL0mN2pR4tV6x" \
  -H "User-Agent: Pluggou-Webhook/1.0" \
  -d '{
    "id": "c3d4e5f6-a1b2-7890-cdef-1234567890ab",
    "event_type": "transaction",
    "data": {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "payment_method": "pix",
        "e2e_id": "E12345678202301011234abcdefghijkl",
        "amount": 10000,
        "platform_tax": 149,
        "liquid_amount": 9851,
        "status": "paid",
        "paid_at": "2026-01-29 14:30:00",
        "created_at": "2026-01-29 14:25:00"
    }
  }'

Campos do payload

Campo	Tipo	Descrição
`id`	string (UUID)	Identificador único deste evento de webhook.
`event_type`	string	Sempre `"transaction"` para webhooks de transação.
`data.id`	string (UUID)	Identificador único da transação.
`data.payment_method`	string	Método de pagamento utilizado (ex: `"pix"`).
`data.e2e_id`	string \| null	Identificador end-to-end do PIX gerado pelo banco. Disponível apenas após a confirmação do pagamento.
`data.amount`	integer	Valor total da transação em centavos.
`data.platform_tax`	integer	Taxa total cobrada pela plataforma em centavos.
`data.liquid_amount`	integer	Valor líquido que o usuário receberá em centavos (`amount - platform_tax`).
`data.status`	string	Status atual da transação (veja tabela abaixo).
`data.paid_at`	string \| null	Data/hora do pagamento no formato `"YYYY-MM-DD HH:mm:ss"`. `null` se ainda não foi pago.
`data.created_at`	string	Data/hora de criação da transação no formato `"YYYY-MM-DD HH:mm:ss"`.

Status possíveis

Status	Significado
`pending`	Transação criada e aguardando pagamento pelo comprador.
`paid`	Pagamento confirmado. O valor líquido foi creditado na carteira do usuário.
`failed`	Pagamento falhou ou foi recusado pela instituição financeira.
`canceled`	Transação cancelada (expiração ou cancelamento manual).
`refunded`	Valor devolvido ao pagador após o pagamento ter sido confirmado.
`chargeback`	Contestação ou disputa aberta pelo pagador (MED, infração, bloqueio).