Payment Events - Pagou Developer Docs

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": "018f1f2e-7b44-7c9a-8d3e-1a2b3c4d5e71",
    "event_type": "transaction.pending",
    "correlation_id": "order_3001",
    "method": "voucher",
    "status": "pending",
    "amount": 125000,
    "currency": "MXN",
    "voucher": {
      "barcode": "646180123456789012",
      "digitable_line": "646180123456789012",
      "url": "https://payments.example/pay/order_3001",
      "expiration_date": "2026-05-12T23:59:59.000Z",
      "instructions": "Pay using the bank transfer reference before the expiration date.",
      "receipt_url": null
    },
    "informations": [
      { "key": "order_id", "value": "order_3001" },
      { "key": "channel", "value": "app" }
    ],
    "customer": {
      "name": "Ana Souza",
      "email": "ana@example.com",
      "phone": "+5511999998888"
    },
    "products": [
      {
        "id": "019eb2f2-19b1-743e-835b-f7e368742458",
        "title": "Curso completo",
        "unit_price": 125000,
        "quantity": 1,
        "tangible": false,
        "kind": "product"
      }
    ],
    "attribution": {
      "utm_source": "facebook",
      "utm_medium": "cpc",
      "utm_campaign": "black-friday",
      "utm_content": null,
      "utm_term": null,
      "fbc": "fb.1.1699999999.AbCdEf",
      "fbp": "fb.1.1699999999.123456789",
      "gclid": null,
      "ttclid": null,
      "src": null,
      "sck": null,
      "checkout_url": "https://pay.example/checkout/abc",
      "referrer_url": "https://instagram.com/"
    },
    "store": {
      "id": "01930000-0000-7000-8000-000000000001",
      "name": "Marca A"
    }
  }
}

data.customer carries who bought: name, email and phone (phone may be null). The buyer’s document is never sent. The block is null when the transaction has no resolvable customer. data.products carries the purchased line items, in the same shape the transaction detail endpoint returns: the item’s public id, title, unit_price, quantity, tangible, and kind. The list is empty when the transaction has no line items. unit_price is an integer in the currency’s smallest unit, matching amount — 10000 on a BRL sale is R$ 100,00. tangible tells you whether the item ships. kind is product, order_bump or upsell; a free gift arrives as a product priced 0, not a kind of its own. data.attribution carries where the sale came from: campaign UTMs, ad click IDs (fbc, fbp, gclid, ttclid), the affiliate pair (src, sck) and the checkout/referrer URLs. Individual keys are null when absent, and the whole block is null for API-created transactions — attribution lives on the checkout session, which those sales don’t have. data.store tells which store the sale happened in: the storefront’s public id and its name. It is what lets you tell brands apart when one account runs several of them against the same endpoint. The block comes as null — always present, never omitted — when no storefront is recorded on the sale: API charges, manual charges and splits. Sales that predate the storefront rollout arrive null too, so read null as “no storefront recorded” rather than as proof the sale bypassed one.

These blocks are additive and were introduced together. Treat them as optional: keep your handler working when any of them is missing, and don’t make fulfillment depend on their presence.

data.informations echoes the custom informations array you sent when creating the transaction via the API — use it to reconcile the event against your own records. It is present only when you sent custom entries on create; transactions created without them (or through checkout links) omit the field.

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.
For method: "voucher", transaction.pending can also carry payment instructions in data.voucher. Show the returned url, digitable_line, barcode, or instructions and keep waiting for transaction.paid.
Use refund and chargeback events to drive finance and support flows.
Route transaction.three_ds_required back into your card challenge flow.

​Example delivery payload

​ACK response

​Event names emitted today

​Common ingestion error

​Mapping guidance

Example delivery payload

ACK response

Event names emitted today

Common ingestion error

Mapping guidance