Skip to main content
This page is the only payload reference for webhooks — the API reference links here instead of duplicating field tables. Every event shares one envelope; the data shape underneath depends on which family the event belongs to.

Event families

A few notes on how these map to what you did:
  • An operation is never the namespace. A successful capture moves a row from authorization.* into payment.* (payment.captured); a failed capture leaves the hold intact and reports under authorization.* instead (authorization.capture_declined / authorization.capture_failed) — the row never became a payment, so it isn’t reported as one.
  • Every other operation (void, refund) reports both its success and its outcome events inside the same namespace it already belongs to.
  • A hold can’t be voided, so there are no authorization.voided, authorization.void_declined, or authorization.void_failed events. A void of an uncaptured authorization is refused with 409 tx:invalid-state-transition and sends no event. A hold ends when you capture it, when its capture window runs out (authorization.expired), or — only when the authorization itself timed out — when RadiumOne reverses it (authorization.reversed). Once captured, a void reports as payment.voided, payment.void_declined, or payment.void_failed.
  • A transaction moving through settlement (SUBMITTED → SETTLING → SETTLED) does not re-fire payment.captured or refund.captured at each stage — those statuses all map to the same event you already received. Track a transaction’s progress into settlement via references.settlement_batch_id plus the batch-level settlement.* event, not a per-stage payment event.
  • A one-shot sale — any card purchase, including a hosted checkout payment and one whose checkout session expired mid-payment (decline_reason: "expired_while_processing") — ends in exactly one of the final events in Final events for a one-shot sale below.
  • A transaction under manual review (INCONSISTENT) sends no event until an operator resolves it, during business hours; then its final event arrives.

Final events for a one-shot sale

A one-shot sale is a card purchase — approved and captured in one step — made with a purchase call or through hosted checkout. Its first final event is always one of these, and it tells you whether to fulfil the order. That holds even when a checkout session expired while the payment was processing: the outcome was unknown to the page, not to RadiumOne. This table is the single reference for that decision — the hosted checkout and Payments API pages link here.
  • Fulfil on payment.captured only — never on payment.declined, payment.failed or payment.reversed, and not on authorization.created until the hold is captured.
  • Nothing else can come first. payment.voided and the other void events only follow a payment.captured (a hold can’t be voided); refund.* events belong to separate refund transactions; settlement.* events describe batches, not a sale’s outcome.
  • “No event yet” is normal while the transaction is PENDING or REVERSAL_PENDING, and while it’s INCONSISTENT until an operator resolves it. Poll the status inquiry if you need an answer sooner, and contact support if it stays INCONSISTENT.
  • Each event can be delivered more than once — de-duplicate on the event id (Retries, ordering, and duplicates).
  • chargeback.created is reserved for a future release. It’s declared so you can see it coming, but it’s never emitted today — don’t build against it yet.

Envelope

Every delivery shares this top-level shape, regardless of family:
string
required
Event ID, for example evt_…. Use this to dedupe retried and duplicate deliveries — see Retries, ordering, and duplicates.
string
required
The event type, for example payment.captured. See Event families for the full catalogue.
string
required
ISO 8601 timestamp. This is the ordering token — see Ordering.
string
required
Schema version for the data block: "v1" for transaction events (authorization.*, payment.*, refund.*) and "v2" for settlement events (settlement.*). Branch on the event family first, then check the version you expect; handle an unknown version gracefully instead of failing the delivery.
object
required
The event body. Shape depends on the family — see Transaction events and Settlement events.
Unknown-field tolerance. Treat every field as optionally growing over time: RadiumOne may add new fields to data in a future release without bumping payload_version. Parse defensively — ignore fields you don’t recognize rather than rejecting the payload.

Transaction events (authorization.*, payment.*, refund.*)

