Paying Out
The order of calls for sending money from a customer's balance to a bank account or wallet.
This is a common flow. It covers the order to make the calls in, and each step links to the documentation that explains it in more detail.
There are two ways to pay out, and they differ in whose balance funds the payout.
| Paying from | Recipient registered on | Who is onboarded |
|---|---|---|
| Your own balance | Your own account | Nobody. The sender and the recipient are identified and screened |
| A customer's balance | That customer | The customer |
Paying out from your own balance
Use this when you pay out on behalf of your own users under the reliance model. The money comes from your own balance, the recipient is registered on your own account, and nobody is onboarded as a customer. None of these calls take a customerId.
1. Register the recipient.
POST /v1/linked_accounts
Send relationshipType with the country, currency, holder and identifiers, and holderType (INDIVIDUAL or BUSINESS) for a third-party recipient. A bank account is VERIFIED when you create it. A wallet reaches VERIFIED once screening clears. Register a recipient once and reuse its id. See Payout destinations.
2. Check your balance.
GET /v1/balances
Read available on the balance that will fund the payout. See Balances.
3. Quote, if the payout converts.
POST /v1/quotes
{
"fromCurrency": "USDC",
"toCurrency": "ARS",
"toAmount": "1000.00",
"chain": "SOL"
}You need a quote when your balance is a stablecoin and the recipient is paid in local currency. Set the amount on one side only:
| Send | When | What comes back |
|---|---|---|
toAmount | The recipient has to receive an exact figure | toAmount exactly as sent, and the USDC you owe in fromAmount, rounded up |
fromAmount | You want to spend a fixed amount of USDC | What the recipient will receive in toAmount |
toAmount takes at most two decimals, and it applies to payouts only, from USDC to local currency. The response carries id, fromAmount, toAmount, rate, fees[] and expiresAt. A quote lasts about two minutes and can be used once.
If the quote is refused, the specific reason is in error.details.issues[].message.
Status and code | Why |
|---|---|
400 validation_error | Both fromAmount and toAmount were sent, or neither was, or toAmount isn't a number or has more than eight decimals |
422 validation_error | toAmount is zero, has more decimals than the currency allows (two for fiat), or is below the minimum for the pair, around 14 ARS or 0.01 USDC |
422 route_unsupported | toAmount was sent on a pay-in, from local currency to USDC, or the pair couldn't be priced |
4. Instruct the payout.
POST /v1/payouts/fiat
{
"linkedAccountId": "link_...",
"amount": { "value": "1000.00", "currency": "ARS" },
"quoteId": "qte_...",
"reference": "Invoice 1042"
}amount is what the recipient receives. When you attach a quote, send the quote's toAmount as the value. Leave quoteId out when you pay from a balance already held in the payout currency. reference is shown on the transfer, and metadata takes key and value pairs that are echoed back.
5. Read it back until it completes.
GET /v1/payouts/fiat/{payoutId}
Success is transaction_status: COMPLETE with settlement_status: SETTLED. FAILED is terminal, and the funds never leave on a failure. Store the payout's id against your own reference when you create it.
Paying out from a customer's balance
The rest of this page covers payouts from the balance of a customer you onboarded.
Before you start
The customer is ACTIVE, holds the endorsement the payout needs, and has enough in available rather than in total. See Endorsements and Balances.
Paying someone other than the customer is a third party, and Alfred derives that rather than taking your word for it. See Core concepts.
The sequence
1. Register the destination.
POST /v1/customers/{customerId}/linked_accounts
Send the country, the currency and the identifiers, and leave the rail alone. Alfred derives supportedRails[] from what you sent, and derives relationship.relationship_type from the registered holder.
A destination whose route is not LIVE is refused here rather than at payout, so registering early is how you find out. See Payout destinations.
2. Wait for linked_account.updated to reach VERIFIED.
A payout to anything else is refused with recipient_not_linked before anything is locked. Handle EXPIRED as well as REJECTED, because a relationship has a validity window and a destination that worked last quarter can stop working with nobody touching it.
3. Quote, but only if you need one.
POST /v1/customers/{customerId}/quotes
You need a quote for a genuine FX pair, which means the funding balance and the destination are different fiat currencies, or the funding balance is a stablecoin and the destination is not USD.
You do not need one for a same-currency payout. An MXNa balance out to MXN over SPEI is a plain transfer with no FX leg. USDC or USDT to USD is a par redemption, where a quote is optional and only locks fees. See Quotes and pricing.
4. Instruct the payout.
POST /v1/customers/{customerId}/payouts/fiat
POST /v1/customers/{customerId}/payouts/stablecoin
You never name the balance to debit. It resolves from the customer and the quote's pair.
The rail resolves in a fixed order: the quote's rail if you passed a quote, then the body's rail, then the destination's rail if it supports only one. Whatever resolves has to be in supportedRails[] or you get rail_mismatch. If the destination supports several and neither the quote nor the body names one, the request fails on rail.
5. Wait for payout.fiat.updated.
Success is transaction_status: COMPLETE with settlement_status: SETTLED. Read both. A payout that is PROCESSING with FUNDS_EXPECTED has left and is in delivery, which is different from a payout sitting on a compliance hold. See Statuses and lifecycle.
The mistake to avoid
Quoting before the money is there. A quote carries an expiresAt of roughly two minutes. A deposit carries no deadline at all. If you quote and then wait for funds, you will re-quote. Get the funds credited, then quote, then execute.
The related version is quoting for a pair that needs no quote. A same-currency payout with a quote attached is not more correct, it is a request that can fail on an expiry it never needed.
When it goes wrong
A payout that fails leaves the funds on the balance. Fix the cause and send a new payout. Once the provider accepts a payout it cannot be canceled, so confirm the destination before you instruct. See Refunds and retries.
In sandbox
Registering a destination normally waits on a review you do not control.
POST /v1/test/linked_accounts/{linkedAccountId}/simulate_activation
This moves it straight to VERIFIED, which is the difference between testing a payout in a minute and waiting on someone else's queue. See Testing in sandbox.
Updated 11 days ago

