> ## 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 a saved bank beneficiary

See [saved beneficiaries](https://docs.stableyard.fi/payments/off-ramps.md#saved-third-party-bank-beneficiaries) for supported markets and the payment flow.


## OpenAPI

````yaml openapi.json GET /v2/accounts/{accountId}/beneficiaries/{beneficiaryId}
openapi: 3.1.0
info:
  title: Stableyard Partner API
  version: 2.0.0
  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 documented in the
    separate Interfaces & SDKs reference.
  x-stableyard-documentation-surface: partner
servers:
  - url: https://prod-api.stableyard.fi
    description: Production
  - url: https://staging-api-v2.stableyard.fi
    description: Sandbox
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 identity verification. Managed vaults and
      fiat payment rails use this same verified UPA identity.
  - name: Vaults
    description: >-
      Create policy-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}/beneficiaries/{beneficiaryId}:
    get:
      tags:
        - Accounts
      summary: Get a masked bank beneficiary
      operationId: getBankBeneficiary
      parameters:
        - name: accountId
          in: path
          required: true
          schema:
            type: string
        - name: beneficiaryId
          in: path
          required: true
          schema:
            type: string
            pattern: ^beneficiary_[A-Za-z0-9_-]{3,48}$
        - 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: Beneficiary
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required:
                  - beneficiary
                properties:
                  beneficiary:
                    $ref: '#/components/schemas/SavedBankBeneficiary'
              examples:
                example:
                  summary: Get a masked bank beneficiary 200 response
                  value:
                    beneficiary:
                      id: beneficiary_123
                      accountId: acct_123
                      label: example
                      country: example
                      currency: USD
                      bankCode: example
                      beneficiaryName: Example account
                      accountNumberLast4: exam
                      status: active
                      verificationStatus: verify_on_payment
                      version: 1
                      createdAt: '2026-08-28T10:00:00.000Z'
                      disabledAt: '2026-08-28T10:00:00.000Z'
        '400':
          description: Validation, authorization, conflict, or runtime error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                example:
                  summary: List saved third-party bank beneficiaries 400 response
                  value:
                    error:
                      code: bad_request
                      message: The request is invalid
                      details: example
        '401':
          description: Validation, authorization, conflict, or runtime error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                example:
                  summary: List saved third-party bank beneficiaries 401 response
                  value:
                    error:
                      code: bad_request
                      message: The request is invalid
                      details: example
        '403':
          description: Validation, authorization, conflict, or runtime error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                example:
                  summary: List saved third-party bank beneficiaries 403 response
                  value:
                    error:
                      code: bad_request
                      message: The request is invalid
                      details: example
        '404':
          description: Validation, authorization, conflict, or runtime error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                example:
                  summary: List saved third-party bank beneficiaries 404 response
                  value:
                    error:
                      code: bad_request
                      message: The request is invalid
                      details: example
        '409':
          description: Validation, authorization, conflict, or runtime error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                example:
                  summary: List saved third-party bank beneficiaries 409 response
                  value:
                    error:
                      code: bad_request
                      message: The request is invalid
                      details: example
        '422':
          description: Validation, authorization, conflict, or runtime error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                example:
                  summary: List saved third-party bank beneficiaries 422 response
                  value:
                    error:
                      code: bad_request
                      message: The request is invalid
                      details: example
        '503':
          description: Validation, authorization, conflict, or runtime error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                example:
                  summary: List saved third-party bank beneficiaries 503 response
                  value:
                    error:
                      code: bad_request
                      message: The request is invalid
                      details: example
      security:
        - partnerBasicAuth: []
components:
  schemas:
    SavedBankBeneficiary:
      type: object
      additionalProperties: false
      required:
        - id
        - accountId
        - label
        - country
        - currency
        - bankCode
        - beneficiaryName
        - accountNumberLast4
        - status
        - verificationStatus
        - version
        - createdAt
        - disabledAt
      properties:
        id:
          type: string
          pattern: ^beneficiary_[A-Za-z0-9_-]{3,48}$
        accountId:
          type: string
        label:
          type: string
        country:
          type: string
        currency:
          type: string
        bankCode:
          type: string
        beneficiaryName:
          type: string
        accountNumberLast4:
          type: string
          minLength: 4
          maxLength: 4
        status:
          type: string
          enum:
            - active
            - disabled
        verificationStatus:
          type: string
          const: verify_on_payment
        version:
          type: integer
          const: 1
        createdAt:
          type: string
          format: date-time
        disabledAt:
          type: string
          format: date-time
          nullable: true
    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: {}
  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.