Skip to main content

Payouts Overview

A payout moves funds out of the authenticated user's balance to an external account. There are two kinds of payouts, and both follow the same flow and share the same concepts:

PayoutSendsGuide
Bank transferFiat currency to a bank accountBank Transfers
Crypto transferUSDT to a wallet addressCrypto Transfers

In the API, the payout type is transfer for a bank transfer and withdrawal for a crypto transfer. You will see these names in the endpoints, in the response and in the type filter when listing payouts.

withdrawal also accepts currency: "USD" for cash withdrawals, delivered in cash at physical delivery points. They use the same endpoint as crypto transfers but need no destination. The API reserves the amount plus the maximum fee (2.5%) from the balance and returns it as reservedAmount. The fee actually charged is set on approval, and any difference is refunded to the balance.


Authentication​

Payout endpoints require a valid x-api-key and a Bearer Token issued to a store role in headers.

x-api-key: <your_api_key>
Authorization: Bearer <access_token>

See the Authentication Guide to see more details.


Payout Destinations​

Every payout points to a payout destination: the account that receives the funds.

  • For a bank transfer, it holds the bank details and the beneficiary that owns the account.
  • For a crypto transfer, it holds the wallet address.

A destination can have an optional label, a friendly name that makes it easy to find later.

Two ways to set the destination​

When you create a payout, the destination is one of two shapes. They are mutually exclusive: sending id together with the account fields is rejected.

ShapeWhat you sendWhat happens
Reuse{ "id": "<destination id>" }The saved destination is used
InlineThe rail, the account identifier and the other fields the rail requiresThe matching destination is found, or created if it does not exist yet

Each rail requires different fields. Use Get the field requirements for payout destination rails to find out what each one needs before building your form.

Managing destinations on their own​

You don't have to create destinations through a payout. To keep a saved list of accounts for your users, use:

Destinations and past payouts​

Each payout keeps a snapshot of the destination as it was when the payout was created, returned in the destination field. Editing a destination later never changes the payouts that already used it.


Payout Lifecycle​

The status field of a payout progresses through the following values:

StatusDescription
pendingPayout created. Awaiting processing.
in_progressPayout is being actively processed.
sanction_reviewPayout is on hold while a compliance review is completed.
paidPayout completed successfully. Terminal state.
rejectedPayout rejected. Funds are restored. Terminal state.

When a payout is rejected and the provider reported a reason, it is returned in metadata.payoutProvider.reason.


Balance Impact​

EventEffect on Balance
Payout createdThe amount is immediately deducted from the user's available balance
Payout rejectedThe amount is automatically restored to the user's balance

For bank transfers in a currency other than USD, the amount deducted is the equivalent in USD (amountInUSD), calculated by the API at creation time.


Daily Limit​

Bank transfers and crypto transfers count toward the same daily payout limit of the store. Check how much is left with Get the daily payout limit usage. A payout that would exceed it is rejected with the PAYOUT_DAILY_LIMIT_EXCEEDED error code.


Retrieving Payouts​


Next Steps​