Webhook event types - Payments API

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

Family	Meaning	Events
`authorization.*`	Funds held, nothing captured yet	`created`, `declined`, `failed`, `expired`, `voided`, `reversed`, `capture_declined`, `capture_failed`, `void_declined`, `void_failed`
`payment.*`	Money in — a capture succeeded	`captured`, `voided`, `reversed`, `declined`, `failed`, `void_declined`, `void_failed`
`refund.*`	Money out	`captured`, `voided`, `reversed`, `declined`, `failed`, `void_declined`, `void_failed`
`settlement.*`	A settlement batch changed state	`settled`, `rejected`, `discarded`

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 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.
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. Currently always "v1".

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.

Transaction event fields

string

required

Always "transaction" for this family. Lets you branch on payload shape without parsing the event type string.

object

required

Show transaction fields

string

required

Transaction UUID.

string

required

PURCHASE, AUTHORIZE, or REFUND — the type of the row this event reports on. Capture and void never produce their own row; they change the status of the existing PURCHASE/AUTHORIZE row (type stays unchanged) and report under authorization.*/payment.* events instead.

string

required

Transaction lifecycle status — same enum as Payment lifecycle.

object

required

Show amount fields

string

required

ISO 4217 currency code.

string

required

Amount in the currency’s minor units, as a numeric string (avoids floating-point precision loss on large values).

integer

required

The currency’s decimal-place exponent (2 for SGD/USD, 0 for JPY) — not a copy of value. {"currency":"SGD","value":"12000","minor_units":2} means SGD 120.00.

string | null

When the transaction occurred (ISO 8601) — not when this event was raised.

string | null

PAYMENT / LOYALTY on a paired loyalty sale; null on a standalone sale.

object | null

Loyalty split, present only on a paired redemption sale — see Loyalty redemptions below.

Show redemption fields

string

required

APPROVED (points moved) / DECLINED (host refused, or moved and reversed) / NOT_ATTEMPTED (no confirmed redemption yet).

object

required

Residual amount charged to the card. Same shape as transaction.amount.

object

required

Value redeemed from loyalty. Same shape as transaction.amount.

object

required

Show merchant fields

string

required

Your merchant UUID.

string | null

Outlet that owns the channel this transaction came through.

string | null

Originating channel UUID.

string | null

Channel type, for example ECOMMERCE_SITE or PHYSICAL_STORE.

object

required

Show references fields

string | null

Your own order identifier, echoed back if you sent one.

string

required

Your idempotency key for the original request.

string | null

The transaction this one acts on (a refund’s original sale, a void’s authorization). null on an original sale.

string | null

Groups the payment and loyalty legs of one paired sale. null on a standalone sale.

string | null

The settlement batch this transaction belongs to — join this against the corresponding settlement.* event. null before the transaction is assigned to a batch.

object

required

Show processor fields

string | null

Verbatim host/acquirer response code ("00" = approved). Useful for support tickets and reconciliation footnotes — branch your application logic on transaction.status, never on this code.

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

Settlement event fields

string

required

Always "settlement_batch" for this family.

object

required

Show batch fields

string

required

Settlement batch UUID.

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

SETTLEMENT_CONFIRMED / SETTLEMENT_REJECTED / RECONCILED.

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

Show merchant fields

string

required

Your merchant UUID.

object

required

Show terminal fields

string | null

The settling device’s UUID. This webhook is the only supported way to discover a device_id.

object

required

Show totals fields

object

required

Net total in the transaction currency. Same shape as a transaction amount.

object | null

Net total in the settlement currency. null until the batch is confirmed.

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 unit. For example, 5000 for SGD means SGD 50.00.

Fields RadiumOne doesn’t publish yet

The gateway’s internal event payload also carries processor.rrn, processor.auth_code, and terminal.acquirer_id. These aren’t published today, pending a decision on exposing acquirer- and host-level identifiers to merchants. If your integration needs one of these, contact support rather than relying on an undocumented field appearing in a future payload — additions here are additive, but nothing guarantees a specific field ships on a specific date.

Introduction

Guides

Payment methods

3D Secure

Handle failures

Webhooks

Errors

Reference

Webhook event types - Payments API

Event families

Envelope

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

Settlement events

Loyalty redemptions

Fields RadiumOne doesn’t publish yet

Next steps

Verify webhook signatures

Retries, ordering, and duplicates

​Event families

​Envelope

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

​Settlement events

​Loyalty redemptions

​Fields RadiumOne doesn’t publish yet

​Next steps

Verify webhook signatures

Retries, ordering, and duplicates

Event families

Envelope

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

Settlement events

Loyalty redemptions

Fields RadiumOne doesn’t publish yet

Next steps