This request requires a valid access token. See Authentication to obtain one with
POST /v1/auth/token before you continue.Batches
A batch moves through the same settlement stages a transaction reports: queued (SUBMITTED), in progress at the acquirer (SETTLING), and settled (SETTLED). While a batch is open, its transactions can still be voided; once it closes, only a referenced or standalone refund can return funds. See Payment lifecycle for the full state diagram.
Settlement webhooks
Subscribe tosettlement.settled, settlement.rejected, and settlement.discarded to track batch outcomes without polling. Settlement events use payload_version: "v2": each one names the batches it covers in data.batches.payment (card payments) and data.batches.loyalty (UOB Rewards points and vouchers), and a slot is null when the settlement has no batch of that kind. See Webhook event types for the full payload shape.
- One event can cover two batches. If your terminal settles card payments and rewards redemptions together, you get one
settlement.settlednaming both batches, once both have finished. Otherwise you get one event per batch, with one slot filled. - Rejections and discards arrive straight away for the batch concerned — they never wait for the other batch.
- Join batches to transactions by matching each filled slot’s
idagainstdata.references.settlement_batch_idon your transaction events.
Retrieve a settlement batch
Look up a batch’s status and totals by its reference when you need an authoritative read (for example, to reconcile asettlement.rejected event). This lookup is documented in the API reference.
Reconciliation tips
- Reconcile by batch reference, not by settlement date alone — a batch can span or shift across calendar days depending on cutoff timing.
- Treat
settlement.rejectedandsettlement.discardedas exceptions requiring investigation, not just log entries — funds you expected to settle didn’t. - Cross-check your own transaction totals against the batch totals returned above; a mismatch is worth investigating before you close your books for the period.
- Remember that a transaction’s
amounton a loyalty-split sale reflects only the card residual, not the gross order total — reconcile against the right figure. - Match individual transactions to the acquirer’s statement on
rrn(retrieval reference number), returned on the transaction object and indata.processor.rrnon transaction webhooks. Keep it, andauth_code, with the order: they’re what you quote in a dispute. - Each batch in a settlement event carries its own
terminal.acquirer_id(for example,data.batches.payment.terminal.acquirer_id), which tells you which acquirer processed that batch, so you can group batches by acquirer when you match them against statements. On a combined settlement, the card and rewards batches can name different acquirers. - Reconcile each slot of a settlement event on its own: the card batch and the rewards batch have their own
id,state,tx_count, andtotals.
Go-live notes
- Register a webhook endpoint before you go live so settlement outcomes reach you without polling.
- Build an alert for
settlement.rejected/settlement.discarded— these need a human, not just a log line. - Review the full go-live checklist.
Next steps
Retrieve a settlement batch
Full reference for the batch-status lookup.
Webhooks
Set up your endpoint and verify signatures.