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

# Select the Vault payment method

> Select the UPA's Vault to fund a receive Payment's escrow.

Selects `vault.stableyard` for this Payment. `paymentMethodId` is the only field you control: Stableyard derives the payer UPA, active Vault, payment source and active policy from the client token, and you cannot submit a `vaultId`, account locator, source or destination address, amount, policy or fee.

The resulting funding operation is private execution state under the existing Payment, and must fund the same immutable escrow amount as Direct crypto, Routing and hosted on-ramp methods. It has `commercialFeeMode: parent_payment`, so it never accrues a second platform or partner fee. Creating the option moves no money and does not complete the Payment; [authorize it](/api-reference/client-payments/authorize-vault-funding) next.

Send the client bearer token and `X-Stableyard-Payment-Secret`. `Idempotency-Key` is required; reusing it with different input returns `409 idempotency_conflict`.


## OpenAPI

````yaml frontend-openapi.json POST /v2/client/me/payments/{paymentId}/options
openapi: 3.1.0
info:
  title: Stableyard Interfaces & SDK API
  version: 2.0.0-staging
  x-stableyard-api-version: '2026-09-09'
  x-stableyard-supported-api-versions:
    - '2026-09-09'
  summary: >-
    Advanced browser API used by Stableyard Checkout, Add Money, and
    account-bound interfaces.
  description: >

    These endpoints power Stableyard's official interface SDKs, hosted checkout,
    Add Money, and advanced custom browser integrations.


    Most partners should use `@stableyard/react` or `@stableyard/sdk` instead of
    calling these routes directly. A browser must never receive an app secret.
    Public checkout uses a Payment-scoped client secret, while account-bound
    experiences use a short-lived client bearer token created by the partner
    backend.
  x-stableyard-documentation-surface: frontend
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: Client API
    description: >-
      Account-bound browser and mobile routes authenticated with a short-lived
      client bearer token. App secrets never enter client code.
  - 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: Payments
    description: >-
      Create escrow-first payments, issue partner-authenticated send
      instructions or executions, power public checkout, and reconcile
      collection through final account settlement.
