> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stableyard.fi/llms.txt
> Use this file to discover all available pages before exploring further.

# Third-party flows

> Pay or collect for someone else, or run accounts for your own customers, and what each flow needs.

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.

<Warning>
  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](/supported-regions-and-currencies#fiat-payout).
</Warning>

<Note>
  Moving money between an account holder's own bank and their own wallet? Use [First-party flows](/guides/first-party-flows) instead.
</Note>

## 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

<CardGroup cols={3}>
  <Card title="Pay local currency to someone else" icon="arrow-up-from-line" href="#pattern-pay-local-currency-to-someone-else">
    A one-time bank transfer or a local merchant QR payment, funded from stablecoin.
  </Card>

  <Card title="Pay in stablecoin" icon="coins" href="#pattern-pay-in-stablecoin">
    Pay a wallet, another account or a handle, including another partner's, with no verification.
  </Card>

  <Card title="Collect for a merchant" icon="store" href="#pattern-collect-for-a-merchant">
    Payers pay a merchant account you keep; the net lands where the merchant chose.
  </Card>

  <Card title="Acquirer or PSP, sub-merchant balances" icon="building-columns" href="#pattern-acquirer-or-psp-sub-merchant-balances">
    Convert intermediary settlement balances into stablecoin, under an agreement.
  </Card>

  <Card title="Platform serves its customers" icon="layer-group" href="#pattern-platform-serves-its-customers">
    Give each of your customers their own account, verified and run from your backend.
  </Card>
</CardGroup>

| Pattern | Signals | Primary scoping focus |
| - | - | - |
| [Pay local currency to someone else](#pattern-pay-local-currency-to-someone-else) | A different person or business receives local currency | The sender is an `individual`; the beneficiary's market |
| [Pay in stablecoin](#pattern-pay-in-stablecoin) | The beneficiary takes stablecoin at a wallet, an account or a handle | Who signs; confirming a handle you cannot look up |
| [Collect for a merchant](#pattern-collect-for-a-merchant) | Payers pay counterparties whose accounts you keep | The merchant's destination; which status releases goods |
| [Acquirer or PSP, sub-merchant balances](#pattern-acquirer-or-psp-sub-merchant-balances) | Balances sit in an intermediary settlement account | Classification and a commercial agreement |
| [Platform serves its customers](#pattern-platform-serves-its-customers) | Each of your customers needs their own identity, history and destinations | Customer of record and verification per account |

## 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

| Party | Confirm before building |
| - | - |
| Sender | An `individual` account with approved identity verification. A `business` account cannot send this payment |
| Beneficiary | Needs no Stableyard account. Identified by bank code and account number, or by the merchant's QR payload |
| Funds owner | The sender's payment source, a connected wallet or a Vault. Whoever controls it signs |
| Support owner | Who tells the sender what happens when a quote expires or a payout needs review |

| Beneficiary | `destination.type` | Request fields | Markets |
| - | - | - | - |
| A bank account, once | `external_bank` | `country`, `bankCode`, `accountNumber`. `beneficiaryName` is required for `PH` and optional for `VN` | Vietnam, Philippines |
| A local merchant's QR code | `external_qr` | `country`, `qrPayload`. A personal QR code is refused | Vietnam, Philippines, Kenya |

<Steps>
  <Step title="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](/concepts/individual-kyc) and [Start KYC](/api-reference/kyc/create-kyc-session).
  </Step>

  <Step title="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](/api-reference/configuration/get-partner-config) and [Capability activation](/concepts/capability-activation).
  </Step>

  <Step title="Set the payment source">
    `PUT /v2/accounts/{accountId}/payment-source` names the wallet or Vault that funds the payout. See [Set payment source](/api-reference/settlement/set-payment-source).
  </Step>

  <Step title="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](/api-reference/payments/list-beneficiary-banks).
  </Step>

  <Step title="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](/payments/off-ramps) and [Create payment](/api-reference/payments/create-payment).
  </Step>

  <Step title="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](/payments/sending-payments#fund-a-fiat-send-before-its-quote-expires).
  </Step>

  <Step title="Read the payment">
    `GET /v2/payments/{paymentId}` until `status` is terminal. `offrampStatus` reports the external payout and `operationalState` reports health. See [Get payment](/api-reference/payments/get-payment).
  </Step>
</Steps>

<Warning>
  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](/payments/sending-payments#never-replace-a-stuck-payment).
</Warning>

**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

| Party | Confirm before building |
| - | - |
| Sender | Any `individual` or `business` account. No verification is needed |
| Beneficiary | A wallet address, an account in your namespace, or another partner's account by qualified handle |
| Wallet controller | Who signs from the payment source, or whether a Vault authorizes sends without a per-send signature |

| Beneficiary | `destination.type` | Address it by |
| - | - | - |
| A wallet | `crypto_wallet` | `chainId`, `address`, `assetCode` |
| An account in your namespace | `upa` or `payment_handle` | `accountId` or `externalUserId`, or its handle |
| An account belonging to another partner | `payment_handle` | Its qualified handle, `name@namespace` |

<Steps>
  <Step title="Set the payment source">
    `PUT /v2/accounts/{accountId}/payment-source` names the connected wallet or Vault that funds sends. See [Sending payments](/payments/sending-payments#set-a-payment-source-first).
  </Step>

  <Step title="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](/api-reference/payments/preview-payment).
  </Step>

  <Step title="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](/api-reference/payments/create-payment).
  </Step>

  <Step title="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](/api-reference/payments/confirm-payment).
  </Step>

  <Step title="Read the payment">
    A successful confirm is not settlement. Read `GET /v2/payments/{paymentId}` until `status` is terminal. See [Get payment](/api-reference/payments/get-payment).
  </Step>
</Steps>

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](/payments/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

| Party | Confirm before building |
| - | - |
| Merchant | One account per merchant. Receiving stablecoin needs no verification. A `displayProfile` sets how payers see it |
| Payer | Anyone with the payment link. Payers never see the merchant's wallet address or bank details |
| Destination owner | The merchant, through its settlement profile. Nothing a payer does can move it |
| You | Which status releases goods or credits the merchant in your product |

<Steps>
  <Step title="Create the merchant account">
    `POST /v2/accounts` with the merchant's wallet, and optionally a `displayProfile`. See [Create account](/api-reference/accounts/create-account).
  </Step>

  <Step title="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](/settlement/merchant-settlement) and [Set preference](/api-reference/settlement/set-settlement-profile).
  </Step>

  <Step title="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](/api-reference/payments/create-payment).
  </Step>

  <Step title="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](/payments/depositing-funds#collect-a-known-amount-with-a-hosted-payment-page).
  </Step>

  <Step title="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](/settlement/receiving-settlement) and [Get payment](/api-reference/payments/get-payment).
  </Step>
</Steps>

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](/concepts/wallets-and-handles#public-payment-acceptance) and [Update payment acceptance](/api-reference/payment-handles/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.

<Steps>
  <Step title="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](/settlement/acquirer-psp-settlement#where-the-funds-originate-decides-the-review-path).
  </Step>

  <Step title="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.
  </Step>
</Steps>

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](/guides/first-party-flows#pattern-acquirer-or-psp-own-merchant-accounts).

## 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.

| Party | Confirm before building |
| - | - |
| Customer of record | Each of your customers is its own account, keyed by your `externalUserId`. Your own company is Your Business UPA, not one of them |
| Verification | Each `individual` verifies email and identity; each `business` completes hosted business verification through its authorized representative |
| Wallet controller | Your customer, or your platform if you provide the wallet |
| Support owner | Who handles rejected verification, expired links and payments that need intervention |

The money movements are the patterns on this page and on [First-party flows](/guides/first-party-flows), run per customer account. The gates, steps and coverage for each platform shape are on [Choose your pattern](/white-label/patterns).

<CardGroup cols={3}>
  <Card title="Embedded ramps for individuals" icon="mobile" href="/white-label/patterns#pattern-embedded-ramps-for-individuals">
    People fund from a US bank and cash out to their own bank, inside your app.
  </Card>

  <Card title="Platform for business customers" icon="building" href="/white-label/patterns#pattern-platform-for-business-customers">
    Companies get US bank access through your product after hosted verification.
  </Card>

  <Card title="Crypto-only payouts" icon="wallet" href="/white-label/patterns#pattern-crypto-only-payouts">
    Stablecoin to wallets, accounts and handles, with no verification.
  </Card>
</CardGroup>

## Blockers to check before building

| Blocker | Why it matters |
| - | - |
| A `business` sender on a bank or QR payout | Not available to business accounts, and `subjectType` cannot be changed |
| No rail in the beneficiary's market | The United States has no third-party bank transfer, and Kenya has no bank rail |
| Rail not enabled for your app | `externalBank` or `externalQr` reports `available: false` in `GET /v2/partners/config` |
| Sender not verified | The payment's `nextAction` names what is owed, such as `start_kyc_session` or `verify_account_email` |
| Quote expired | `payment_quote_expired` is terminal; the next attempt is a new payment with a new key |
| Handle you cannot verify | Another partner's handle cannot be looked up first; confirm it with your customer |
| Merchant without an active destination | A receive payment naming the account is refused at creation |
| Bank chosen as a settlement destination | Refused with `payment_method_not_supported`; settlement runs to a crypto wallet |
| Acquirer flow assumed to be self-serve | It has no public endpoint and is agreed commercially |

## 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](/white-label/going-live).

## Go deeper

<CardGroup cols={2}>
  <Card title="Off-ramps" icon="arrow-up-from-line" href="/payments/off-ramps">
    Pay out local currency to a bank or a local merchant.
  </Card>

  <Card title="Stablecoin transfers" icon="coins" href="/payments/stablecoin-transfers">
    Send to a wallet, or to another account by id or handle.
  </Card>

  <Card title="Merchant settlement" icon="store" href="/settlement/merchant-settlement">
    Deliver collected value to the destination a merchant chose.
  </Card>

  <Card title="First-party flows" icon="user" href="/guides/first-party-flows">
    When one legal entity owns both ends of the movement.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.