Skip to main content
WEBHOOK
Fires as a cardholder’s transaction moves through its lifecycle. TRANSACTION_PROCESSED is the single, canonical event type for card transactions — you may receive it more than once for the same purchase as it progresses. Every payload has two fields you branch on:
  • type — what kind of transaction it is: PURCHASE, REVERSAL, REFUND, or ADJUSTMENT.
  • status — which lifecycle phase / outcome it represents.
They always pair together as follows: A PURCHASE therefore progresses AUTHORIZED → CLEARED; the other types are terminal.

The authorization → clearing flow

A typical purchase produces two TRANSACTION_PROCESSED events:
  1. status: AUTHORIZED when the cardholder pays (a hold is placed).
  2. status: CLEARED when the merchant settles — often a few days later, and sometimes for a slightly different amount (currency conversion, tips). The CLEARED amount is the real, final figure.
Both events carry the same relatedTransactionId, so you can correlate the phases and act on the CLEARED one.
Some merchants settle almost immediately (you’ll see CLEARED right away); others authorize and settle days apart. Always key your “transaction complete” logic off status: CLEARED, never AUTHORIZED.

Correlation fields

relatedTransactionId is the field to group by. It is present on every transaction event, it is the same value on an authorization and on its clearing however far apart they arrive, and it is not derived from anything optional. transactionId is not a correlation key: it identifies the event, so the authorization and the clearing of one purchase carry different values. This is deliberate — it is what makes a redelivery recognisable — but it means two events about one purchase will never share it.
authorizationCode is optional and may be absent. It is passed through from the card network exactly as received; the network stopped returning it on most transactions in October 2026. An integration that correlates on authorizationCode will fail. Use relatedTransactionId, which is always present.
Every references key is omitted when the network did not supply it, rather than sent empty, so an absent key means “not supplied” and never “supplied as blank”.

Events arriving out of order

Deliveries are independent and are retried separately, so a CLEARED event can reach you before its AUTHORIZED one. Treat relatedTransactionId as the purchase’s primary key and upsert on it: create the record on whichever event arrives first, and let the CLEARED amount overwrite the authorized one. Do not require the authorization to exist before accepting a clearing.

Payload — settlement (status: CLEARED)

Payload — reversal (status: REVERSED)

A reversal carries chargeId (the charge it undoes) and relatedTransactionId; a REFUNDED payload has the same shape with status: REFUNDED and type: REFUND.

Payload Fields

Common Use Cases

  • Mark a transaction successful on status: CLEARED, using its amount as the final charge.
  • Correlate an authorization with its settlement via relatedTransactionId, so a hold and its later capture aren’t double-counted.
  • Handle REVERSED (authorization voided) and REFUNDED (merchant refund) to restore balance in your ledger — a REVERSED payload’s chargeId tells you exactly which charge it undoes.
  • Send real-time notifications and implement MCC-based spending controls.
TRANSACTION_PROCESSED supersedes the deprecated granular events (TRANSACTION_AUTHORIZED, TRANSACTION_CLEARED, TRANSACTION_REVERSED, and TRANSACTION_REFUNDED). They remain fully supported for existing integrations — no migration required — but new integrations should subscribe to TRANSACTION_PROCESSED and branch on status.

Body

application/json
event
string
Example:

"TRANSACTION_PROCESSED"

eventId
string
businessId
string
environment
enum<string>
Available options:
LIVE,
SANDBOX
timestamp
string<date-time>
data
object

Response

200

Acknowledge the event.