> ## 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. Stableyard independently verifies the on-chain transfer to the escrow (chain, token, recipient, amount, success, finality and receipt uniqueness), and only verified escrow receipt evidence advances collection. 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-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/{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. Stableyard independently
        verifies the on-chain transfer to the immutable escrow, including chain,
        token, recipient, amount, success, finality, and receipt uniqueness.
        Only verified escrow receipt evidence advances collection.
        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: >-
            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.