Skip to main content

Get Settlement Status

GET /merchant/settlements/:id returns the current state of one of your settlements. Use it to track a settlement from REQUESTED to its terminal outcome.

Status lifecycle​

    (PENDING_APPROVAL) ─┐
(UNDERFUNDED)          ─┤
(WAITING_AML_CREDIT)   ─┴→ REQUESTED → PROCESSING → SETTLED   (terminal)
                                                  → REJECTED  (terminal)

Settlements normally start at REQUESTED. Three statuses come before it, and all three converge on it:

  • PENDING_APPROVAL — the amount exceeds your cashout approval cap, or destination screening did not pass (failed or unavailable — AML-screened gateways only). The funds are claimed; it waits until someone approves it, from the dashboard or over the API.
  • UNDERFUNDED — you asked for more than the routed pool holds. Nothing is claimed; shortfall says how much more is needed, and it activates itself when the funds land. See Parked cashouts.
  • WAITING_AML_CREDIT — a SMART or AML_HELD cashout whose destination screen could not run because your AML screening credit is exhausted. It resolves itself once you top up.

REJECTED is a cancellation — by an operator, by your own cancel of a parked cashout, or automatically when a parked cashout passes its expiresAt. A cashout whose destination turns out to be a Finomesh address (for example, a payment's deposit address) is also rejected before anything is sent, with rejectionReason destination_is_platform_address.

Once SETTLED, the response carries the real receivedAmount, txHash, and a ready-to-open blockchainUrl. A settlement id that isn't yours returns 404.

Example​

TS=$(date +%s); BODY=""
SIG=$(printf '%s.%s' "$TS" "$BODY" | openssl dgst -sha256 -hmac "$SIGNING_SECRET" | awk '{print $2}')
curl https://api.finomesh.com/api/v1/merchant/settlements/<settlement-id> \
  -H "X-Api-Key: $FINOMESH_API_KEY" \
  -H "X-Timestamp: $TS" -H "X-Signature: $SIG"

Tracking a settlement​

There is no settlement webhook — poll this endpoint (or list) until status reaches a terminal value. A reasonable cadence is every few minutes for a normal payout, or immediately after you know a blocker has cleared (e.g. right after topping up funds or AML credit).

This endpoint is also the only source for a parked cashout's live shortfall / shortfallUsd. They are recomputed on every read here (and on list) and are absent from the 202 create response, so read them back rather than caching what you calculated yourself.

Reference​