Webhook de Transacción

Los webhooks son notificaciones automáticas que la API envía cuando ocurre un evento de la transacción.

Esta página sigue el contrato actual de la API: el payload base es el mismo en todos los eventos y lo que cambia es el prefijo del evento y los campos adicionales de cada etapa.

Eventos soportados

Evento	Cuándo se envía
TRANSACTION_CREATED	Cuando se crea la transacción
TRANSACTION_PAID	Cuando la transacción es pagada
TRANSACTION_INFRACTION	Cuando la transacción entra en infracción
TRANSACTION_REFUNDED	Cuando la transacción es reembolsada

Formato del payload

Campo	Tipo	Obligatorio	Descripción
type	string (enum) - TRANSACTION_CREATED, TRANSACTION_PAID, TRANSACTION_INFRACTION, TRANSACTION_REFUNDED	Sí	Tipo del evento enviado en el webhook
data	object	Sí	Datos de la transacción

El campo type en la raíz identifica el evento. Dentro de data, el campo type identifica la operación de la entidad.

Payload base

Estos campos están presentes en todos los webhooks de transacción.

Campo	Tipo	Obligatorio	Descripción
id	string (UUID)	Sí	Identificador único de la transacción
amount	number	Sí	Monto de la transacción, en centavos
paymentMethod	string (enum) - PIX	Sí	Método de pago
externalCode	string	Sí	Código de referencia externo enviado por la integración
isInfoProduct	boolean	Sí	Indica si la transacción corresponde a un producto digital
createdAt	string (ISO)	Sí	Fecha de creación
status	string (enum) - PENDING, PIX_QRCODE_GENERATED, PAID, PROCESSING_REFUND, PROCESSING_INFRACTION, REFUNDED, INFRACTION, FAILED, BLOCKED	Sí	PENDING: transacción creada, en espera de procesamiento PIX_QRCODE_GENERATED: QR Code PIX generado, en espera de pago PAID: transacción pagada PROCESSING_REFUND: reembolso en procesamiento PROCESSING_INFRACTION: infracción en procesamiento REFUNDED: transacción reembolsada INFRACTION: transacción reembolsada (MED) FAILED: error en el procesamiento BLOCKED: bloqueada por la apertura de un MED
type	string (enum) - TRANSACTION	Sí	Tipo de la operación

Variaciones por evento

TRANSACTION_CREATED

Usa solamente el payload base.

TRANSACTION_PAID

Además del payload base, agrega:

Campo	Tipo	Obligatorio	Descripción
endToEnd	string	No	Identificador end-to-end de la transacción
amountPaid	number	Sí	Monto efectivamente pagado
paymentDate	string (ISO)	No	Fecha del pago
payer	object	No	Datos del pagador (ver Sub-Objetos AccountHolder)
paymentReceipt	string	No	URL del comprobante de pago

TRANSACTION_INFRACTION

Además del payload base, agrega:

Campo	Tipo	Obligatorio	Descripción
endToEnd	string	No	Identificador end-to-end de la transacción
infractionAmount	number	Sí	Monto de la infracción
infractionDate	string (ISO)	No	Fecha de la infracción

TRANSACTION_REFUNDED

Además del payload base, agrega:

Campo	Tipo	Obligatorio	Descripción
endToEnd	string	No	Identificador end-to-end de la transacción
refundAmount	number	Sí	Monto del reembolso
refundDate	string (ISO)	No	Fecha del reembolso
endToEndRefund	string	No	Identificador end-to-end del reembolso
refundReceipt	string	No	URL del comprobante de reembolso

Sub-Objetos

AccountHolder

Campo	Tipo	Obligatorio	Descripción
type	string (enum) - PF, PJ	Sí	Tipo de titular
name	string	Sí	Nombre del titular
document	string	Sí	Documento del titular
bankAccount	object	Sí	Datos bancarios (ver Sub-Objeto BankAccount)
pix	object	Sí	Clave PIX del titular (ver Sub-Objeto PixKeyVo)

BankAccount

Campo	Tipo	Obligatorio	Descripción
type	string	Sí	Tipo de cuenta
digit	string	Sí	Dígito de la cuenta
ispb	string	Sí	ISPB del banco

PixKeyVo

Campo	Tipo	Obligatorio	Descripción
key	string	Sí	Clave PIX
type	string	Sí	Tipo de la clave PIX

Ejemplo de payload

Datos enmascarados

Los valores sensibles pueden estar enmascarados con ***.

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