OnrampBankAccount, with an id prefixed onramp_acct_. Each inbound transfer has its own funding transaction and bank_funding.* events; it does not require a new receive Payment.
When to use it
Use it when a customer funds repeatedly and should do it the way they pay any bill: a transfer from the bank they already use. It is a standing facility, not a session. The details do not change, so a customer can save them as a payee. For one payment by a payer with no stablecoin, use fiat at checkout instead. See On-ramps.What it needs
An
individual gets the banking relationship through identity verification and the hosted form. A business gets it through hosted business verification.
Check what can be issued
Call these endpoints from your backend with thev2:payments scope. Check requirements before showing the flow. Missing routes, access or eligible wallets return available: false with a reason. Authentication and unexpected failures use normal HTTP errors; handle those separately from unavailable configuration.
Choose the wallet and asset from these lists, not from the general network catalog. None of them replaces the account’s
bank_onramp approval.
Issue it
WhenrecipientOnFile is true, the verified recipient details can be reused:
Omit all three recipient fields to use the verified details on file, or send all three together to override them. A partial override is rejected. When
recipientOnFile is false, supply the full recipient details; omitting them returns 400 with details.reasonCode: "onramp_recipient_details_required".
The response shows only the bank name and the last four digits. The full details come from deposit instructions.
One per account, and its routing is fixed. An account holds one on-ramp account. Asking again with the same wallet, chain and asset returns the existing one. Asking with a different one is refused with 409, and details names the routing already issued. An issued account cannot be re-pointed; Stableyard support can retire it so another can be issued.
Retry with the same key. Idempotency-Key is required and must contain 8–256 printable characters after trimming surrounding whitespace. Repeating the original body with the same key after a timeout or a provisioning response resumes the same issuance. When the issued account reference is already saved, recovery reads that account rather than issuing another. An unresolved attempt outside the provider’s replay window stops for review; do not switch keys to bypass it.
Deposit fees
New USD funding accounts use a 25 bps (0.25%) developer fee. The banking provider deducts it from each incoming deposit before converting the remainder to stablecoin. Show the rate from the requirements response before issuance and from the issued account when showing its bank details. The rate is set by Stableyard; do not send it in the request body. The facility keeps its fee rate through retries. Existing accounts are not automatically repriced.developerFeeBps: null means the historical rate has not been confirmed, rather than a zero fee. An operations-reviewed provider update is required to change an existing account’s future-deposit pricing.
Banking, conversion and network costs are separate from this revenue. Collecting a developer fee does not guarantee that 25 bps covers those costs. These reusable funding-account fees do not change Payment commercial fees or the customer’s KYC/KYB and sub-client requirements.
Use the actual developerFee in funding history for reconciliation. The amount is an exact decimal string confirmed by the banking provider, rather than a calculation from the rate. null means fee evidence is unavailable. A recorded fee does not prove that a separate fee payout has reached Stableyard.
Statuses
Show the deposit instructions
beneficiary.name is the account holder name the sender puts on the transfer. Show every field exactly as returned.
rail is the rail requested at issuance. acceptedRails lists every rail these instructions can accept, limited to those issued on the facility and enabled for your app. Use that list when showing the sender how to transfer.
Track each transfer
Every transfer in becomes one bank funding transaction, listed newest first.
The example above shows 100.00 USD gross received, a confirmed 0.25 USD developer fee and 99.65 USDC net delivered; the conversion result can also reflect FX, rounding or other costs. Never derive a missing fee from the difference between the two legs. Amounts are decimal strings. Repeated event delivery must not credit the same funding transaction twice. This list is the source of truth behind the
bank_funding.* webhooks. limit runs from 1 to 100, default 50.
List every on-ramp account an account holds with GET /v2/accounts/{accountId}/onramp-bank-accounts.
When setup is interrupted
Errors
Webhooks
The payload carriesaccountId, onrampBankAccountId, transactionId, status, the USD and stablecoin amounts, and destinationTxHash when known. It never carries bank details.
Coverage
Issuance is US dollars only, over ACH, Fedwire and FedNow. Production supports USDC on Arbitrum One (42161); sandbox supports USDC on Arbitrum Sepolia (421614). The examples above use the production base URL. For sandbox, use https://staging-api-v2.stableyard.fi, sandbox credentials and a wallet returned by that environment’s requirements response. App enablement and account approval are separate requirements. See US bank environments.
Stableyard has no endpoint that simulates a deposit, in either environment.
Related
- Capability activation: the
bank_onrampapproval this needs. - Universal Payment Account: the account and wallets it attaches to.
- Depositing funds: every way value arrives in an account.
- Webhooks: signatures, delivery and retries.
Next: Deposit addresses
Reusable stablecoin addresses with no amount and no expiry.