Pick the destination
Corridors are enabled per market and per app, and the destination types differ by market. Kenya, for example, has local payment methods but no bank rail. View supported regions and currencies →
QR market availability
The QR catalog includes PH/PHP, VN/VND, ID/IDR, KE/KES, BR/BRL, CO/COP, PE/PEN and TH/THB. UseGET /v2/partners/config for your app’s enabled markets; catalog support
alone does not make a route executable. Stableyard operations selects the
provider. Your request body and Payment lifecycle remain the same when that
selection changes. Bank-transfer coverage is configured separately.
Each enabled market reports currencyDecimals, and minimumAmountAtomic /
maximumAmountAtomic when limits apply, both in that precision. IDR uses whole
rupiah (currencyDecimals: 0) and has a 20,000 IDR minimum, so send
"amount": "50000", not "50000.00".
Existing Payments retain their original route and quote. Retry an uncertain
request with its original idempotency key and follow its nextAction; never
start a duplicate payout because the market configuration changed. A QR decode
preview may require account readiness again after a route change. Refresh
capabilities when a market becomes unavailable.
For an external_qr payment, select Arbitrum One USDC directly, or a linked
Base USDC connected wallet when Base routing is enabled for the environment.
Base funding creates a source-bound Routing order and collects the output into
the Payment’s Arbitrum One escrow before the QR provider can pay. It needs a
provider-confirmed quote expiry and can be unavailable if the remaining quote
window is too short. Other networks, Base Vault funding and Arbitrum Sepolia
are not executable sources for this rail. Setting a Payment Source alone does
not move funds or verify its balance.
For a connected-wallet QR Payment, fund only from the wallet selected at
creation. A transfer from another address is recorded in escrow for manual
recovery and does not start the merchant payout. Use the source-bound hosted
checkout when possible; if you present deposit instructions yourself, show
this source-wallet requirement alongside the amount, token and expiry.
Create the payout
UsePOST /v2/payments with intent: "send" and a stable Idempotency-Key. /v2/payments/preview supports crypto destinations only; it rejects external_bank, bank_account and external_qr. One-time bank and QR routes return a quote at creation.
quoteExpiresAt. An expired payout quote cannot be refreshed on the same Payment. Read the original Payment and reconcile any funds sent before starting a new attempt with a new key after it is terminal. See Fund a fiat send before its quote expires.
US linked-bank payout
Use a bank already linked under the sending UPA. US linked-bank payouts are available in sandbox; contact Stableyard for production. US one-timeexternal_bank payments and settlement into a linked bank are not supported.
- Read
GET /v2/partners/configfor the app’s bank access and payment permissions. - Activate
linked_bankfor the intended US/USD rail and wait for account-level approval fromGET /v2/accounts/{accountId}/capabilities. - Read bank-account requirements, link the beneficiary, and wait until the returned bank is
active. - Configure the sender’s supported Payment Source.
- Create the Payment using the returned
bankAccountIdand an exact crypto input.
0.50 USD, Fedwire 10.00 USD) is added on top, so the payment collects the amount plus the rail fee; see linked bank rail fees. The final USD delivery and conversion cost are confirmed only at settlement, so this does not promise a fixed dollar amount. Preserve the precision returned by the API. See amount semantics.
Complete the returned checkout funding action and follow its selected option’s confirmationMode. Escrow funding is not submitted through the outgoing /confirm endpoint. Reconcile GET /v2/payments/{paymentId} and signed payment.* events until a terminal outcome, checking operationalState separately.
The coverage page lists where US bank payouts are available. In sandbox, use the sandbox base URL, sandbox accounts and the supported test network.
Link a bank before paying it
Linking needs linked-bank access enabled for your app. Anindividual account needs an approved identity check. A business account can link a US dollar bank after hosted KYB, and no other country.
Read GET /v2/accounts/{accountId}/bank-account-requirements for the fields and availability, then POST /v2/accounts/{accountId}/bank-accounts. A linked bank is not a payout destination until it is verified and active.
Business bank access
Abusiness account starts hosted verification with a capability activation and a stable Idempotency-Key.
business.legalName only on the first application, or when replaying that exact request after an interruption. Then act on nextAction.type:
The hosted form collects company, ownership, document and consent details, and banking is enabled only after the application is approved. Read
GET /v2/accounts/{accountId}/capabilities after verification and wait for ready: true.
To fund in US dollars as well, activate bank_onramp on the same approved relationship; business can be left out once the application exists. Your app must be enabled for each service; GET /v2/partners/config shows what is enabled.
In the partner dashboard, the same flow is under Accounts → an account → Banking: start or resume KYB, set up US dollar funding, reveal bank instructions, and send to verified US linked banks. Link the bank itself under Settlement once approved.
Next: Transactions
The ledger rows every payment leg writes.
Saved third-party bank beneficiaries
Individual UPAs can save PH/PHP and VN/VND bank recipients for repeat payments.POST /v2/accounts/{accountId}/beneficiaries requires v2:accounts, the app’s
external-bank entitlement and an Idempotency-Key. Send label, country,
currency, bankCode, accountNumber and beneficiaryName. Read bank codes
from GET /v2/payments/external-bank/banks?country=PH (or VN).
Listing and reading return masked records. Saving does not approve the recipient
or send money. To pay, use POST /v2/payments with
destination: { type: "beneficiary", beneficiaryId: "beneficiary_..." }, the owning
sender UPA, amountMode: "deliver_exact", and the matching fiat payment amount.
The current external-bank flow rechecks compliance, routing and provider evidence.
Continue using the returned Payment’s funding action and status.
Details are immutable. Disable with
DELETE /v2/accounts/{accountId}/beneficiaries/{beneficiaryId} and save a replacement.
Disabling blocks new Payments and purges the saved encrypted details; existing
Payments retain their frozen destination for reconciliation. Exact create and
Payment retries retain their original idempotency identity.
This feature does not add USD, INR or AED third-party beneficiary support.
Business-owned linked banks and reusable USD funding accounts remain separate.