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

# Refresh a payment option

> Replace an expired or failed provider option with a newly quoted one.

Replaces an expired or failed provider option with a newly quoted option. Refresh is rejected after any payment evidence is observed. Send a new `Idempotency-Key` for each intended replacement.


## OpenAPI

````yaml frontend-openapi.json POST /v2/public/payments/{paymentId}/options/{optionId}/refresh
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/public/payments/{paymentId}/options/{optionId}/refresh:
    post:
      tags:
        - Payments
      summary: Refresh Payment option
      description: >-
        Replaces an expired or failed provider option with a newly quoted
        option. Refresh is rejected after any payment evidence is observed. Send
        a new Idempotency-Key for each intended replacement.
      operationId: refreshPublicPaymentOptionByPayment
      parameters:
        - name: paymentId
          in: path
          required: true
          schema:
            type: string
            pattern: ^payment_[A-Za-z0-9_-]+$
            example: payment_123
          description: >-
            Canonical `payment_*` identifier. Internal execution identifiers are
            never accepted by Partner Payment routes.
        - name: optionId
          in: path
          required: true
          schema:
            type: string
            example: pay_option_123
          description: Payment option returned by the payment-method selection endpoint.
        - name: Idempotency-Key
          in: header
          required: true
          schema:
            type: string
            example: payment-request-001
          description: Use this for retry-safe payment operations from your backend.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RefreshPublicPaymentOptionRequest'
            examples:
              example:
                summary: Refresh Payment option request
                value:
                  receiptEmail: customer@example.com
                  fiatCurrency: USD
                  returnUrl: https://example.com
      responses:
        '200':
          description: Replacement payment option
          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/CreatePublicPaymentOptionResponse'
              examples:
                example:
                  summary: Refresh Payment option 200 response
                  value:
                    previousSelectedOptionId: pay_option_previous
                    option:
                      id: pay_option_123
                      providerCode: direct
                      paymentMethodType: crypto
                      paymentMethodId: crypto.direct
                      type: crypto
                      displayName: Arbitrum USDC
                      status: creating
                      selectionStatus: selected
                      requiredAmountAtomic: '1000000'
                      paidAmountAtomic: '1000000'
                      remainingAmountAtomic: '1000000'
                      isTerminal: true
                      confirmationMode: provider_webhook
                      transactionSubmissions:
                        - transactionHash: >-
                            0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
                          purpose: destination_escrow
                          status: submitted
                          failureCode: null
                          submittedAt: '2026-08-28T10:00:00.000Z'
                          verifiedAt: null
                      sourceAmount:
                        amountAtomic: '10000000'
                        assetSymbol: USDC
                        decimals: 6
                        chainId: 42161
                        tokenAddress: '0xaf88d065e77c8cC2239327C5EDb3A432268e5831'
                      destinationAmount:
                        amountAtomic: '10000000'
                        assetSymbol: USDC
                        decimals: 6
                        chainId: 42161
                        tokenAddress: '0xaf88d065e77c8cC2239327C5EDb3A432268e5831'
                      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: '10000000'
                        amountDecimal: '10'
                        assetSymbol: USDC
                        decimals: 6
                        chainId: 42161
                        tokenAddress: '0xaf88d065e77c8cC2239327C5EDb3A432268e5831'
                      execution:
                        type: deposit_address
                        address: '0x1111111111111111111111111111111111111111'
                        chainId: 1
                        tokenAddress: '0x1111111111111111111111111111111111111111'
                        assetSymbol: USDC
                        amountAtomic: '1000000'
                        decimals: 0
                        expiresAt: null
                      expiresAt: null
                      refreshable: true
                      feeAmountAtomic: null
                      actionExpiresAt: null
                      quoteExpiresAt: null
                      orderExpiresAt: null
                      receipts:
                        - chainId: 1
                          txHash: example
                          logIndex: null
                          amountAtomic: '1000000'
                          confirmedAt: '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'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '424':
          $ref: '#/components/responses/FailedDependency'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
      security:
        - paymentClientSecret: []
