Skip to main content

Create Settlement

POST /merchant/settlements requests a settlement of an exact amount to a destination address. It returns immediately with a REQUESTED settlement; the on-chain payout is dispatched after your gateway's configured delay.

If you have set a cashout approval cap, a request above the cap instead returns a PENDING_APPROVAL settlement that waits for someone on your team to approve it in the dashboard before it is dispatched.

Example​

BODY='{"assetId":"<asset-uuid>","amount":"250.00","address":"T...","label":"payouts","metadata":{"requester":"ops-team-alice","orderId":"1234"}}'
TS=$(date +%s)
SIG=$(printf '%s.%s' "$TS" "$BODY" | openssl dgst -sha256 -hmac "$SIGNING_SECRET" | awk '{print $2}')
curl -X POST https://api-staging.finomesh.com/api/v1/merchant/settlements \
  -H "X-Api-Key: $FINOMESH_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "X-Timestamp: $TS" -H "X-Signature: $SIG" \
  -d "$BODY"

Key rules​

  • amount must be > 0 and ≤ your matured available for that asset — check Get Balances first. Requesting more returns a 409 conflict.
  • Idempotency-Key is required. Reuse the same key to safely retry without creating a second settlement. The same key with a different body returns 409 idempotency_conflict.
  • address is validated for the asset's chain (EVM EIP-55 checksum, TRON/UTXO base58check) and stored in your address book on first use, tagged API. A repeat address is reused, not rejected.
  • metadata (optional) is a free-form, one-level JSON object for your own tracking — attach whatever you need (e.g. {"requester":"ops-team-alice","orderId":"1234"}). It is echoed back on read and shown to the approver, key by key, when a request parks at the approval cap. Keys are not validated; total size is capped at 4 KB. A conventional requester key (who initiated the cashout) is shown first to the approver.
  • The response starts REQUESTED (so txHash / blockchainUrl are empty), or PENDING_APPROVAL when the amount exceeds your approval cap. netAmount = amount − feeLocked is what lands at the destination.

Approval cap​

If your gateway has a cashout approval cap (a USD ceiling you configure in the dashboard), any API cashout whose USD value is strictly greater than the cap is created as PENDING_APPROVAL instead of REQUESTED. It reserves the funds but is not dispatched until it is approved — from the dashboard settlement list or over the API (list the waiting cashouts, then approve; 2FA required). Approving it moves it to REQUESTED and starts the normal dispatch delay. Approval is the only merchant action: a parked cashout you don't approve stays reserved until you do (cancelling one is an operator/support action, not a merchant reject). With no cap configured, every API cashout dispatches without approval, exactly as before.

Fee efficiency​

Prefer one larger cashout over many small ones

Every settlement is a separate on-chain transaction that pays its own network fee. On fee-based chains — notably TRON, where each transfer burns energy/bandwidth — splitting a withdrawal into several partial cashouts makes you pay that per-transaction fee every time, so the total network cost is higher than withdrawing the same funds in a single settlement.

Where practical, cash out your full available balance in one request rather than dribbling it out in repeated partial withdrawals. Estimate the fee first if you want to compare.

Track it to a terminal state with Get Settlement Status, or rely on the settlement webhook.

Reference​