Skip to main content
In a third-party flow, the beneficiary is a different legal entity from the sender, or you collect and move money on behalf of someone else. These flows need more scoping than first-party ones: who each party is, which account type sends, and whether the beneficiary’s market has a rail.
One-time bank and QR payments are available to individual accounts only, in Vietnam, the Philippines and, for QR, Kenya. There is no third-party bank transfer in the United States. A business account pays third parties in stablecoin; its bank access is limited to its own US linked bank and a US dollar on-ramp account. See Supported regions and currencies.
Moving money between an account holder’s own bank and their own wallet? Use First-party flows instead.

​
Scoping output

Before building, agree on:
  • The customer of record for each party, and its subjectType. It cannot be changed after creation
  • The sender and the beneficiary
  • The funds owner at each step, and who signs from the wallet that funds sends
  • Whether your platform gives its own customers accounts
  • The beneficiary’s rail and market: a bank, a merchant QR code, a wallet, an account or a handle
  • The pattern
  • The support owner: who handles rejected verification, expired quotes and payments that need intervention
  • The reference you reconcile against, carried on each payment as externalReference

​
Choose your pattern

Pay local currency to someone else

A one-time bank transfer or a local merchant QR payment, funded from stablecoin.

Pay in stablecoin

Pay a wallet, another account or a handle, including another partner’s, with no verification.

Collect for a merchant

Payers pay a merchant account you keep; the net lands where the merchant chose.

Acquirer or PSP, sub-merchant balances

Convert intermediary settlement balances into stablecoin, under an agreement.

Platform serves its customers

Give each of your customers their own account, verified and run from your backend.

​
Pattern: Pay local currency to someone else

Use when: a sender pays a supplier, contractor or other beneficiary’s bank account once, or pays a local merchant through its QR code. Signals:
  • The beneficiary is not the same legal entity as the sender
  • The beneficiary receives local currency, not stablecoin
  • The payment is one-off: nothing is saved for the next one
1

Create and verify the sender

POST /v2/accounts with subjectType: "individual". The sender verifies their email, then their identity with POST /v2/accounts/{accountId}/kyc/session. See Individual KYC and Start KYC.
2

Confirm the rail is enabled

capabilities.payments.methods.externalBank.available or capabilities.payments.methods.externalQr.available in GET /v2/partners/config. Where your banking program covers the bank rail, also activate bank_payout. See Get configuration and Capability activation.
3

Set the payment source

PUT /v2/accounts/{accountId}/payment-source names the wallet or Vault that funds the payout. See Set payment source.
4

Look up the bank code

For a bank beneficiary, GET /v2/payments/external-bank/banks?country=VN lists the accepted codes. Pass the selected code unchanged in destination.bankCode. See Beneficiary banks.
5

Create the payment

POST /v2/payments with intent: "send", an Idempotency-Key, deliver_exact and a fiat amount: what the beneficiary receives. These destinations are quoted at creation, not in preview. See Off-ramps and Create payment.
6

Fund it before the quote expires

When nextAction.type is transaction with depositInstructions, send exactly that amount to that address before funding.quoteExpiresAt. An expired quote is terminal and cannot be re-priced. See Fund a fiat send before its quote expires.
7

Read the payment

GET /v2/payments/{paymentId} until status is terminal. offrampStatus reports the external payout and operationalState reports health. See Get payment.
A send cannot be cancelled. Do not create a second payment for the same obligation: only a genuinely terminal failed or expired payment is replaced, with a new key. See Never replace a stuck payment.
Stableyard enables: your organization’s KYB, Identity & KYC, External Bank Transfer for Vietnam and the Philippines, and the external QR rail reported at capabilities.payments.methods.externalQr.

​
Pattern: Pay in stablecoin

Use when: the beneficiary accepts stablecoin: a supplier’s wallet, another of your customers by handle, or an account that belongs to another partner. Signals:
  • Value stays in stablecoin end to end
  • The beneficiary is a wallet address, an account or a payment handle
  • Either account type can send, with no verification
1

Set the payment source

PUT /v2/accounts/{accountId}/payment-source names the connected wallet or Vault that funds sends. See Sending payments.
2

Preview the send

POST /v2/payments/preview. Proceed only when the funding option for your source reports available: true; otherwise show unavailableReason. See Preview payment.
3

