Webhook

Webhooks são notificações automáticas que a API envia sempre que ocorre um evento relacionado a uma transação. Assim, você não precisa ficar consultando a API: basta receber e processar o evento quando ele chegar.

Eventos de webhook

Cada webhook representa uma mudança no ciclo de vida da transação.

Tipos de evento

Evento	Descrição
TRANSACTION_CREATED	Transacao criada
TRANSACTION_PAID	Transacao paga
TRANSACTION_INFRACTION	Transacao com infracao
TRANSACTION_REFUNDED	Transacao estornada

Dados do webhook

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

Sub-Objetos

data

Campo	Tipo	Obrigatório	Descrição
id	string (UUID)	Sim	Identificador único da transação
amount	number	Sim	Valor da transação (inteiro em centavos)
paymentMethod	string (enum) - PIX	Sim	Método de pagamento
externalCode	string	Sim	Seu código de referência (pode ser nulo)
isInfoProduct	boolean	Sim	Indica se é 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: Transacao criada, aguardando processamento PIX_QRCODE_GENERATED: QRCode PIX gerada, aguardando pagamento PAID: Transacao paga PROCESSING_REFUND: Estorno em processamento PROCESSING_INFRACTION: Infracao em processamento REFUNDED: Transacao estornada INFRACTION: Transacao estornada (MED) FAILED: Erro no processamento BLOCKED: Bloqueado devido abertura de MED
type	string (enum) - TRANSACTION_CREATED, TRANSACTION_PAID, TRANSACTION_INFRACTION, TRANSACTION_REFUNDED	Sim	Tipo do evento da transação
endToEnd	string	Não	Identificador end-to-end da transação
amountPaid	number	Não	Valor pago
paymentDate	string (ISO)	Não	Data de pagamento
payer	object	Não	Dados do pagador (ver Sub-Objetos AccountHolder)
receiptUrl	string	Não	URL do comprovante
infractionDate	string (ISO)	Não	Data da infração

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-Objetos BankAccount)
pix	object	Sim	Chave PIX do titular (ver Sub-Objetos PixKeyVo)

BankAccount

Campo	Tipo	Obrigatório	Descrição
type	string	Sim	Tipo de conta
branch	string	Sim	Agência
number	string	Sim	Número da 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

{
  "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_PAID",
    "endToEnd": "E2E123456789",
    "amountPaid": 10000,
    "paymentDate": "2026-03-06T12:49:04.681Z",
    "payer": {
      "type": "PF",
      "name": "Fulano de Tal",
      "document": "12345678910",
      "bankAccount": {
        "type": "CHECKING",
        "branch": "0001",
        "number": "123456",
        "digit": "7",
        "ispb": "12345678"
      },
      "pix": {
        "key": "12345678910",
        "type": "CPF"
      }
    },
    "receiptUrl": "https://sua-api.com/receipt/E2E123456789",
    "infractionDate": null
  }
}