> ## 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. # Issue an on-ramp bank account > Issue a persistent US bank account whose deposits convert to stablecoin on-chain. Issues a persistent US bank account (ACH, FedWire or FedNow) for the UPA. Incoming USD converts automatically to the chosen `destinationAssetCode` and is delivered on-chain to the UPA's connected wallet. There is no separate settlement step, and the account is reusable indefinitely. The UPA needs an active `bank_onramp` provider relationship (the same regulated-banking relationship used for linked-bank payouts) and an active connected wallet on a verified destination chain and asset pair. Unverified pairs return `payment_method_not_supported`. Only `connectedWalletId` and `destinationAssetCode` are always required in the body. Omit `recipientType`, `recipientName` and `recipientAddress` together to use verified details on file, indicated by `recipientOnFile` in the requirements response. To override those details, or when none are on file, send all three together. A partial override is rejected. A UPA holds one on-ramp bank account per provider. Repeating the request returns the existing account rather than issuing a second set of banking coordinates. Routing is fixed when the account is issued: a request naming a different connected wallet, chain or destination asset returns `409`, and an existing account cannot be re-pointed. `Idempotency-Key` is required and must contain 8–256 printable characters after trimming surrounding whitespace. Preserve the original body and key through a timeout or `provisioning` response. Discover eligible rails and wallets through [Get on-ramp requirements](/api-reference/onramp-accounts/get-onramp-requirements). The response shows only the bank name and the last four account digits. Call [Get deposit instructions](/api-reference/onramp-accounts/get-deposit-instructions) for the full details to show the account holder. See [On-ramp accounts](/concepts/on-ramp-accounts). ## OpenAPI ````yaml openapi.json POST /v2/accounts/{accountId}/onramp-bank-accounts openapi: 3.1.0 info: title: Stableyard Partner API version: 2.0.0-staging x-stableyard-api-version: '2026-09-09' x-stableyard-supported-api-versions: - '2026-09-09' summary: Backend API for UPAs, Payments, activity, and optional financial products. description: > Use this API from a trusted partner backend with an app ID and app secret. ## Recommended integration 1. Call `GET /v2/partners/config` to verify credentials and discover enabled capabilities. 2. Create a UPA only when your product needs a persistent Stableyard account. 3. Create a receive or send Payment with `POST /v2/payments`. 4. Redirect a payer to the returned `paymentUrl` or pass the Payment credentials to an official Stableyard interface SDK. 5. Process signed webhooks and fetch the Payment by ID for reconciliation. Checkout execution and account-bound browser endpoints are intentionally documented in the separate Interfaces & SDKs reference. Console endpoints are dashboard implementation details and are not part of the partner integration contract. x-stableyard-documentation-surface: partner servers: - url: https://prod-api.stableyard.fi description: Production - url: https://staging-api-v2.stableyard.fi description: Staging - url: http://localhost:3001 description: Local security: [] tags: - name: Authentication x-displayName: API authentication description: Verify your app ID and app secret before calling UPA APIs. - name: Accounts x-displayName: UPA Accounts description: Create Universal Payment Accounts and manage account settings. - name: Deposit Addresses description: Create reusable receive addresses and verify inbound deposits. - name: Identity & KYC description: >- Verify the UPA email and run provider-neutral identity verification. Managed vaults and fiat payment rails use this same verified UPA identity. - name: Vaults description: >- Create Safe/Zodiac controlled stablecoin vaults and manage policy updates for accounts. - name: Payments description: >- Create escrow-first payments, issue partner-authenticated send instructions or executions, power public checkout, and reconcile collection through final account settlement. - name: Balances & Transactions description: >- Read Stableyard-posted financial activity. Balances are ledger projections of activity Stableyard processed; they are not live balances of externally controlled wallets. paths: /v2/accounts/{accountId}/onramp-bank-accounts: post: tags: - Accounts summary: Issue a persistent on-ramp bank account (US) description: >- Issues a persistent US bank account (ACH, FedWire, or FedNow) for this UPA. Any inbound wire to the returned account automatically converts to the chosen crypto asset and delivers on-chain to the UPA's connected wallet -- there is no separate settlement step, and the account is reusable indefinitely for repeated deposits. Requires an active `bank_onramp` provider relationship on the UPA (the same regulated-banking relationship used for linked-bank payouts) and an active connected wallet on a verified destination chain/asset pair; unverified chain/asset combinations are rejected with `payment_method_not_supported`. A UPA holds one on-ramp bank account per provider. Repeating the request for the account that already exists returns it rather than issuing a second set of banking coordinates for the same person -- this is a standing facility, not a bounded Payment. Its routing is fixed when it is issued, because the provider fixes it: a request naming a different connected wallet, chain or destination asset is rejected with `409`, and re-pointing an existing account is not possible at any level. This response exposes only the bank name and the last 4 account digits; call the deposit-instructions endpoint to get the full details to show the account holder. operationId: createOnrampBankAccountByAccountId parameters: - name: accountId in: path required: true schema: type: string example: acct_123 description: Canonical account id returned by the Accounts API. - name: Idempotency-Key in: header required: true schema: type: string minLength: 8 maxLength: 256 pattern: ^[^\u0000-\u001f\u007f]+$ example: bank-funding-account-123-v1 description: >- Required retry key for funding-account issuance: 8-256 printable characters after trimming surrounding whitespace. Retry the identical request with the same key after a timeout or provisioning response; changed input returns `409 idempotency_conflict`. - name: Stableyard-Version in: header required: false schema: type: string enum: - '2026-09-09' description: >- Optional contract-version assertion. Omit it to use the app environment's pinned version. A different supported version is accepted only after that environment is explicitly migrated. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateOnrampBankAccountRequest' examples: example: summary: Issue a persistent on-ramp bank account (US) request value: connectedWalletId: wallet_abc123 destinationAssetCode: USDC rail: ach recipientType: individual recipientName: Example account recipientAddress: street1: example street2: example street3: example city: example region: example postalCode: example country: US responses: '200': description: On-ramp bank account headers: Stableyard-Version: description: >- Effective date-based Stableyard API contract version for this response. schema: type: string enum: - '2026-09-09' content: application/json: schema: $ref: '#/components/schemas/OnrampBankAccount' examples: example: summary: Issue a persistent on-ramp bank account (US) 200 response value: id: onramp_acct_123 accountId: acct_123 status: provisioning rail: null sourceAsset: USD destinationAssetCode: USDC destinationChainId: 42161 connectedWalletId: connectedwallet_123 bankName: null accountNumberLast4: null createdAt: '2026-08-28T10:00:00.000Z' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '424': $ref: '#/components/responses/FailedDependency' '429': $ref: '#/components/responses/TooManyRequests' security: - partnerBasicAuth: [] components: schemas: CreateOnrampBankAccountRequest: type: object additionalProperties: false required: - connectedWalletId - destinationAssetCode description: >- Omit recipientType, recipientName and recipientAddress to use the name and address already verified for the UPA (see recipientOnFile on the requirements). Send all three together to override them. dependentRequired: recipientType: - recipientName - recipientAddress recipientName: - recipientType - recipientAddress recipientAddress: - recipientType - recipientName properties: connectedWalletId: type: string pattern: ^wallet_[A-Za-z0-9_-]{3,59}$ example: wallet_abc123 destinationAssetCode: type: string enum: - USDC - USDT description: >- Only chain/asset pairs Stableyard has verified with the provider are accepted; unverified combinations return payment_method_not_supported. rail: type: string enum: - ach - fedwire - fednow default: ach recipientType: type: string enum: - individual - business recipientName: type: string minLength: 1 maxLength: 200 recipientAddress: $ref: '#/components/schemas/OnrampRecipientAddress' OnrampBankAccount: type: object additionalProperties: false required: - id - accountId - status - rail - sourceAsset - destinationAssetCode - destinationChainId - connectedWalletId - bankName - accountNumberLast4 - createdAt properties: id: type: string example: onramp_acct_123 accountId: type: string status: type: string enum: - provisioning - active - requires_intervention - disabled - retired rail: type: - string - 'null' enum: - ach - fedwire - fednow - null sourceAsset: type: string example: USD destinationAssetCode: type: string example: USDC destinationChainId: type: integer example: 42161 connectedWalletId: type: string description: >- The connected wallet this bank account forwards to. Fixed when the bank account is issued: the provider cannot re-point an existing account, so a different wallet, chain or asset requires a different bank account entirely. bankName: type: - string - 'null' accountNumberLast4: type: - string - 'null' description: >- Last 4 digits only. Use the deposit-instructions endpoint for the full details. createdAt: type: string format: date-time OnrampRecipientAddress: type: object additionalProperties: false required: - street1 - city - region - postalCode - country properties: street1: type: string minLength: 1 maxLength: 200 street2: type: string minLength: 1 maxLength: 200 street3: type: string minLength: 1 maxLength: 200 city: type: string minLength: 1 maxLength: 120 region: type: string minLength: 1 maxLength: 120 postalCode: type: string minLength: 1 maxLength: 20 country: type: string pattern: ^[A-Z]{2}$ example: US ErrorResponse: type: object additionalProperties: false required: - error properties: error: type: object additionalProperties: false required: - code - message properties: code: type: string minLength: 1 maxLength: 128 example: bad_request message: type: string minLength: 1 maxLength: 1000 example: The request is invalid details: {} responses: BadRequest: description: Bad request headers: Stableyard-Version: description: >- Effective date-based Stableyard API contract version for this response. schema: type: string enum: - '2026-09-09' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: example: summary: BadRequest response value: error: code: bad_request message: The request is invalid details: example Unauthorized: description: Unauthorized headers: Stableyard-Version: description: >- Effective date-based Stableyard API contract version for this response. schema: type: string enum: - '2026-09-09' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: example: summary: Unauthorized response value: error: code: bad_request message: The request is invalid details: example Forbidden: description: The app secret does not include the required scope headers: Stableyard-Version: description: >- Effective date-based Stableyard API contract version for this response. schema: type: string enum: - '2026-09-09' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: example: summary: Forbidden response value: error: code: bad_request message: The request is invalid details: example NotFound: description: Not found headers: Stableyard-Version: description: >- Effective date-based Stableyard API contract version for this response. schema: type: string enum: - '2026-09-09' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: example: summary: NotFound response value: error: code: bad_request message: The request is invalid details: example Conflict: description: Conflict headers: Stableyard-Version: description: >- Effective date-based Stableyard API contract version for this response. schema: type: string enum: - '2026-09-09' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: example: summary: Conflict response value: error: code: bad_request message: The request is invalid details: example FailedDependency: description: Required chain, network, or provider configuration is missing headers: Stableyard-Version: description: >- Effective date-based Stableyard API contract version for this response. schema: type: string enum: - '2026-09-09' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: example: summary: FailedDependency response value: error: code: bad_request message: The request is invalid details: example TooManyRequests: description: >- Rate limit, payment-option limit, selection cooldown, or temporary abuse block headers: Stableyard-Version: description: >- Effective date-based Stableyard API contract version for this response. schema: type: string enum: - '2026-09-09' Retry-After: description: Seconds until the caller should retry. schema: type: integer minimum: 1 RateLimit-Limit: description: Quota for the most constrained policy. schema: type: integer minimum: 1 RateLimit-Remaining: description: Requests remaining in that policy window. schema: type: integer minimum: 0 RateLimit-Reset: description: Seconds until that policy window resets. schema: type: integer minimum: 0 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: example: summary: TooManyRequests response value: error: code: bad_request message: The request is invalid details: example securitySchemes: partnerBasicAuth: type: http scheme: basic description: >- HTTP Basic auth. Username is the Stableyard app ID. Password is the app secret. The optional Stableyard-Version request header must match the environment pin. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.