components:
  schemas:
    RefreshPublicPaymentOptionRequest:
      type: object
      additionalProperties: false
      properties:
        receiptEmail:
          type: string
          format: email
          maxLength: 254
        fiatCurrency:
          type: string
          pattern: ^[A-Z]{3}$
          example: USD
        returnUrl:
          type: string
          format: uri
          maxLength: 2048
    CreatePublicPaymentOptionResponse:
      type: object
      required:
        - previousSelectedOptionId
        - option
      properties:
        previousSelectedOptionId:
          type:
            - string
            - 'null'
          example: pay_option_previous
        option:
          $ref: '#/components/schemas/PublicPaymentOption'
    PublicPaymentOption:
      type: object
      additionalProperties: false
      required:
        - id
        - providerCode
        - paymentMethodType
        - paymentMethodId
        - type
        - displayName
        - status
        - selectionStatus
        - requiredAmountAtomic
        - paidAmountAtomic
        - remainingAmountAtomic
        - isTerminal
        - confirmationMode
        - transactionSubmissions
        - destinationAmount
        - payerAmount
        - recipientAmount
        - providerFee
        - execution
        - expiresAt
        - refreshable
        - actionExpiresAt
        - receipts
      properties:
        id:
          type: string
          example: pay_option_123
        providerCode:
          type: string
          enum:
            - direct
            - routing
            - banxa
            - vault
          example: direct
        paymentMethodType:
          type: string
          enum:
            - crypto
            - fiat_onramp
            - card
            - account_balance
        paymentMethodId:
          type: string
          example: crypto.direct
        type:
          type: string
          enum:
            - crypto
            - fiat_onramp
            - card
            - account_balance
        displayName:
          type: string
          example: Arbitrum USDC
        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
          description: >-
            Movement direct payments require transaction-hash submission. Other
            supported Payment escrow networks are detected by provider webhook.
        transactionSubmissions:
          type: array
          items:
            $ref: '#/components/schemas/PaymentTransactionSubmission'
          description: >-
            Movement transaction candidates submitted for this option. Empty for
            webhook-detected networks.
        sourceAmount:
          anyOf:
            - $ref: '#/components/schemas/PaymentAmount'
            - type: 'null'
          description: >-
            Exact amount the payer must deposit in the selected source asset.
            For Routing exact-output options, this is normalized from
            quote.inputAmount.
        destinationAmount:
          $ref: '#/components/schemas/PaymentAmount'
        payerAmount:
          $ref: '#/components/schemas/NormalizedPaymentAmount'
        recipientAmount:
          $ref: '#/components/schemas/NormalizedPaymentAmount'
        providerFee:
          anyOf:
            - $ref: '#/components/schemas/NormalizedPaymentAmount'
            - type: 'null'
          description: >-
            Routing/provider network cost when reported. Commercial partner and
            platform fees remain private.
        execution:
          description: >-
            Normalized interface execution contract for the selected Payment
            option.
          oneOf:
            - title: Crypto deposit address
              type: object
              additionalProperties: false
              required:
                - type
                - address
                - chainId
                - tokenAddress
                - assetSymbol
                - amountAtomic
                - decimals
                - expiresAt
              properties:
                type:
                  type: string
                  const: deposit_address
                address:
                  type: string
                chainId:
                  type: integer
                tokenAddress:
                  type: string
                assetSymbol:
                  type: string
                amountAtomic:
                  type: string
                  pattern: ^[0-9]+$
                decimals:
                  type: integer
                  minimum: 0
                  maximum: 36
                expiresAt:
                  type:
                    - string
                    - 'null'
                  format: date-time
            - title: Hosted fiat checkout
              type: object
              additionalProperties: false
              required:
                - type
                - provider
                - checkoutUrl
              properties:
                type:
                  type: string
                  const: hosted_checkout
                provider:
                  type: string
                  enum:
                    - banxa
                checkoutUrl:
                  type: string
                  format: uri
            - title: Account-bound Vault authorization
              description: >-
                Returned only after an authenticated UPA selects its Vault. The
                Payment client secret alone cannot authorize this action.
              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
            - title: Execution not ready
              type: 'null'
        expiresAt:
          type:
            - string
            - 'null'
          format: date-time
          description: >-
            Compatibility field for the effective payer deadline, capped by the
            Stableyard action TTL, provider deadline, and enclosing Payment
            expiry. Use this for countdowns.
        refreshable:
          type: boolean
          description: >-
            True only when this provider option has expired or failed and
            Stableyard has observed no financial evidence, so it may be replaced
            safely.
        feeAmountAtomic:
          type:
            - string
            - 'null'
          pattern: ^[0-9]+$
          description: >-
            Provider/network fee in the source denomination when reported.
            Stableyard and partner commercial fee economics are private.
        actionExpiresAt:
          type:
            - string
            - 'null'
          format: date-time
          description: >-
            Stableyard-controlled deadline for completing or refreshing 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
          description: >-
            Provider quote deadline used server-to-server while creating the
            order. Do not show this as the payer funding timer.
        orderExpiresAt:
          type:
            - string
            - 'null'
          format: date-time
          description: >-
            Provider-owned funding-order deadline before it is capped by the
            enclosing Payment expiry. Null when the provider does not return
            one. Legacy Banxa records may retain the former action deadline here
            during a rolling deployment; use expiresAt for countdowns.
        receipts:
          type: array
          items:
            $ref: '#/components/schemas/PaymentReceipt'
        error:
          $ref: '#/components/schemas/PublicPaymentError'
    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
    ServiceUnavailable:
      description: Payment provider or escrow provisioning is unavailable
      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: ServiceUnavailable response
              value:
                error:
                  code: bad_request
                  message: The request is invalid
                  details: example
  securitySchemes:
    paymentClientSecret:
      type: http
      scheme: bearer
      bearerFormat: Stableyard Payment client secret
      description: >-
        Short-lived browser capability for exactly one payment_* resource. Never
        place it in a URL.

````

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