Skip to main content
GET
cURL
Read-only lookup for a settlement batch by its reference.

Request

Path parameter reference (batch UUID) — from a settlement.settled / settlement.rejected webhook.

Response

totals_provisional is true while the batch is still open (totals are running estimates) and false once closed, when total_settlement_amount becomes authoritative. total_settlement_amount stays null until the batch reaches a confirmed state. Totals are integers in minor units. A batch carries two currencies, so it states the minor units of each: total_presented_amount is in presented_currency (scale presented_currency_minor_units), and total_settlement_amount in settlement_currency (scale settlement_currency_minor_units). See Currencies and amounts. Returns 404 — never 403 — for a batch that doesn’t exist or belongs to a different merchant, to prevent batch-ID enumeration. See Settlement and reconciliation for batch lifecycle states.

Authorizations

Authorization
string
header
required

Access token from POST /v1/auth/token, sent as Authorization: Bearer <token>. Treat it as opaque.

Path Parameters

reference
string<uuid>
required

The settlement batch reference returned when the batch was created, or carried on a settlement.settled / settlement.rejected webhook.

Response

Successful Response

Standard success envelope. Every successful response has this shape, with the operation's own payload under data.

data
MerchantSettlementStatusResponse · object | null

The operation's result. Its shape is documented per operation; omitted on responses that carry no payload.

message
string | null

Optional human-readable note. Omitted from the response when not set, which is the case for every payment operation today. Never parse it.

request_id
string | null

Correlation ID for this HTTP request, for logs and support. Send your own in the X-Request-Id header (letters, digits and hyphens, up to 36 characters -- other characters are stripped) or the gateway generates one. This is NOT the request_id idempotency key you send in a transaction body; the two are unrelated.

status
string
default:ok

Always ok on a successful (2xx) response. Errors use a different body shape entirely (RFC 9457 problem details), so branch on the HTTP status code, not on this field.

Last modified on October 25, 2026