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

# Get deposit instructions for an on-ramp bank account

> Get the full bank details an account holder sends funds to.

Returns the beneficiary name, bank, ABA routing number and account number the account holder should send funds to, plus where converted funds are delivered. This is the only endpoint that returns the full account number: call it from your backend, show the details to the account holder, and never log or store them. Responses are marked `Cache-Control: no-store, private`.

`rail` identifies the rail requested at issuance. `acceptedRails` lists the rails the sender can use with these instructions: those issued on the account and currently enabled for your app. Display those choices rather than assuming the requested rail is the only one available.

Only an `active` on-ramp bank account has instructions; any other status returns `409`. See [Depositing funds](/payments/depositing-funds).


## OpenAPI

````yaml openapi.json GET /v2/accounts/{accountId}/onramp-bank-accounts/{onrampBankAccountId}/deposit-instructions
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/{onrampBankAccountId}/deposit-instructions:
    get:
      tags:
        - Accounts
      summary: Get deposit instructions for an on-ramp bank account
      description: >-
        Returns the full bank details (beneficiary name, bank, ABA routing
        number, account number) the account holder should send funds to. This is
        the only endpoint that returns the full account number: call it from
        your backend, show the details to the account holder, and never log or
        store them. Responses are marked `Cache-Control: no-store, private`. The
        requested rail is returned as rail; acceptedRails lists the rails issued
        on the facility and currently enabled for the app. Only an `active` bank
        account has instructions; any other status returns `409`.
      operationId: getOnrampDepositInstructions
      parameters:
        - name: accountId
          in: path
          required: true
          schema:
            type: string
            example: acct_123
          description: Canonical account id returned by the Accounts API.
        - name: onrampBankAccountId
          in: path
          required: true
          schema:
            type: string
            example: onramp_acct_123
          description: Id returned when the on-ramp bank account was issued.
        - 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.
      responses:
        '200':
          description: Deposit instructions
          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/OnrampDepositInstructions'
              examples:
                example:
                  summary: >-
                    Get deposit instructions for an on-ramp bank account 200
                    response
                  value:
                    id: onramp_acct_123
                    accountId: acct_123
                    rail: null
                    acceptedRails:
                      - ach
                      - fedwire
                      - fednow
                    currency: USD
                    destination:
                      assetCode: USDC
                      chainId: 42161
                    beneficiary:
                      name: Jane Customer
                    bank:
                      name: Example Bank
                      phone: example
                      abaRoutingNumber: '101019644'
                      accountNumber: '9990005543'
                      accountType: checking
        '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:
    OnrampDepositInstructions:
      type: object
      additionalProperties: false
      required:
        - id
        - accountId
        - rail
        - acceptedRails
        - currency
        - destination
        - beneficiary
        - bank
      properties:
        id:
          type: string
          example: onramp_acct_123
        accountId:
          type: string
        rail:
          type:
            - string
            - 'null'
          enum:
            - ach
            - fedwire
            - fednow
            - null
          description: The rail named when the account was requested.
        acceptedRails:
          type: array
          items:
            type: string
            enum:
              - ach
              - fedwire
              - fednow
          description: >-
            Every rail a sender can use with these bank details: what the
            account was issued with, limited to the rails enabled for the app.
          example:
            - ach
            - fedwire
            - fednow
        currency:
          type: string
          example: USD
        destination:
          type: object
          required:
            - assetCode
            - chainId
          properties:
            assetCode:
              type: string
              example: USDC
            chainId:
              type: integer
              example: 42161
          description: Where converted funds are delivered.
        beneficiary:
          type: object
          properties:
            name:
              type: string
              example: Jane Customer
          description: The account holder name to put on the transfer.
        bank:
          type: object
          properties:
            name:
              type: string
              example: Example Bank
            phone:
              type: string
            abaRoutingNumber:
              type: string
              example: '101019644'
            accountNumber:
              type: string
              example: '9990005543'
            accountType:
              type: string
              example: checking
    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.