Shared by every authorization.*, payment.*, and refund.* event.
string
required
Always "transaction" for this family. Lets you branch on payload shape without parsing the event type string.
object
required
object
required
object
required
object
required
Both references are set once, when the acquirer answers the original purchase, authorization, or refund. A later capture or void of that transaction doesn’t change them, and a refund carries its own. On a paired loyalty sale, each leg carries the references of the host that processed it.
Any 2xx response is a result you branch on status, never on response_code. See Handle the result and the shared transaction status table.

Settlement events

Shared by settlement.settled, settlement.rejected, and settlement.discarded (payload_version: "v2"). A settlement event describes a settlement — one or two batches — not a single transaction. data.batches has two named slots, payment (card payments) and loyalty (UOB Rewards points and vouchers); each holds a full batch object or null. settlement.rejected and settlement.discarded are sent straight away for the batch concerned, in the same two-slot shape — they’re never held back to wait for the other batch. If a discarded batch is the last of a pair to finish, the pair’s settlement.settled follows.
Upgrading from v1. Settlement events used to carry payload_version: "v1" with data.object: "settlement_batch" and a single data.batch, data.terminal, and data.totals. In v2, data.object is "settlement" and each batch carries its own terminal and totals inside data.batches.payment or data.batches.loyalty. Transaction events didn’t change and stay v1.
Example settlement.settled (v2)
string
required
Always "settlement" for this family.
object
required
The batches this settlement covers, by the money they carry. At least one slot is filled.
object
required
string
required
Settlement batch UUID. Match it against data.references.settlement_batch_id on your transaction events to find the transactions inside the batch.
string
required
Composite batch identity as presented to the acquirer.
string
required
Calendar day the batch covers (ISO 8601) — not when it settled.
string
required
The batch’s own state. On a pair, each slot carries its own batch’s state.
  • SETTLEMENT_CONFIRMED, RECONCILED, or CLOSED_NO_SETTLEMENT — settled (settlement.settled). Treat all three the same: which one you see depends on how the acquirer confirms, not on your money.
  • SETTLEMENT_REJECTED — the acquirer rejected the batch (settlement.rejected).
  • BATCH_DISCARDED — the batch was abandoned and its transactions will never settle (settlement.discarded, or the other slot of a pair’s settlement.settled).
integer
required
Transactions in the batch.
boolean
required
true while the batch is still open — totals are running, not authoritative, until it closes.
string | null
When the batch closed (ISO 8601).
string | null
When the acquirer confirmed settlement (ISO 8601).
object
required
Where the batch settled.
object
required
See Settlement and reconciliation for how these events fit into batch tracking.

Loyalty redemptions

On a paired sale (a card payment with a loyalty redemption), RadiumOne sends one event per redemption sale — the loyalty outcome rides inside that same event’s payload, not as a separate loyalty.* event. The transaction event’s data.transaction.leg tells you which acquirer leg this row settles to (PAYMENT or LOYALTY), and data.transaction.redemption carries the split:
  • APPROVED: points moved. points_amount was redeemed from loyalty; card_amount is the residual charged to the card.
  • DECLINED: the loyalty host refused the redemption, or it moved and was later reversed. The payment leg can still be a healthy AUTHORIZED — a declined redemption does not by itself mean the sale failed. See Pay with points for the degraded-sale behavior this reports.
  • NOT_ATTEMPTED: no confirmed redemption — either none was attempted, or its outcome isn’t known yet.
leg and redemption are null on a standalone (non-redemption) sale. A full redemption — points cover the whole sale, no card charge — reports as a single event with leg: "LOYALTY" and data.references.transaction_group_id: null (there’s no paired card leg to group with). If a loyalty leg is later reversed, that reversal is its own separate event, not folded into the original.
Amounts are always integers in the currency’s minor units. For example, 5000 for SGD means SGD 50.00. Only currencies with 2 minor units are accepted today — read each currency’s minor units from the API rather than from your own table. See Currencies and amounts.

Next steps

Verify webhook signatures

Algorithm, key encoding, and generated verifier code.

Retries, ordering, and duplicates

Delivery semantics, the backoff schedule, and endpoint suspension.
Last modified on October 25, 2026