Overview
Create and track outgoing crypto transfers, fees, failures, and reversals.
A payout sends funds from your merchant balance to a destination wallet. Submit it from your server with payouts:write and a persisted idempotency key.
Create a payout#
Provide currency, network, amount, destination, and beneficiary_type. Add destination_tag when the receiving network or wallet requires a memo/tag. Optional fields include description and string-valued metadata.
Use a supported pair and validate the destination with the recipient. A syntactically valid string can still be rejected by the selected network with 422 unprocessable_entity. Example addresses in these docs are placeholders; replace them before sending a real request.
A successful creation returns 201 with status: queued; funds are reserved. Save the payout ID. There is no merchant external_id field for payouts; use metadata, which is returned on the payout representation.
Who receives the funds#
Every payout declares who owns the destination wallet. Send beneficiary_type with one of two values:
| Value | Meaning |
|---|---|
self | Your own wallet, or your own account at an exchange |
third_party | A wallet that belongs to someone else: a customer, a partner, a payroll recipient |
The field is required on every creation request and has no default. A body without it is rejected with 400 validation_error, and so is any value outside the two above. The platform stores the value you declare and returns it on the payout object; it is fixed once the payout is created.
Declaring third_party does not change how the payout executes. Nothing is rejected, delayed, or verified differently because of this value today. It is used for compliance handling of transfers, where a transfer to your own wallet and a transfer to someone else's wallet are handled differently. You are the only party who can state which one it is, so declare it truthfully.
Payout statuses#
| Status | Meaning |
|---|---|
queued | Accepted and waiting for execution |
processing | Execution is underway or its outcome still needs resolution; funds remain reserved |
confirming | Broadcast and awaiting sufficient confirmation |
completed | Transfer confirmed |
failed | Transfer failed and its reservation was released |
reversed | A previously completed transfer disappeared from the canonical chain and funds were restored |
The schema retains cancelled for compatibility, but individual payout rows do not enter that status. There is no payout cancellation endpoint. executable_at, when present, is the earliest execution time, not a guarantee of completion at that instant.
Amounts and fees#
amount is the requested principal, recipient_amount is sent on-chain, and target_funding_amount is the target-denominated obligation. The allocation fields show who pays each commercial charge. balance_movements records the effect on each participating currency and network; there is no scalar merchant debit field.
configured_network_fee_amount is a quoted commercial charge in payout currency. Actual network_fee is reported separately with its own currency and network after it is measured. Do not add that actual cost to the target obligation. A payout can also be funded from another balance — see below and amounts.
Funding from other balances#
By default a payout is paid from the balance of its own currency and network. Support can additionally allow funding from other balances, separately for Test and Live; without that grant only the payout's own balance is used.
Set the saved policy in the dashboard's payout funding settings, or send the optional funding override in Create. funding.mode is one of:
| Mode | Behavior |
|---|---|
same_asset_only | Use only the payout currency and network balance |
source_only | Use one explicit source balance named in funding.source |
target_first | Use the payout balance first, then eligible other balances |
funding.source is required only for source_only; send null otherwise. Anything outside the grant is refused with 422 funding_not_granted. Other refusals are funding_balance_insufficient, funding_route_unavailable, funding_allocation_limit, funding_conversion_fee_payer_invalid, and 409 funding_policy_conflict / funding_grant_conflict when the policy or grant changed before acceptance. A refused payout is not created. See errors.
While funding converts, the payout stays processing; funding.status shows converting, needs_review, ready, or closed. funding is null for a payout paid from its own balance. When present, funding.sources lists each source with its own amounts in its own currency and network — never sum different assets. A failed payout does not undo a conversion that already completed, so check acquired funds before creating another payout.
Notifications and retries#
Subscribe to payout.completed, payout.failed, and payout.reversed; their payloads use schema_version 2 and carry all native balance movements. Reject an unfamiliar schema_version explicitly. No payout.created or intermediate-status event is published; use the create response and GET while it is processing.
If the create request times out, retry the same key and body. A new payout after a confirmed terminal failure is a new business decision and needs a new key. Check the current payout before retrying a failed or reversed transfer so the recipient is not paid twice.