paths:
  /v2/client/me/payments/{paymentId}/options:
    post:
      tags:
        - Client API
      summary: Select my Vault Payment method
      description: >

        Selects `vault.stableyard` for this Payment. Stableyard derives the
        payer UPA, active Vault, Payment Source, and active policy from the
        Client token; callers cannot submit a `vaultId`, account locator, source
        address, destination address, amount, policy, or fee.


        The resulting funding operation is private execution state under the
        existing Payment. It must fund the same immutable escrow amount used by
        Direct crypto, Routing, and hosted on-ramp methods. The operation has
        `commercialFeeMode: parent_payment`: it never accrues a second platform
        or partner fee, because the parent Payment owns the immutable commercial
        fee snapshot. Creating this option moves no money and does not complete
        the Payment.
      operationId: createClientPaymentOption
      parameters:
        - name: paymentId
          in: path
          required: true
          schema:
            type: string
            pattern: ^payment_[A-Za-z0-9_-]+$
            example: payment_123
          description: Canonical receive Payment whose escrow will be funded.
        - name: Idempotency-Key
          in: header
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 256
            pattern: ^[ -~]+$
            example: vault-payment-option-01
          description: >-
            Required retry key for this account-bound Payment mutation. Reuse
            the same key only with the identical Payment, option, and body;
            different input returns `409 idempotency_conflict`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SelectAccountBoundVaultPaymentMethodRequest'
            examples:
              vault:
                summary: Select the active Vault Payment Source
                value:
                  paymentMethodId: vault.stableyard
      responses:
        '200':
          description: Vault funding option awaiting one-time authorization
          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/AccountBoundVaultPaymentOptionResponse'
              examples:
                created:
                  summary: Vault option created
                  value:
                    paymentId: payment_123
                    option:
                      id: pay_option_vault_123
                      providerCode: vault
                      paymentMethodType: account_balance
                      paymentMethodId: vault.stableyard
                      type: account_balance
                      displayName: Pay with Stableyard Vault
                      status: pending
                      selectionStatus: selected
                      requiredAmountAtomic: '10000000'
                      paidAmountAtomic: '0'
                      remainingAmountAtomic: '10000000'
                      isTerminal: false
                      confirmationMode: provider_webhook
                      transactionSubmissions: []
                      sourceAmount:
                        amountAtomic: '10000000'
                        assetSymbol: USDC
                        decimals: 6
                        chainId: 42161
                      destinationAmount:
                        amountAtomic: '10000000'
                        assetSymbol: USDC
                        decimals: 6
                        chainId: 42161
                      payerAmount:
                        amountAtomic: '10000000'
                        amountDecimal: '10'
                        assetSymbol: USDC
                        decimals: 6
                        chainId: 42161
                        tokenAddress: '0xaf88d065e77c8cC2239327C5EDb3A432268e5831'
                      recipientAmount:
                        amountAtomic: '10000000'
                        amountDecimal: '10'
                        assetSymbol: USDC
                        decimals: 6
                        chainId: 42161
                        tokenAddress: '0xaf88d065e77c8cC2239327C5EDb3A432268e5831'
                      providerFee:
                        amountAtomic: '0'
                        amountDecimal: '0'
                        assetSymbol: USDC
                        decimals: 6
                        chainId: 42161
                        tokenAddress: '0xaf88d065e77c8cC2239327C5EDb3A432268e5831'
                      execution:
                        type: managed_authorization
                        actionId: fund_auth_123
                        authorization: approved
                        expiresAt: '2026-09-01T12:10:00.000Z'
                        confirmEndpoint: >-
                          /v2/client/me/payments/payment_123/options/pay_option_vault_123/authorize
                      expiresAt: null
                      refreshable: false
                      feeAmountAtomic: '0'
                      actionExpiresAt: null
                      quoteExpiresAt: null
                      orderExpiresAt: null
                      receipts: []
                    fundingOperation:
                      id: pay_funding_123
                      status: awaiting_authorization
                      statusVersion: 1
                      commercialFeeMode: parent_payment
                      transactionHash: null
                      authorizedAt: null
                      broadcastAt: null
                      confirmedAt: null
                      expiresAt: '2026-09-01T12:10: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'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '424':
          $ref: '#/components/responses/FailedDependency'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      security:
        - clientBearerAuth: []
          clientPaymentSecret: []
