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.

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-staging.finomesh.com/api/v1/merchant/settlements/<settlement-id> \
  -H "X-Api-Key: $FINOMESH_API_KEY" \
  -H "X-Timestamp: $TS" -H "X-Signature: $SIG"

Polling vs. webhook​

You do not have to poll — a settlement webhook fires on the terminal result. Poll when you want a synchronous check (for example, confirming a payout in an operator screen); otherwise let the webhook drive your bookkeeping.

One case where this endpoint is the only source: 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​