Create the payment

POST /v2/payments with an Idempotency-Key. For upa and payment_handle, the recipient’s settlement profile decides the chain and asset, and a recipient with no active settlement destination is refused. See Create payment.
4

Confirm the returned action

POST /v2/payments/{paymentId}/confirm with the proof nextAction.type names: a transaction hash, or managed_authorization for a Vault. See Confirm payment.
5

Read the payment

A successful confirm is not settlement. Read GET /v2/payments/{paymentId} until status is terminal. See Get payment.
You can pay another partner’s qualified handle but cannot look it up through the authenticated API first, so confirm it with your customer before sending. Only participants your organization owns are returned on the payment. See Stablecoin transfers.

​
Pattern: Collect for a merchant

Use when: payers pay merchants, sellers or other counterparties whose accounts you keep, and each one’s net lands at the destination its own account chose. Signals:
  • You collect on behalf of a counterparty and deliver their share
  • Each merchant chooses where its money lands; the payer chooses only how to pay
  • Payers may hold stablecoin, or only fiat where fiat at checkout is enabled
1

Create the merchant account

POST /v2/accounts with the merchant’s wallet, and optionally a displayProfile. See Create account.
2

Set the merchant's destination

GET /v2/accounts/{accountId}/settlement-destinations, offer only destinations where capabilities.settlementSupported is true, then PUT /v2/accounts/{accountId}/settlement-profile. See Merchant settlement and Set preference.
3

Create one receive payment per obligation

POST /v2/payments with intent: "receive", the merchant as recipient and your externalReference. The settlement destination and fees are frozen onto the payment at creation. See Create payment.
4

Send the payer to checkout

The payer opens checkout.paymentUrl, which presents the methods that payment supports, including fiat at checkout where it is enabled for your app and the payer’s market. Keep checkout.clientSecret out of logs and URLs. See Depositing funds.
5

Read the payment

accepted means the payer’s funds were verified; succeeded means the merchant’s destination was credited with fees.merchantNetAmountAtomic. See Settlement lifecycle and Get payment.
To let payers start a payment themselves, enable the merchant’s public payment page with PUT /v2/accounts/{accountId}/payment-acceptance. It needs an active qualified handle, an eligible preferred settlement destination and an enabled app-level public payment policy. See Public payment acceptance and Update payment acceptance. Merchants settle in stablecoin to a connected wallet. A merchant’s bank account cannot receive settlement yet.

​
Pattern: Acquirer or PSP, sub-merchant balances

Use when: a PSP or platform converts balances held in an intermediary settlement account for its sub-merchants into stablecoin.
1

Classify the flow

Classification is made strictly on the processing flow, not on intent or contract wording: who owns the account the funds sit in, whether an intermediary settlement account is involved, and at what point stablecoin is minted. An intermediary account holding sub-merchant balances is third-party. See Acquirer and PSP settlement.
2

Agree the terms with Stableyard

The classification decides which review applies and whether the flow is eligible at all. The funding arrangement, the eligible currencies and the approved destinations are named in your agreement.
There is no public endpoint that creates an acquirer settlement, and nothing is switched on self-serve. Balances from processing accounts you own are a first-party flow.

​
Pattern: Platform serves its customers

Use when: your product gives each of its own customers a Stableyard account: a wallet or fintech serving people, or a platform serving companies. The money movements are the patterns on this page and on First-party flows, run per customer account. The gates, steps and coverage for each platform shape are on Choose your pattern.

Embedded ramps for individuals

People fund from a US bank and cash out to their own bank, inside your app.

Platform for business customers

Companies get US bank access through your product after hosted verification.

Crypto-only payouts

Stablecoin to wallets, accounts and handles, with no verification.

​
Blockers to check before building

​
Before go-live

Staging has no simulator, and some corridors cannot be rehearsed end to end outside production, so your first production payout on a corridor is also its first real test. Production re-creates accounts and verification. See Going live.

​
Go deeper

Off-ramps

Pay out local currency to a bank or a local merchant.

Stablecoin transfers

Send to a wallet, or to another account by id or handle.

Merchant settlement

Deliver collected value to the destination a merchant chose.

First-party flows

When one legal entity owns both ends of the movement.