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:
| Payout | Sends | Guide |
|---|---|---|
| Bank transfer | Fiat currency to a bank account | Bank Transfers |
| Crypto transfer | USDT to a wallet address | Crypto Transfers |
In the API, the payout
typeistransferfor a bank transfer andwithdrawalfor a crypto transfer. You will see these names in the endpoints, in the response and in thetypefilter when listing payouts.
withdrawalalso acceptscurrency: "USD"for cash withdrawals, delivered in cash at physical delivery points. They use the same endpoint as crypto transfers but need nodestination. The API reserves the amount plus the maximum fee (2.5%) from the balance and returns it asreservedAmount. 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.
| Shape | What you send | What happens |
|---|---|---|
| Reuse | { "id": "<destination id>" } | The saved destination is used |
| Inline | The rail, the account identifier and the other fields the rail requires | The 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:
- Create a payout destination
- List payout destinations, which supports searching by
label - Get a payout destination by ID
- Edit a payout destination
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:
| Status | Description |
|---|---|
pending | Payout created. Awaiting processing. |
in_progress | Payout is being actively processed. |
sanction_review | Payout is on hold while a compliance review is completed. |
paid | Payout completed successfully. Terminal state. |
rejected | Payout 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
| Event | Effect on Balance |
|---|---|
| Payout created | The amount is immediately deducted from the user's available balance |
| Payout rejected | The 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
- Get payout by ID
- Get paginated list of payouts, which can be filtered by
type,status,currencyand creation date - Get payout by register ID
Next Steps
- Bank Transfers: send ARS, BRL, PYG, USD and EUR to a bank account
- Crypto Transfers: send USDT to a wallet