Transaction Webhook

Webhooks are automatic notifications that the API sends when a transaction event happens.

This page follows the current API contract: the base payload is the same for every event, and what changes is the event prefix and the extra fields of each step.

Supported events

Event	When it is sent
TRANSACTION_CREATED	When the transaction is created
TRANSACTION_PAID	When the transaction is paid
TRANSACTION_INFRACTION	When the transaction enters infraction
TRANSACTION_REFUNDED	When the transaction is refunded

Payload format

Field	Type	Required	Description
type	string (enum) - TRANSACTION_CREATED, TRANSACTION_PAID, TRANSACTION_INFRACTION, TRANSACTION_REFUNDED	Yes	Type of the event sent in the webhook
data	object	Yes	Transaction data

The type field at the root identifies the event. Inside data, the type field identifies the entity operation.

Base payload

These fields are present in every transaction webhook.

Field	Type	Required	Description
id	string (UUID)	Yes	Unique identifier of the transaction
amount	number	Yes	Transaction amount, in cents
paymentMethod	string (enum) - PIX	Yes	Payment method
externalCode	string	Yes	External reference code sent by the integration
isInfoProduct	boolean	Yes	Indicates whether the transaction is for a digital product
createdAt	string (ISO)	Yes	Creation date
status	string (enum) - PENDING, PIX_QRCODE_GENERATED, PAID, PROCESSING_REFUND, PROCESSING_INFRACTION, REFUNDED, INFRACTION, FAILED, BLOCKED	Yes	PENDING: transaction created, awaiting processing PIX_QRCODE_GENERATED: PIX QR Code generated, awaiting payment PAID: transaction paid PROCESSING_REFUND: refund being processed PROCESSING_INFRACTION: infraction being processed REFUNDED: transaction refunded INFRACTION: transaction refunded (MED) FAILED: processing error BLOCKED: blocked because a MED was opened
type	string (enum) - TRANSACTION	Yes	Operation type

Variations per event

TRANSACTION_CREATED

Uses the base payload only.

TRANSACTION_PAID

In addition to the base payload, it adds:

Field	Type	Required	Description
endToEnd	string	No	End-to-end identifier of the transaction
amountPaid	number	Yes	Amount actually paid
paymentDate	string (ISO)	No	Payment date
payer	object	No	Payer data (see Sub-Objects AccountHolder)
paymentReceipt	string	No	URL of the payment receipt

TRANSACTION_INFRACTION

In addition to the base payload, it adds:

Field	Type	Required	Description
endToEnd	string	No	End-to-end identifier of the transaction
infractionAmount	number	Yes	Infraction amount
infractionDate	string (ISO)	No	Infraction date

TRANSACTION_REFUNDED

In addition to the base payload, it adds:

Field	Type	Required	Description
endToEnd	string	No	End-to-end identifier of the transaction
refundAmount	number	Yes	Refund amount
refundDate	string (ISO)	No	Refund date
endToEndRefund	string	No	End-to-end identifier of the refund
refundReceipt	string	No	URL of the refund receipt

Sub-Objects

AccountHolder

Field	Type	Required	Description
type	string (enum) - PF, PJ	Yes	Holder type
name	string	Yes	Holder name
document	string	Yes	Holder document
bankAccount	object	Yes	Bank data (see Sub-Object BankAccount)
pix	object	Yes	PIX key of the holder (see Sub-Object PixKeyVo)

BankAccount

Field	Type	Required	Description
type	string	Yes	Account type
digit	string	Yes	Account check digit
ispb	string	Yes	ISPB of the bank

PixKeyVo

Field	Type	Required	Description
key	string	Yes	PIX key
type	string	Yes	PIX key type

Payload example

Masked data

Sensitive values may be masked with ***.

{
  "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"
      }
    }
  }
}