> ## 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={"system"}
    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={"system"}
    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={"system"}
    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={"system"}
    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. Confirm with Stableyard that on-ramp accounts are enabled for your production app. An account holds one on-ramp account, and an issued one cannot be re-pointed to another wallet or asset.
</Warning>

**Stableyard enables:** your organization's KYB, and the US on-ramp with `bank_onramp` for your app. 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 at settlement, 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. Confirm production availability with Stableyard. 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` for your app, 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.

## 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">
    Stableyard reviews each flow before enabling it. 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

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