Skip to main content
Payouts (supplier settlements, customer withdrawals, partner disbursements) are the highest-risk operation a payments business automates. This solution runs them from your backend with an API key that can only request withdrawals from one wallet, inside limits and whitelists the platform enforces, with human approval above a threshold.

​
What you’ll need

  • A treasury wallet with the payout asset attached and funded.
  • Owner or admin access to the console to set policies and create the service key.
  • The list of destination addresses you pay, if you intend to whitelist them.

​
Components to configure

​
Steps

1

Set the policy in the console

Under Account Settings → Security & Approvals, enable Only allow whitelisted addresses and add your destinations to the Address Book; set Per transaction and Per day limits under Spend limit; and enable Require approval to withdraw with a Require above amount threshold and the approval group that must sign off. Set On balance drift to the behaviour you want if the on-chain balance disagrees with the ledger.
2

Create the service key

In Developer, create an API key with scopes withdrawals:create and withdrawals:read, restrict it to the treasury wallet, allowlist your backend’s IP range and set an expiry. Store the secret in your secrets manager; it is shown once.
3

Request each payout with an idempotency key

POST /api/v1/wallets/{wallet_id}/request-withdrawal with asset_id, amount and recipient_address, and an X-Idempotency-Key equal to your payout’s own identifier. A retry after a timeout returns the original result instead of paying twice. Rejections come back immediately with a reason: destination not whitelisted, limit exceeded, withdrawals frozen (423).
4

Drive your state machine from events

Subscribe to withdrawal.created, withdrawal.pending_approval, withdrawal.submitted, withdrawal.confirmed, withdrawal.completed, withdrawal.failed and withdrawal.cancelled. Treat confirmed as settled. Reconcile with GET /api/v1/withdrawals/{withdrawal_id}, which carries the transaction hash and block once broadcast.
5

Rehearse the emergency stop

Confirm that an owner can reach Security & Approvals → Emergency → Freeze withdrawals quickly, and that your backend handles the 423 that follows without retrying in a loop. Unfreeze is a deliberate, audited action.

​
Considerations

  • Amounts are strings in the asset’s units; never send floating-point numbers.
  • A payout that needs approval stays pending until an approver acts in the console. Design for that latency: hold the customer-facing status at “processing” rather than failing.
  • Daily limits reset on the platform’s day boundary; size them to your real volume plus headroom, not to the maximum you could imagine paying.
  • Stablecoin payouts on EVM networks are token transfers from the same wallet and address as the native asset.