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

# First-party flows

> Fund, withdraw, top up and settle when one legal entity owns both ends of the movement.

In a first-party flow, the account money leaves or is collected into and the destination it reaches belong to the same legal entity: your own business, or one customer acting for itself. To run these patterns for many customers inside your product, pair them with [Platform serves its customers](/guides/third-party-flows#pattern-platform-serves-its-customers).

<Note>
  Paying someone else's bank, wallet or handle, or collecting for a merchant? Use [Third-party flows](/guides/third-party-flows) instead.
</Note>

## Scoping output

Before building, agree on:

* The legal entity that owns both ends, and its account: [Your Business UPA](/universal-payment-account#your-business-upa), or one customer's account
* `subjectType`, `individual` or `business`. It cannot be changed after creation
* The motion: fund, withdraw, top up, settle, or several
* The pattern
* Market, currency and rail for any bank leg
* Chain and stablecoin for the wallet leg
* Who signs from the wallet. Stableyard never signs for a connected wallet
* What finance reconciles against: payment ids and `externalReference`, deposits, or on-ramp funding transactions

## Choose your pattern

<CardGroup cols={3}>
  <Card title="Fund from your own bank" icon="building-columns" href="#pattern-fund-from-your-own-bank">
    US bank details in the holder's name. Every transfer in arrives as stablecoin in their wallet.
  </Card>

  <Card title="Withdraw to your own bank" icon="money-check" href="#pattern-withdraw-to-your-own-bank">
    A payout from the holder's wallet to a bank account they linked and verified.
  </Card>

  <Card title="Top up with stablecoin" icon="qrcode" href="#pattern-top-up-with-stablecoin">
    A permanent deposit address. Any amount, any time, settled to the holder's destination.
  </Card>

  <Card title="Settle your own revenue" icon="vault" href="#pattern-settle-your-own-revenue">
    Collect for your own business and settle the net into a wallet or Vault you control.
  </Card>

  <Card title="Acquirer or PSP, own merchant accounts" icon="store" href="#pattern-acquirer-or-psp-own-merchant-accounts">
    Convert local-currency balances from processing accounts you own, under an agreement.
  </Card>
</CardGroup>

| Pattern | Signals | Primary objects |
| - | - | - |
| [Fund from your own bank](#pattern-fund-from-your-own-bank) | Repeated USD funding from the holder's own bank; no call per transfer | [Account](/universal-payment-account), connected wallet, [`bank_onramp`](/concepts/capability-activation), [on-ramp account](/concepts/on-ramp-accounts) |
| [Withdraw to your own bank](#pattern-withdraw-to-your-own-bank) | Cash-out to a bank the holder owns; each withdrawal started explicitly | Account, [`linked_bank`](/concepts/capability-activation), [bank account](/concepts/bank-accounts), [payment](/concepts/payments) |
| [Top up with stablecoin](#pattern-top-up-with-stablecoin) | Repeated stablecoin arrivals of any amount; no order per arrival | Account, [settlement destination](/settlement/destinations), [deposit address](/concepts/deposit-addresses) |
| [Settle your own revenue](#pattern-settle-your-own-revenue) | Your own account collects; you choose where the net lands | Your Business UPA, settlement profile, receive payment, Vault |
| [Acquirer or PSP, own merchant accounts](#pattern-acquirer-or-psp-own-merchant-accounts) | Local-currency settlement balances in processing accounts you own | A commercial agreement. No public endpoint |

## How the money moves

<Tabs>
  <Tab title="Fund">
    ```mermaid theme={null}
    flowchart LR
      B["Holder's US bank"] -->|"ACH, Fedwire or FedNow"| O["On-ramp account"]
      O -->|"converted by a banking partner"| W["Holder's wallet<br/>USDC or USDT"]
    ```
  </Tab>

  <Tab title="Withdraw">
    ```mermaid theme={null}
    flowchart LR
      W["Holder's wallet"] -->|"exact deposit"| E["Payment escrow"]
      E -->|"verified, then paid out by a banking partner"| L["Holder's linked US bank"]
    ```
  </Tab>

  <Tab title="Top up">
    ```mermaid theme={null}
    flowchart LR
      S["Holder's other wallet"] -->|"stablecoin"| D["Deposit address"]
      D -->|"settled, net of fees"| W["Holder's settlement destination"]
    ```
  </Tab>

  <Tab title="Settle">
    ```mermaid theme={null}
    flowchart LR
      P["Payer"] -->|"receive payment"| A["Your account"]
      A -->|"verified, net of fees"| T["Your wallet or Vault"]
    ```
  </Tab>
</Tabs>

## Pattern: Fund from your own bank

**Use when:** the account holder funds their account repeatedly by bank transfer from a bank they already use, and the money should arrive as stablecoin in their own wallet.

**Signals:**

* The holder saves the same bank details as a payee and reuses them
* No API call should fire per transfer
* The destination is a connected wallet on the same account

<Steps>
  <Step title="Create the account">
    `POST /v2/accounts` with `subjectType` and the holder's wallet. See [Universal Payment Account](/universal-payment-account) and [Create account](/api-reference/accounts/create-account).
  </Step>

  <Step title="Verify the holder">
    An `individual` verifies their email, then their identity with `POST /v2/accounts/{accountId}/kyc/session`. A `business` completes hosted business verification, started by its first activation. See [Onboarding overview](/concepts/onboarding).
  </Step>

  <Step title="Activate bank_onramp">
    `POST /v2/accounts/{accountId}/capability-activations` with `capability: "bank_onramp"`. Open `nextAction.url` for the holder, then wait for `ready: true` in `GET /v2/accounts/{accountId}/capabilities`. See [Capability activation](/concepts/capability-activation) and [Activate capability](/api-reference/capabilities/activate-capability).
  </Step>

  <Step title="Check what can be issued">
    `GET /v2/accounts/{accountId}/onramp-bank-account-requirements`. Continue only on `available: true`, and choose the wallet and asset from its `destinations`. See [On-ramp accounts](/concepts/on-ramp-accounts#check-what-can-be-issued).
  </Step>

  <Step title="Issue the on-ramp account">
    `POST /v2/accounts/{accountId}/onramp-bank-accounts` with an `Idempotency-Key`. The wallet and asset are fixed once issued. See [Issue on-ramp account](/api-reference/onramp-accounts/issue-onramp-account).
  </Step>

  <Step title="Show the deposit instructions">
    `GET /v2/accounts/{accountId}/onramp-bank-accounts/{onrampBankAccountId}/deposit-instructions` is the only response with the full account number. Show it to the holder; never log, cache or store it. See [Deposit instructions](/api-reference/onramp-accounts/get-deposit-instructions).
  </Step>

  <Step title="Track each transfer">
    Every transfer in is one funding transaction, listed by `GET /v2/accounts/{accountId}/onramp-bank-accounts/{onrampBankAccountId}/transactions`. `bank_funding.completed` and `bank_funding.failed` prompt you to read it. See [Funding transactions](/api-reference/onramp-accounts/list-funding-transactions).
  </Step>
</Steps>

<Warning>
  On-ramp accounts are US dollars only, over ACH, Fedwire and FedNow. Issuance is certified on staging and not yet proven in production. An account holds one on-ramp account per banking partner, and an issued one cannot be re-pointed to another wallet or asset.
</Warning>

**Stableyard enables:** your organization's KYB, the on-ramp with a US banking program, and `bank_onramp` on that program. See [Going live](/white-label/going-live#what-stableyard-must-enable).

## Pattern: Withdraw to your own bank

**Use when:** the account holder cashes out stablecoin to a bank account they already hold, and each withdrawal is started explicitly.

**Signals:**

* The bank is in the holder's own name. Paying anyone else's bank is a [third-party flow](/guides/third-party-flows#pattern-pay-local-currency-to-someone-else)
* Each withdrawal is one payment with its own id and result
* The holder's wallet holds the stablecoin, and someone can sign from it

<Steps>
  <Step title="Create the account with a wallet">
    `POST /v2/accounts` with `wallets`. See [Create account](/api-reference/accounts/create-account).
  </Step>

  <Step title="Verify the holder">
    An `individual` needs approved identity verification. A `business` starts hosted business verification by activating `linked_bank` with `business.legalName`, and can then link a US bank only. See [Business bank access](/payments/off-ramps#business-bank-access).
  </Step>

  <Step title="Activate linked_bank">
    `POST /v2/accounts/{accountId}/capability-activations` with `capability: "linked_bank"`, then wait for `ready: true`. See [Capability activation](/concepts/capability-activation).
  </Step>

  <Step title="Link the bank">
    Read `GET /v2/accounts/{accountId}/bank-account-requirements`, render the country's `schema`, then `POST /v2/accounts/{accountId}/bank-accounts`. Wait for the bank's `status` to be `active`. See [Bank accounts](/concepts/bank-accounts), [Bank requirements](/api-reference/bank-accounts/get-bank-account-requirements) and [Link bank account](/api-reference/bank-accounts/link-bank-account).
  </Step>

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

  <Step title="Create the withdrawal">
    `POST /v2/payments` with `intent: "send"`, `destination.type: "bank_account"`, `collect_exact` and a crypto amount, or `deliver_exact` and a fiat amount where the route offers a locked quote. Under `collect_exact` the final dollar figure is known only when the provider settles, so do not promise one. See [Sending payments](/payments/sending-payments#create-the-payment) and [Create payment](/api-reference/payments/create-payment).
  </Step>

  <Step title="Fund it before the quote expires">
    When `nextAction.type` is `transaction` with `depositInstructions`, the wallet sends exactly that amount to that address before `funding.quoteExpiresAt`. An expired quote is terminal. 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, with `operationalState` and `offrampStatus` beside it. Never create a second payment for the same withdrawal. See [Get payment](/api-reference/payments/get-payment).
  </Step>
</Steps>

<Warning>
  Payouts to a linked bank work in the United States only, certified on staging and not yet proven in production. Philippine and Vietnamese banks can be linked but cannot receive a payout, and no linked bank can receive settlement. See [Supported regions and currencies](/supported-regions-and-currencies#linking-a-bank-account).
</Warning>

A withdrawal in stablecoin to a wallet the holder controls is a send to `crypto_wallet` and needs no verification. See [Stablecoin transfers](/payments/stablecoin-transfers).

**Stableyard enables:** your organization's KYB, the linked-bank route for each country, `linked_bank` on your banking program, and business verification for `business` accounts.

## Pattern: Top up with stablecoin

**Use when:** the account holder sends stablecoin from a wallet they control into their account, in any amount, whenever they choose.

**Signals:**

* The holder saves one address per chain and reuses it
* No amount, expiry or order is attached to an arrival
* No verification is involved

<Steps>
  <Step title="Give the account a settlement destination">
    Issuing an address needs an active preferred settlement destination: a connected wallet on a settlement chain. Set it with `PUT /v2/accounts/{accountId}/settlement-profile`. See [Settlement destinations](/settlement/destinations) and [Set preference](/api-reference/settlement/set-settlement-profile).
  </Step>

  <Step title="Check the network catalog">
    `GET /v2/deposit-networks`. Request only chains where `live` is `true`: one paused chain fails the whole batch. See [List networks](/api-reference/deposit-addresses/list-deposit-networks).
  </Step>

  <Step title="Issue the addresses">
    `POST /v2/accounts/{accountId}/deposit-addresses` with `chainIds`. Each address is permanent for one account on one chain. See [Create addresses](/api-reference/deposit-addresses/create-deposit-addresses).
  </Step>

  <Step title="Show the address with its minimum">
    A transfer below the asset's minimum is recorded as `ignored`. It is not credited and not returned. See [Deposit minimums](/supported-regions-and-currencies#deposit-minimums).
  </Step>

  <Step title="Read each deposit">
    `GET /v2/accounts/{accountId}/deposits`. Each arrival is its own deposit; credit it on `settled`, not on `detected`. See [Deposit addresses](/concepts/deposit-addresses) and [List deposits](/api-reference/deposit-addresses/list-deposits).
  </Step>
</Steps>

Deposit-address issuance is paused on Tron and Bitcoin, and addresses already issued there are still monitored. Nothing on a deposit ties it to an order, so use a receive payment when you need to reconcile against one.

## Pattern: Settle your own revenue

**Use when:** you collect payment for your own business, such as for your own goods or your revenue share, and want the net held in a wallet or Vault you control.

**Signals:**

* The receiving account is yours, typically Your Business UPA
* Your backend chooses where value lands; the payer chooses only how to pay
* Spending afterwards may need to be bound by on-chain rules

<Steps>
  <Step title="Use your own account">
    [Your Business UPA](/universal-payment-account#your-business-upa) is covered by your organization's KYB and needs no separate verification. Any other account you control can receive the same way.
  </Step>

  <Step title="Provision a Vault, if you want one">
    `POST /v2/accounts/{accountId}/vault`, then wait for `status: active` before settling into it. Vaults run on Arbitrum only, with USDC and USDT. See [Treasury settlement](/settlement/treasury-settlement) and [Create Vault](/api-reference/vaults/create-vault).
  </Step>

  <Step title="Choose the destination">
    `GET /v2/accounts/{accountId}/settlement-destinations`. Offer only destinations where `capabilities.settlementSupported` is `true`, then set the profile with `PUT /v2/accounts/{accountId}/settlement-profile`. See [List destinations](/api-reference/settlement/list-settlement-destinations).
  </Step>

  <Step title="Collect">
    `POST /v2/payments` with `intent: "receive"` and your account as `recipient`, or issue a deposit address for open-ended top-ups. See [Depositing funds](/payments/depositing-funds).
  </Step>

  <Step title="Confirm it landed">
    `GET /v2/payments/{paymentId}`. `accepted` means the payer's funds were verified; `succeeded` means your destination was credited. See [Settlement lifecycle](/settlement/receiving-settlement).
  </Step>
</Steps>

Settlement runs in stablecoin, to a connected wallet or a Vault. A bank account cannot receive settlement yet.

## Pattern: Acquirer or PSP, own merchant accounts

**Use when:** you hold local-currency settlement balances in processing merchant accounts you own, and want them settled in stablecoin in your own name.

<Steps>
  <Step title="Classify the flow">
    Classification is made strictly on the processing flow: who owns the account the funds sit in, whether an intermediary settlement account is involved, and at what point stablecoin is minted. Funds in your own processing merchant accounts are first-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">
    Settlement runs on a prefunded basis. The funding arrangement, the eligible currencies and the approved destinations are named in your agreement, and the relationship begins with business verification.
  </Step>
</Steps>

There is no public endpoint that creates an acquirer settlement, and nothing is switched on self-serve. Sub-merchant balances in an intermediary account are a [third-party flow](/guides/third-party-flows#pattern-acquirer-or-psp-sub-merchant-balances).

## Blockers to check before building

| Blocker | What it means | Check |
| - | - | - |
| Organization KYB not approved | No fiat product works for you or any account | `compliance.partnerKyb.status` in `GET /v2/partners/config` |
| Holder not verified | Activation is refused with `409 conflict`, naming `verify_account_email` or `complete_kyc` | `GET /v2/accounts/{accountId}/email` and `GET /v2/accounts/{accountId}/kyc` |
| Capability not ready | The service cannot be used until it is `active` | `ready` in `GET /v2/accounts/{accountId}/capabilities` |
| Route not enabled for your app | Nothing can be issued or linked in that market | `available` and `unavailableReason` in the on-ramp and bank-account requirements |
| No eligible wallet | No on-ramp account, deposit address or settlement | `destinations` in the on-ramp requirements; `settlementSupported` on each destination |
| Wrong `subjectType` | A `business` account reaches US bank rails only, after hosted KYB | `subjectType` cannot be changed; create the account correctly |
| Bank not verified | A bank in `pending_verification` cannot receive a payout | `status` on `GET /v2/accounts/{accountId}/bank-accounts/{bankAccountId}` |
| Quote expired | `payment_quote_expired` is terminal; the next attempt is a new payment with a new key | Fund before `funding.quoteExpiresAt` |

## Before go-live

Staging has no simulator: hosted verification needs a real person, and no endpoint fakes a bank deposit or settles a payout. Production re-creates accounts, verification, on-ramp accounts and linked banks, so run one small supervised transfer each way before launch. See [Going live](/white-label/going-live).

## Go deeper

<CardGroup cols={2}>
  <Card title="On-ramp accounts" icon="building-columns" href="/concepts/on-ramp-accounts">
    Requirements, statuses, deposit instructions and funding transactions.
  </Card>

  <Card title="Bank accounts" icon="money-check" href="/concepts/bank-accounts">
    Link a holder's bank per country, its states and its coverage.
  </Card>

  <Card title="Treasury settlement" icon="vault" href="/settlement/treasury-settlement">
    Settle your own revenue into a wallet or Vault, and govern how it is spent.
  </Card>

  <Card title="Third-party flows" icon="users" href="/guides/third-party-flows">
    When the beneficiary is someone else, or you act for your customers.
  </Card>
</CardGroup>


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