Settlement

Overview

When a customer pays using their card, the funds are not sent to the merchant's bank account immediately. They are only transferred when the merchant performs a settlement - typically at the end of the trading day. A settlement totals all payments received and subtracts all refunds, then sends the net amount to the bank in a single transfer.

Here is a simple example:

Transaction	Amount
Purchase of shirt	+$20.00
Purchase of hat	+$10.00
Refund of hat	−$10.00
Total settled	$20.00

Settlements and settlement enquiries are both submitted to the same endpoint:

POST /v1/settlements

Once created, poll for the result using:

GET /v1/settlements/{settlement_id}

The polling loop for settlements is identical to the one used for transactions - see Transactions Overview for the full polling loop implementation.

Settlement

A settlement closes the current batch and sends the net total to the merchant's bank.

POST /v1/settlements

{
  "type": "SETTLEMENT"
}

The terminal will display settlement progress to the merchant. Poll the returned settlement_id until the settlement reaches FINALISED.

Settlement enquiry

A settlement enquiry retrieves a summary of transactions without closing the batch or transferring any funds. Enquiries can be made any number of times throughout the day.

Today's settlement

POST /v1/settlements

{
  "type": "ENQUIRY"
}

Settlement for a specific date

POST /v1/settlements

{
  "type": "ENQUIRY",
  "enquiry_date": {
    "year": 2024,
    "month": 11,
    "day": 7
  }
}

Field	Type	Required	Description
`enquiry_date`	object	No	The date to query. If omitted, returns today's settlement summary
`enquiry_date.year`	integer	Yes (if date provided)	Four-digit year
`enquiry_date.month`	integer	Yes (if date provided)	Month (1–12)
`enquiry_date.day`	integer	Yes (if date provided)	Day of month (1–31)

Polling

After submitting a settlement or enquiry, poll the returned settlement_id using:

GET /v1/settlements/{settlement_id}?min_version={min_version}

Pass the min_version from the last response to receive only updates. Continue polling until the settlement reaches FINALISED.

See Transactions Overview for the complete polling loop implementation, including backoff strategy and Action Framework callbacks.

Receipt codes

Settlement and settlement enquiry receipts use three-letter codes to identify transaction types:

Code	Transaction type
`PUR`	Purchases
`TIP`	Tips
`SUR`	Surcharges
`REF`	Refunds
`CAS`	Cashouts
`TOT`	Totals

Action Framework callbacks

Settlements trigger the following Action Framework callbacks:

Action code	Description
`SETTLEMENT_COMPLETE`	The settlement has completed. Trigger any post-settlement logic in your POS, such as printing a settlement report or resetting the current transaction batch.
`RETRY_SETTLEMENT`	The settlement needs to be retried. Resubmit the same settlement request.

Recovery

Settlement uses the same polling loop as transactions and is subject to the same failure scenarios - network disconnection, terminal offline, and timeout. The override flow applies to settlements in the same way.

See Transaction recovery for full details.