Skip to main content
Pagou currently exposes two public webhook envelope shapes.

​
Envelope comparison

DomainTop-level event fieldResource fieldConcrete event name
Paymentsevent: "transaction"datadata.event_type
Transferstypedata.objecttop-level type

​
Payment webhook example

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

​
Transfer webhook example

{
  "id": "evt_payout_1001",
  "type": "payout.transferred",
  "api_version": "v2",
  "data": {
    "object": {
      "id": "po_1001",
      "status": "paid",
      "type": "pix",
      "amount": 1200
    }
  }
}

​
ACK response

{
  "received": true
}

​
Common ingestion error

{
  "error": "missing_event_id"
}
Fix: require the top-level id, deduplicate by that value, return 200 OK quickly, and process asynchronously.

​
Mapping guidance

  • Drive business state from resource status, not from a frontend guess.
  • Map transfer event payout.transferred to settled resource status paid.
  • Reconcile if your worker crashes after acknowledgement.