> ## 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 Routing or hosted on-ramp option with a newly quoted one.

Replaces an expired or failed Routing or hosted on-ramp option with a newly quoted option. Direct and Vault options cannot be refreshed, and an option that is still active returns `409`. Refresh is also 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
  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/public/payments/{paymentId}/options/{optionId}/refresh:
    post:
      tags:
        - Payments
      summary: Refresh Payment option
      description: >-
        Replaces an expired or failed 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: The `payment_*` ID returned when the Payment was created.
        - 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: request-key-001
          description: >-
            Retry key. Reuse a key only with the identical request; different
            input returns a conflict.
      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
          example: direct
          description: >-
            Payment method family. Crypto methods return `direct` or `routing`
            and Vault methods return `vault`. Hosted on-ramp methods return an
            opaque code; identify them by `paymentMethodType` or `type`
            `fiat_onramp`, and treat unknown codes as opaque.
          x-known-values:
            - direct
            - routing
            - vault
        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 automatically.
        transactionSubmissions:
          type: array
          items:
            $ref: '#/components/schemas/PaymentTransactionSubmission'
          description: Transaction hashes submitted for this option.
        sourceAmount:
          anyOf:
            - $ref: '#/components/schemas/PaymentAmount'
            - type: 'null'
          description: Exact amount the payer must send in the selected source asset.
        destinationAmount:
          $ref: '#/components/schemas/PaymentAmount'
        payerAmount:
          $ref: '#/components/schemas/NormalizedPaymentAmount'
        recipientAmount:
          $ref: '#/components/schemas/NormalizedPaymentAmount'
        providerFee:
          anyOf:
            - $ref: '#/components/schemas/NormalizedPaymentAmount'
            - type: 'null'
          description: >-
            Network or routing cost when reported. Partner and platform fees are
            not included.
        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
                  description: >-
                    Opaque identifier of the hosted checkout. Do not depend on
                    its value.
                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: >-
            Deadline for the payer to fund this option, capped by the Payment
            expiry. Use this for countdowns.
        refreshable:
          type: boolean
          description: >-
            True only when this option has expired or failed and no payment was
            observed, so it can be replaced safely.
        feeAmountAtomic:
          type:
            - string
            - 'null'
          pattern: ^[0-9]+$
          description: >-
            Network fee in the source denomination when reported. Partner and
            platform fees are not included.
        actionExpiresAt:
          type:
            - string
            - 'null'
          format: date-time
          description: >-
            Deadline for completing or refreshing the current payer action.
            Reaching it does not by itself permit replacement.
        quoteExpiresAt:
          type:
            - string
            - 'null'
          format: date-time
          description: Informational quote deadline. Use expiresAt for countdowns.
        orderExpiresAt:
          type:
            - string
            - 'null'
          format: date-time
          description: >-
            Funding-order deadline, capped by the Payment expiry. Null when the
            order has none. 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: >-
            `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
    ServiceUnavailable:
      description: Temporarily unavailable. Retry later.
      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: provider_unavailable
              value:
                error:
                  code: provider_unavailable
                  message: The service is temporarily unavailable
  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.