Skip to main content
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.
Paying someone else’s bank, wallet or handle, or collecting for a merchant? Use Third-party flows instead.

​
Scoping output

Before building, agree on:
  • The legal entity that owns both ends, and its 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

Fund from your own bank

US bank details in the holder’s name. Every transfer in arrives as stablecoin in their wallet.

Withdraw to your own bank

A payout from the holder’s wallet to a bank account they linked and verified.

Top up with stablecoin

A permanent deposit address. Any amount, any time, settled to the holder’s destination.

Settle your own revenue

Collect for your own business and settle the net into a wallet or Vault you control.

Acquirer or PSP, own merchant accounts

Convert local-currency balances from processing accounts you own, under an agreement.

​
How the money moves

​
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
1

Create the account

POST /v2/accounts with subjectType and the holder’s wallet. See Universal Payment Account and Create account.
2

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

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 and Activate capability.
4

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

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

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

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.
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.
Stableyard enables: your organization’s KYB, the on-ramp with a US banking program, and bank_onramp on that program. See Going live.

​
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
  • Each withdrawal is one payment with its own id and result
  • The holder’s wallet holds the stablecoin, and someone can sign from it
1

Create the account with a wallet

POST /v2/accounts with wallets. See Create account.
2

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

Activate linked_bank

POST /v2/accounts/{accountId}/capability-activations with capability: "linked_bank", then wait for ready: true. See Capability activation.
4

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, Bank requirements and Link bank account.
5

Set the payment source

PUT /v2/accounts/{accountId}/payment-source names the wallet that funds the withdrawal. See Set payment source.
6

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 and Create payment.
7

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

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.
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.
A withdrawal in stablecoin to a wallet the holder controls is a send to crypto_wallet and needs no verification. See 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
1

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 and Set preference.
2

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

Issue the addresses

POST /v2/accounts/{accountId}/deposit-addresses with chainIds. Each address is permanent for one account on one chain. See Create addresses.
4

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

Read each deposit

GET /v2/accounts/{accountId}/deposits. Each arrival is its own deposit; credit it on settled, not on detected. See Deposit addresses and List deposits.
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
1

Use your own 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.
2

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 and Create Vault.
3

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

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

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

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

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

​
Blockers to check before building

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

​
Go deeper

On-ramp accounts

Requirements, statuses, deposit instructions and funding transactions.

Bank accounts

Link a holder’s bank per country, its states and its coverage.

Treasury settlement

Settle your own revenue into a wallet or Vault, and govern how it is spent.

Third-party flows

When the beneficiary is someone else, or you act for your customers.