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

# Authorize a Vault funding operation

> Authorize the exact Vault-to-escrow transfer for a receive Payment.

Consumes the one-time `actionId` from the selected option's `execution` object and authorizes Stableyard to execute the exact Vault-to-escrow transfer under the active policy. The client bearer token identifies the payer UPA; `X-Stableyard-Payment-Secret` binds the command to one Payment.

A successful response means authorization was recorded, not that funds arrived or the Payment completed. The Payment advances only after Stableyard verifies the transfer on-chain. Underpayments, duplicate receipts, late payments and execution failures follow the Payment's normal reconciliation and recovery states.

`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/{optionId}/authorize
openapi: 3.1.0
info:
  title: Stableyard Interfaces & SDK API
  version: 2.0.0
  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: Sandbox
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: 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/{optionId}/authorize:
    post:
      tags:
        - Client API
      summary: Authorize my Vault funding operation
      description: >

        Consumes the one-time `actionId` returned in the selected option's
        `execution` object and authorizes Stableyard to execute the exact
        Vault-to-escrow transfer under the active policy. The Client bearer
        token identifies the payer UPA; `X-Stableyard-Payment-Secret` binds the
        command to one Payment.


        A successful response means authorization was recorded, not that funds
        arrived and not that the Payment completed. The Payment advances only
        after Stableyard verifies the transfer to the escrow on-chain.
        Underpayments, duplicate receipts, late payments, and execution failures
        follow the Payment's normal reconciliation and recovery states.
      operationId: authorizeClientVaultPaymentOption
      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: optionId
          in: path
          required: true
          schema:
            type: string
            pattern: ^pay_option_[A-Za-z0-9_-]+$
            example: pay_option_vault_123
          description: Vault option returned by the account-bound option endpoint.
        - 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/AuthorizeAccountBoundVaultPaymentOptionRequest
            examples:
              authorize:
                summary: Approve the server-issued action
                value:
                  actionId: fund_auth_123
                  proof:
                    type: managed_authorization
                    authorization: approved
      responses:
        '200':
          description: Vault funding operation authorized for asynchronous execution
          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:
                authorized:
                  summary: Authorization recorded
                  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: null
                      expiresAt: null
                      refreshable: false
                      feeAmountAtomic: '0'
                      actionExpiresAt: null
                      quoteExpiresAt: null
                      orderExpiresAt: null
                      receipts: []
                    fundingOperation:
                      id: pay_funding_123
                      status: authorized
                      statusVersion: 2
                      commercialFeeMode: parent_payment
                      transactionHash: null
                      authorizedAt: '2026-09-01T12:01:00.000Z'
                      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:
    AuthorizeAccountBoundVaultPaymentOptionRequest:
      type: object
      additionalProperties: false
      required:
        - actionId
        - proof
      properties:
        actionId:
          type: string
          minLength: 1
          maxLength: 128
          example: fund_auth_123
          description: Single-use action identifier returned in option.execution.actionId.
        proof:
          type: object
          additionalProperties: false
          required:
            - type
            - authorization
          properties:
            type:
              type: string
              const: managed_authorization
            authorization:
              type: string
              const: approved
        metadata:
          type: object
          additionalProperties: true
          description: >-
            Optional partner metadata. Must be JSON-safe, at most 4096 bytes,
            depth 3, 25 keys per object, 512 characters per string, and 50 items
            per array.
    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: >-
            Network fee for this funding leg. Vault funding reports zero;
            commercial fees belong to the parent Payment.
        actionExpiresAt:
          type:
            - string
            - 'null'
          format: date-time
          description: >-
            Deadline for completing the current payer action. Reaching it 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: >-
            `destination_escrow`: a direct transfer to the Payment escrow.
            `routing_source`: the payer's source transaction for a Routing
            option. May be omitted on older submissions.
        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: bad_request
              value:
                error:
                  code: bad_request
                  message: The request is invalid
    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
              value:
                error:
                  code: unauthorized
                  message: Authentication is required
    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
              value:
                error:
                  code: forbidden
                  message: The credential does not allow this operation
    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: not_found
              value:
                error:
                  code: not_found
                  message: The resource was not found
    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: idempotency_conflict
              value:
                error:
                  code: idempotency_conflict
                  message: >-
                    The Idempotency-Key was already used with a different
                    request
    UnprocessableEntity:
      description: >-
        The request is valid but this account, method, or route cannot perform
        it
      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: payment_method_not_supported
              value:
                error:
                  code: payment_method_not_supported
                  message: The requested payment method is not supported
    FailedDependency:
      description: This feature is not configured for your app or environment
      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: chain_config_missing
              value:
                error:
                  code: chain_config_missing
                  message: The requested network is not configured for this environment
    TooManyRequests:
      description: Too many requests. Retry after the `Retry-After` interval.
      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: rate_limited
              value:
                error:
                  code: rate_limited
                  message: Too many requests
  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.