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

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. checkout_url is derived on our server from the link and the store’s domain, so it always points at a page of ours. checkout_url_declared carries a checkout URL someone declared and we do not confirm — it can point anywhere, so treat it as text and never as a link to follow. Sales made before 2026-09-16 arrive with checkout_url: null and the old URL under checkout_url_declared, because provenance is not inferred for historical records. referrer_url is declared the same way. 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

​
Event names emitted today

  • transaction.created
  • transaction.pending
  • transaction.paid
  • transaction.cancelled
  • transaction.refunded
  • transaction.partially_refunded
  • transaction.chargedback
  • transaction.three_ds_required
  • transaction.med — explicit subscription only
  • transaction.pre_chargedback — explicit subscription only
The last two are dedicated reversal events. They are delivered only to webhooks that list them in their event selection: a webhook left on “all events” never receives them, because the same reversal already reaches it as transaction.refunded. Subscribe to them in the dashboard (Settings → Integrations) when you want to tell a PIX MED or a pre-chargeback apart from a refund. When a reversal is a MED or a pre-chargeback, the transaction.refunded delivery for it carries data.status as med or pre_chargedback instead of refunded. The event name is stable; the status field is the more specific one.

​
Common ingestion error

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.