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
capturemoves a row fromauthorization.*intopayment.*(payment.captured); a failed capture leaves the hold intact and reports underauthorization.*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, orauthorization.void_failedevents. A void of an uncaptured authorization is refused with409 tx:invalid-state-transitionand 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 aspayment.voided,payment.void_declined, orpayment.void_failed. - A transaction moving through settlement (
SUBMITTED→SETTLING→SETTLED) does not re-firepayment.capturedorrefund.capturedat each stage — those statuses all map to the same event you already received. Track a transaction’s progress into settlement viareferences.settlement_batch_idplus the batch-levelsettlement.*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.capturedonly — never onpayment.declined,payment.failedorpayment.reversed, and not onauthorization.createduntil the hold is captured. - Nothing else can come first.
payment.voidedand the other void events only follow apayment.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
PENDINGorREVERSAL_PENDING, and while it’sINCONSISTENTuntil an operator resolves it. Poll the status inquiry if you need an answer sooner, and contact support if it staysINCONSISTENT. - Each event can be delivered more than once — de-duplicate on the event
id(Retries, ordering, and duplicates). chargeback.createdis 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:Event ID, for example
evt_…. Use this to dedupe retried and duplicate deliveries — see Retries, ordering, and duplicates.The event type, for example
payment.captured. See Event families for the full catalogue.ISO 8601 timestamp. This is the ordering token — see Ordering.
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.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.
Transaction event fields
Transaction event fields
Always
"transaction" for this family. Lets you branch on payload shape without parsing the event type string.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.
Settlement events
Shared bysettlement.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)
Settlement event fields
Settlement event fields
Batch object fields (data.batches.payment, data.batches.loyalty)
Batch object fields (data.batches.payment, data.batches.loyalty)
Settlement batch UUID. Match it against
data.references.settlement_batch_id on your transaction events to find the transactions inside the batch.The batch’s own state. On a pair, each slot carries its own batch’s state.
SETTLEMENT_CONFIRMED,RECONCILED, orCLOSED_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’ssettlement.settled).
true while the batch is still open — totals are running, not authoritative, until it closes.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 separateloyalty.* 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_amountwas redeemed from loyalty;card_amountis 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 healthyAUTHORIZED— 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.