Pay out to a bank account

post

https://api.sandbox.alfredpay.io/v1/customers/{customerId}/payouts/fiat

Natively cross-currency. Pass a quoteId and the FX runs as an LP_EXECUTION leg inside this one PAY_OUT, alongside the FIAT_RAIL leg.

The balance to debit is inferred from the customer and the quote's pair. You never pass it. The linked account has to be VERIFIED, and its currency has to equal the quote's toCurrency.

How the rail is resolved. In order: the quote's rail if you passed a quote, then the body's rail, then the destination's rail if it only supports one. Whatever resolves has to be in the destination's supportedRails[], or you get rail_mismatch. A SPEI quote can't fund a PIX account. If the destination supports several rails and neither the quote nor the body names one, the request fails with validation_error on rail. The resolved combination of country, currency and rail has to be a LIVE route, or it's route_unsupported.

When you need a quote. Only 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 isn't USD.

A same-currency payout is a plain transfer with no FX leg and no quote. USD Corporate Account out to USD over ACH or wire is one. So is an MXNa local balance out to MXN over SPEI.

USDC or USDT going to USD is a par redemption priced from the fee table. A quote is optional there, to lock fees, and never required. No artificial conversion is ever introduced.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Path Params

customerId

string

required

Body Params

linkedAccountId

string

required

quoteId

string

Required only for a genuine FX pair (different fiat currencies, or stablecoin → non-USD fiat). Omit for a same-currency payout; optional for a USDC/USDT → USD par redemption.

rail

string

enum

Which of the destination's supportedRails to use. Required only when the destination supports more than one and no quote is passed; ignored when a quote is passed (the quote's rail governs).

Allowed:

amount

object

required

reference

string

length ≤ 140

payment_flow_id

string

metadata

object

Client-supplied key–value pairs, echoed on the object and every event about it.

Headers

Idempotency-Key

uuid

required

Required on every state-changing POST, simulators included; the only exempt POST is …/verifications/preflight.
Replay (same key, same body) returns the original response with Idempotent-Replayed: true; same key with a
different body → 409 idempotency_conflict. Keys are UUIDs, scoped to the API key, retained for 24 hours.

Responses

Language

Credentials

Loading…

Response

Click Try It! to start a request and see the response here! Or choose an example:

application/json

201Created

202Accepted but routed to policy review, so PENDING_COMPLIANCE with PAUSED.

403endorsement_not_enabled, for example fiat_payout.cross_border.

409recipient_not_linked (linked account not VERIFIED), quote_expired, quote_consumed, or rail_mismatch (the rail is not in the destination's supportedRails).

422insufficient_balance, currency_mismatch, route_unsupported (the resolved route is not LIVE), or validation_error on rail when the destination supports several and none was named. All of these fail before any balance is locked.