Skip to main content
Payment webhooks always use the transaction envelope. The top-level event stays transaction; the concrete event name is in data.event_type.

​
Example delivery payload

{
  "id": "evt_pay_1001",
  "event": "transaction",
  "api_version": "v1",
  "data": {
    "id": "tr_1001",
    "event_type": "transaction.paid",
    "correlation_id": "order_1001",
    "method": "pix",
    "status": "paid",
    "amount": 1500,
    "currency": "BRL",
    "paid_at": "2026-03-16T14:03:10.000Z"
  }
}

​
ACK response

{
  "received": true
}

​
Event names emitted today

  • transaction.created
  • transaction.pending
  • transaction.paid
  • transaction.cancelled
  • transaction.refunded
  • transaction.partially_refunded
  • transaction.chargedback
  • transaction.three_ds_required

​
Common ingestion error

{
  "error": "missing_event_id"
}
Fix: deduplicate by the top-level event id, not by transaction ID, because the same transaction can emit more than one business event over time.

​
Mapping guidance

  • Use transaction.paid to release goods or services.
  • Keep the order open on transaction.pending.
  • Use refund and chargeback events to drive finance and support flows.
  • Route transaction.three_ds_required back into your card challenge flow.