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

# Link a tokenized rail identifier

> Link a provider-tokenized static payment rail alias to a UPA.

Send the provider's opaque `providerIdentifierToken` with its `rail`, `identifierType`, `country`, `currency` and the display fields `displayLabel` and `maskedIdentifier`. Raw rail aliases, raw bank identifiers and raw QR payloads are rejected by design.

The identifier stays a pending destination until provider verification and payout execution are available. `Idempotency-Key` is required and must contain 1–256 characters after trimming surrounding whitespace. Retry the identical request with the same key; changed input returns a conflict.


## OpenAPI

````yaml openapi.json POST /v2/accounts/{accountId}/payment-rail-identifiers
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}/payment-rail-identifiers:
    post:
      tags:
        - Accounts
      summary: Link tokenized rail identifier
      description: >-
        Link a provider-tokenized static rail alias. Raw QR payloads and raw
        bank identifiers are not accepted. The destination remains pending until
        provider verification and payout execution are available.
      operationId: createPaymentRailIdentifierByAccountId
      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: 1
            maxLength: 256
            example: bank-beneficiary-supplier-123
          description: >-
            Required retry key for linking a bank account or rail identifier:
            1-256 characters after trimming surrounding whitespace. Retry the
            identical request with the same key; changed input returns a
            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/CreatePaymentRailIdentifierRequest'
            examples:
              tokenizedUpiIdentifier:
                summary: Provider-tokenized UPI identifier
                value:
                  provider: provider_code
                  providerIdentifierToken: rail_provider_token_opaque_123
                  rail: upi
                  identifierType: vpa
                  displayLabel: Business account
                  maskedIdentifier: mi***@bank
                  country: IN
                  currency: INR
      responses:
        '201':
          description: Linked rail identifier
          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/CreatePaymentRailIdentifierResponse'
              examples:
                pendingVerification:
                  summary: Linked rail identifier awaiting provider verification
                  value:
                    paymentRailIdentifier:
                      id: rail_identifier_123
                      accountId: acct_123
                      provider: provider_code
                      rail: upi
                      identifierType: vpa
                      displayLabel: Business account
                      maskedIdentifier: mi***@bank
                      country: IN
                      currency: INR
                      status: pending_verification
                      verification:
                        version: 0
                        verifiedAt: null
                      disabledAt: null
                      createdAt: '2026-08-28T10:00:00.000Z'
                      updatedAt: '2026-08-28T10:00:00.000Z'
                    settlementDestination:
                      id: destination_123
                      accountId: acct_123
                      type: payment_rail_identifier
                      status: pending_verification
                      preferred: false
                      capabilities:
                        directions:
                          - receive
                        settlementSupported: false
                        unavailableReason: bank_settlement_provider_not_configured
                        country: IN
                        currencies:
                          - INR
                        rail: upi
                      resource:
                        type: payment_rail_identifier
                        paymentRailIdentifier:
                          id: rail_identifier_123
                          accountId: acct_123
                          provider: provider_code
                          rail: upi
                          identifierType: vpa
                          displayLabel: Business account
                          maskedIdentifier: mi***@bank
                          country: IN
                          currency: INR
                          status: pending_verification
                          verification:
                            version: 0
                            verifiedAt: null
                          disabledAt: null
                          createdAt: '2026-08-28T10:00:00.000Z'
                          updatedAt: '2026-08-28T10:00:00.000Z'
                      disabledAt: null
                      createdAt: '2026-08-28T10:00:00.000Z'
                      updatedAt: '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:
    CreatePaymentRailIdentifierRequest:
      type: object
      additionalProperties: false
      required:
        - provider
        - providerIdentifierToken
        - rail
        - identifierType
        - displayLabel
        - maskedIdentifier
        - country
        - currency
      properties:
        provider:
          type: string
          pattern: ^[a-z0-9][a-z0-9_-]{1,63}$
          example: provider_code
        providerIdentifierToken:
          type: string
          minLength: 8
          maxLength: 512
          writeOnly: true
          example: rail_provider_token_opaque_123
          description: >-
            Opaque provider token. Raw rail aliases and raw QR payloads are
            rejected by design.
        rail:
          type: string
          minLength: 1
          maxLength: 64
          example: upi
        identifierType:
          type: string
          minLength: 1
          maxLength: 64
          example: vpa
        displayLabel:
          type: string
          minLength: 1
          maxLength: 160
          example: Business account
        maskedIdentifier:
          type: string
          minLength: 1
          maxLength: 160
          example: mi***@bank
        country:
          type: string
          pattern: ^[A-Za-z]{2}$
          example: IN
        currency:
          type: string
          pattern: ^[A-Za-z]{3}$
          example: INR
    CreatePaymentRailIdentifierResponse:
      type: object
      additionalProperties: false
      required:
        - paymentRailIdentifier
        - settlementDestination
      properties:
        paymentRailIdentifier:
          $ref: '#/components/schemas/PaymentRailIdentifier'
        settlementDestination:
          $ref: '#/components/schemas/SettlementDestination'
    PaymentRailIdentifier:
      type: object
      additionalProperties: false
      required:
        - id
        - accountId
        - provider
        - rail
        - identifierType
        - displayLabel
        - maskedIdentifier
        - country
        - currency
        - status
        - verification
        - disabledAt
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          example: rail_identifier_123
        accountId:
          type: string
          example: acct_123
        provider:
          type: string
          example: provider_code
        rail:
          type: string
          example: upi
        identifierType:
          type: string
          example: vpa
        displayLabel:
          type: string
          example: Business account
        maskedIdentifier:
          type: string
          example: mi***@bank
        country:
          type: string
          pattern: ^[A-Z]{2}$
          example: IN
        currency:
          type: string
          pattern: ^[A-Z]{3}$
          example: INR
        status:
          type: string
          enum:
            - pending_verification
            - active
            - restricted
            - disabled
        verification:
          type: object
          additionalProperties: false
          required:
            - version
            - verifiedAt
          properties:
            version:
              type: integer
              minimum: 0
            verifiedAt:
              type:
                - string
                - 'null'
              format: date-time
        disabledAt:
          type:
            - string
            - 'null'
          format: date-time
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    SettlementDestination:
      type: object
      additionalProperties: false
      required:
        - id
        - accountId
        - type
        - status
        - preferred
        - capabilities
        - resource
        - disabledAt
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          example: destination_123
        accountId:
          type: string
          example: acct_123
        type:
          type: string
          enum:
            - crypto_wallet
            - bank_account
            - payment_rail_identifier
          example: crypto_wallet
        status:
          type: string
          enum:
            - pending_verification
            - active
            - restricted
            - disabled
          example: active
        preferred:
          type: boolean
        capabilities:
          type: object
          additionalProperties: true
          description: >-
            Immutable-at-selection capability projection. `settlementSupported`
            must be true before this destination can be selected.
          example:
            directions:
              - receive
            settlementSupported: true
            unavailableReason: null
            network:
              code: base
              chainId: 8453
              chainFamily: evm
            assets:
              - symbol: USDC
                tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
                decimals: 6
        resource:
          type: object
          additionalProperties: true
          description: >-
            Privacy-safe projection of the linked wallet, bank account, or rail
            identifier. Provider tokens are never returned.
          example:
            type: crypto_wallet
            connectedWalletId: wallet_123
            chainId: 8453
            address: '0x1111111111111111111111111111111111111111'
            walletKind: external
            label: Primary wallet
            ownershipVerificationStatus: unverified
        disabledAt:
          type:
            - string
            - 'null'
          format: date-time
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    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.