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 fromRecipient registered onWho is onboarded
Your own balanceYour own accountNobody. The sender and the recipient are identified and screened
A customer's balanceThat customerThe 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:

SendWhenWhat comes back
toAmountThe recipient has to receive an exact figuretoAmount exactly as sent, and the USDC you owe in fromAmount, rounded up
fromAmountYou want to spend a fixed amount of USDCWhat 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 codeWhy
400 validation_errorBoth fromAmount and toAmount were sent, or neither was, or toAmount isn't a number or has more than eight decimals
422 validation_errortoAmount 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_unsupportedtoAmount 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.


Did this page help you?