Webhook de Transação

Webhooks são notificações automáticas que a API envia quando um evento da transação acontece.

Esta página segue o contrato atual da API: o payload base é o mesmo em todos os eventos e o que muda é o prefixo do evento e os campos extras de cada etapa.

Se você trabalha com depósitos, veja Webhook de Depósito.

Eventos suportados

Evento	Quando é enviado
TRANSACTION_CREATED	Quando a transação é criada
TRANSACTION_PAID	Quando a transação é paga
TRANSACTION_INFRACTION	Quando a transação entra em infração
TRANSACTION_REFUNDED	Quando a transação é estornada

Formato do payload

Campo	Tipo	Obrigatório	Descrição
type	string (enum) - TRANSACTION_CREATED, TRANSACTION_PAID, TRANSACTION_INFRACTION, TRANSACTION_REFUNDED	Sim	Tipo do evento enviado no webhook
data	object	Sim	Dados da transação

O campo type na raiz identifica o evento. Dentro de data, o campo type identifica a operação da entidade.

Payload base

Esses campos estão presentes em todos os webhooks de transação.

Campo	Tipo	Obrigatório	Descrição
id	string (UUID)	Sim	Identificador único da transação
amount	number	Sim	Valor da transação, em centavos
paymentMethod	string (enum) - PIX	Sim	Método de pagamento
externalCode	string	Sim	Código de referência externo enviado pela integração
isInfoProduct	boolean	Sim	Indica se a transação é de produto digital
createdAt	string (ISO)	Sim	Data de criação
status	string (enum) - PENDING, PIX_QRCODE_GENERATED, PAID, PROCESSING_REFUND, PROCESSING_INFRACTION, REFUNDED, INFRACTION, FAILED, BLOCKED	Sim	PENDING: transação criada, aguardando processamento PIX_QRCODE_GENERATED: QRCode PIX gerado, aguardando pagamento PAID: transação paga PROCESSING_REFUND: estorno em processamento PROCESSING_INFRACTION: infração em processamento REFUNDED: transação estornada INFRACTION: transação estornada (MED) FAILED: erro no processamento BLOCKED: bloqueado devido à abertura de MED
type	string (enum) - TRANSACTION	Sim	Tipo da operação

Variações por evento

TRANSACTION_CREATED

Usa apenas o payload base.

TRANSACTION_PAID

Além do payload base, adiciona:

Campo	Tipo	Obrigatório	Descrição
endToEnd	string	Não	Identificador end-to-end da transação
amountPaid	number	Sim	Valor efetivamente pago
paymentDate	string (ISO)	Não	Data do pagamento
payer	object	Não	Dados do pagador (ver Sub-Objetos AccountHolder)
paymentReceipt	string	Não	URL do comprovante de pagamento

TRANSACTION_INFRACTION

Além do payload base, adiciona:

Campo	Tipo	Obrigatório	Descrição
endToEnd	string	Não	Identificador end-to-end da transação
infractionAmount	number	Sim	Valor da infração
infractionDate	string (ISO)	Não	Data da infração

TRANSACTION_REFUNDED

Além do payload base, adiciona:

Campo	Tipo	Obrigatório	Descrição
endToEnd	string	Não	Identificador end-to-end da transação
refundAmount	number	Sim	Valor do estorno
refundDate	string (ISO)	Não	Data do estorno
endToEndRefund	string	Não	Identificador end-to-end do estorno
refundReceipt	string	Não	URL do comprovante de estorno

Sub-Objetos

AccountHolder

Campo	Tipo	Obrigatório	Descrição
type	string (enum) - PF, PJ	Sim	Tipo do titular
name	string	Sim	Nome do titular
document	string	Sim	Documento do titular
bankAccount	object	Sim	Dados bancários (ver Sub-Objeto BankAccount)
pix	object	Sim	Chave PIX do titular (ver Sub-Objeto PixKeyVo)

BankAccount

Campo	Tipo	Obrigatório	Descrição
type	string	Sim	Tipo de conta
digit	string	Sim	Dígito da conta
ispb	string	Sim	ISPB do banco

PixKeyVo

Campo	Tipo	Obrigatório	Descrição
key	string	Sim	Chave PIX
type	string	Sim	Tipo da chave PIX

Exemplo de payload

Dados mascarados

Valores sensíveis podem estar mascarados com ***.

{
  "type": "TRANSACTION_PAID",
  "data": {
    "id": "553e8400-e29b-41d4-a716-436251480000",
    "amount": 10000,
    "paymentMethod": "PIX",
    "externalCode": "TRANS-123",
    "isInfoProduct": false,
    "createdAt": "2026-03-06T12:49:04.681Z",
    "status": "PAID",
    "type": "TRANSACTION",
    "endToEnd": "E2E123456789",
    "amountPaid": 10000,
    "paymentDate": "2026-03-06T12:49:04.681Z",
    "paymentReceipt": "https://files.exemplo.com.br/receipts/transaction-553e8400-e29b-41d4-a716-436251480000.pdf",
    "payer": {
      "type": "PF",
      "name": "Fulano de Tal",
      "document": "***456789**",
      "bankAccount": {
        "type": "CHECKING",
        "digit": "7",
        "ispb": "12345678"
      },
      "pix": {
        "key": "12345678910",
        "type": "CPF"
      }
    }
  }
}