Skip to main content
Captured funds don’t settle instantly — they’re grouped into a settlement batch per terminal/outlet, sent to the acquirer, and settled as a group. Batch state is also what gates whether you void or refund a transaction.
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 to settlement.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.settled naming 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 id against data.references.settlement_batch_id on 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 a settlement.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.rejected and settlement.discarded as 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 amount on 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 in data.processor.rrn on transaction webhooks. Keep it, and auth_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, and totals.

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.
Last modified on October 25, 2026