components:
  schemas:
    SelectAccountBoundVaultPaymentMethodRequest:
      type: object
      additionalProperties: false
      required:
        - paymentMethodId
      properties:
        paymentMethodId:
          type: string
          const: vault.stableyard
          description: >-
            The only caller-controlled field. Stableyard derives the UPA, Vault,
            source, active policy, escrow, amount, and fees.
    AccountBoundVaultPaymentOptionResponse:
      type: object
      additionalProperties: false
      required:
        - paymentId
        - option
        - fundingOperation
      properties:
        paymentId:
          type: string
          pattern: ^payment_[A-Za-z0-9_-]+$
          example: payment_123
        option:
          $ref: '#/components/schemas/AccountBoundVaultPaymentOption'
        fundingOperation:
          $ref: '#/components/schemas/AccountBoundVaultFundingOperation'
    AccountBoundVaultPaymentOption:
      type: object
      additionalProperties: false
      required:
        - id
        - providerCode
        - paymentMethodType
        - paymentMethodId
        - type
        - displayName
        - status
        - selectionStatus
        - requiredAmountAtomic
        - paidAmountAtomic
        - remainingAmountAtomic
        - isTerminal
        - confirmationMode
        - transactionSubmissions
        - sourceAmount
        - destinationAmount
        - payerAmount
        - recipientAmount
        - providerFee
        - execution
        - expiresAt
        - refreshable
        - feeAmountAtomic
        - actionExpiresAt
        - quoteExpiresAt
        - orderExpiresAt
        - receipts
      properties:
        id:
          type: string
          pattern: ^pay_option_[A-Za-z0-9_-]+$
          example: pay_option_vault_123
        providerCode:
          type: string
          const: vault
        paymentMethodType:
          type: string
          const: account_balance
        paymentMethodId:
          type: string
          const: vault.stableyard
        type:
          type: string
          const: account_balance
        displayName:
          type: string
          const: Pay with Stableyard Vault
        status:
          type: string
          enum:
            - creating
            - pending
            - processing
            - succeeded
            - expired
            - failed
            - cancelled
        selectionStatus:
          type: string
          enum:
            - selected
            - superseded
        requiredAmountAtomic:
          type: string
          pattern: ^[0-9]+$
        paidAmountAtomic:
          type: string
          pattern: ^[0-9]+$
        remainingAmountAtomic:
          type: string
          pattern: ^[0-9]+$
        isTerminal:
          type: boolean
        confirmationMode:
          type: string
          enum:
            - provider_webhook
            - transaction_hash_submission
        transactionSubmissions:
          type: array
          items:
            $ref: '#/components/schemas/PaymentTransactionSubmission'
        sourceAmount:
          anyOf:
            - $ref: '#/components/schemas/PaymentAmount'
            - type: 'null'
        destinationAmount:
          $ref: '#/components/schemas/PaymentAmount'
        payerAmount:
          $ref: '#/components/schemas/NormalizedPaymentAmount'
        recipientAmount:
          $ref: '#/components/schemas/NormalizedPaymentAmount'
        providerFee:
          anyOf:
            - $ref: '#/components/schemas/NormalizedPaymentAmount'
            - type: 'null'
          description: >-
            Zero for Vault funding. Parent Payment commercial fees are not
            duplicated on the funding operation.
        execution:
          oneOf:
            - title: Vault authorization required
              type: object
              additionalProperties: false
              required:
                - type
                - actionId
                - authorization
                - expiresAt
                - confirmEndpoint
              properties:
                type:
                  type: string
                  const: managed_authorization
                actionId:
                  type: string
                  minLength: 1
                  maxLength: 128
                authorization:
                  type: string
                  const: approved
                expiresAt:
                  type:
                    - string
                    - 'null'
                  format: date-time
                confirmEndpoint:
                  type: string
                  example: >-
                    /v2/client/me/payments/payment_123/options/pay_option_vault_123/authorize
            - title: No payer action currently required
              type: 'null'
        expiresAt:
          type:
            - string
            - 'null'
          format: date-time
        refreshable:
          type: boolean
          const: false
        feeAmountAtomic:
          type:
            - string
            - 'null'
          pattern: ^[0-9]+$
          description: >-
            Provider/network fee for this funding leg. Vault funding currently
            reports zero; commercial fees belong to the parent Payment.
        actionExpiresAt:
          type:
            - string
            - 'null'
          format: date-time
          description: >-
            Stableyard-controlled presentation deadline for the current payer
            action. It is not proof that a provider order is terminal and does
            not by itself permit replacement.
        quoteExpiresAt:
          type:
            - string
            - 'null'
          format: date-time
        orderExpiresAt:
          type:
            - string
            - 'null'
          format: date-time
        receipts:
          type: array
          items:
            $ref: '#/components/schemas/PaymentReceipt'
        error:
          $ref: '#/components/schemas/PublicPaymentError'
    AccountBoundVaultFundingOperation:
      type: object
      additionalProperties: false
      required:
        - id
        - status
        - statusVersion
        - commercialFeeMode
        - transactionHash
        - authorizedAt
        - broadcastAt
        - confirmedAt
        - expiresAt
      properties:
        id:
          type: string
          pattern: ^pay_funding_[A-Za-z0-9_-]+$
          example: pay_funding_123
        status:
          type: string
          enum:
            - created
            - awaiting_authorization
            - authorized
            - signing
            - broadcast
            - confirmed
            - failed
            - requires_intervention
            - cancelled
            - expired
        statusVersion:
          type: integer
          minimum: 1
        commercialFeeMode:
          type: string
          const: parent_payment
          description: >-
            The immutable parent Payment fee snapshot is authoritative; this
            funding leg cannot accrue a second commercial fee.
        transactionHash:
          type:
            - string
            - 'null'
        authorizedAt:
          type:
            - string
            - 'null'
          format: date-time
        broadcastAt:
          type:
            - string
            - 'null'
          format: date-time
        confirmedAt:
          type:
            - string
            - 'null'
          format: date-time
        expiresAt:
          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: {}
    PaymentTransactionSubmission:
      type: object
      additionalProperties: false
      required:
        - transactionHash
        - status
        - failureCode
        - submittedAt
        - verifiedAt
      properties:
        transactionHash:
          type: string
          description: >-
            Canonical EVM/Movement transaction hash, Bitcoin/Tron transaction
            id, or Solana transaction signature.
          pattern: ^(0x[0-9a-fA-F]{64}|[0-9a-fA-F]{64}|[1-9A-HJ-NP-Za-km-z]{80,90})$
        purpose:
          type: string
          enum:
            - destination_escrow
            - routing_source
          description: >-
            Omitted for legacy destination-escrow submissions; routing_source
            identifies payer funding evidence sent to Routing for verification.
        status:
          type: string
          enum:
            - submitted
            - verifying
            - verified
            - rejected
            - requires_intervention
        failureCode:
          type:
            - string
            - 'null'
          enum:
            - invalid_payment_binding
            - invalid_transaction_hash
            - transaction_failed
            - invalid_transaction_type
            - transaction_hash_mismatch
            - invalid_transfer_function
            - invalid_transfer_arguments
            - asset_mismatch
            - destination_mismatch
            - transaction_already_used
            - transaction_not_confirmed
            - transaction_verification_unavailable
            - payment_option_missing
            - routing_transaction_rejected
            - null
        submittedAt:
          type: string
          format: date-time
        verifiedAt:
          type:
            - string
            - 'null'
          format: date-time
    PaymentAmount:
      type: object
      additionalProperties: false
      required:
        - amountAtomic
        - assetSymbol
        - decimals
      properties:
        amountAtomic:
          type: string
          pattern: ^[0-9]+$
          example: '10000000'
        assetSymbol:
          type: string
          example: USDC
        decimals:
          type: integer
          minimum: 0
          maximum: 36
          example: 6
        chainId:
          type: integer
          example: 42161
        tokenAddress:
          type: string
          example: '0xaf88d065e77c8cC2239327C5EDb3A432268e5831'
    NormalizedPaymentAmount:
      type: object
      additionalProperties: false
      required:
        - amountAtomic
        - amountDecimal
        - assetSymbol
        - decimals
      properties:
        amountAtomic:
          type: string
          pattern: ^[0-9]+$
          example: '10000000'
        amountDecimal:
          type: string
          pattern: ^(0|[1-9]\d*)(\.\d+)?$
          example: '10'
        assetSymbol:
          type: string
          example: USDC
        decimals:
          type: integer
          minimum: 0
          maximum: 36
          example: 6
        chainId:
          type: integer
          example: 42161
        tokenAddress:
          type: string
          example: '0xaf88d065e77c8cC2239327C5EDb3A432268e5831'
    PaymentReceipt:
      type: object
      additionalProperties: false
      required:
        - chainId
        - txHash
        - logIndex
        - amountAtomic
        - confirmedAt
      properties:
        chainId:
          type: integer
        txHash:
          type: string
        logIndex:
          type:
            - integer
            - 'null'
          minimum: 0
          description: >-
            EVM token log index when available; null for chain evidence without
            an EVM log index.
        amountAtomic:
          type: string
          pattern: ^[0-9]+$
        confirmedAt:
          type: string
          format: date-time
    PublicPaymentError:
      type: object
      additionalProperties: false
      required:
        - code
        - message
        - details
      properties:
        code:
          type: string
          enum:
            - routing_underpayment
        message:
          type: string
          example: Routing delivered less than the required payment amount.
        details:
          type: object
          additionalProperties: false
          required:
            - expectedAmountAtomic
            - receivedAmountAtomic
          properties:
            expectedAmountAtomic:
              type: string
              pattern: ^[0-9]+$
              example: '1000000'
            receivedAmountAtomic:
              type: string
              pattern: ^[0-9]+$
              example: '966741'
  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
    UnprocessableEntity:
      description: The requested payment method or refund route is not supported
      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: UnprocessableEntity 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:
    clientBearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Stableyard client access token
      description: >-
        Short-lived account-bound token returned by POST
        /v2/client/auth/exchange.
    clientPaymentSecret:
      type: apiKey
      in: header
      name: X-Stableyard-Payment-Secret
      description: >-
        Payment-specific secret used together with an account-bound Client
        bearer token. It proves access to exactly one Payment and must never be
        placed in a URL, analytics event, or log.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.