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

# Resolve a hosted checkout code

> Exchange a hosted checkout code for the Payment ID and its client secret.

Exchanges the 12-character, case-sensitive Base58 `checkoutCode` from a Stableyard-hosted `paymentUrl` for the `paymentId` and `clientSecret`. The hosted checkout does this server-side before loading the checkout engine. Treat `clientSecret` as opaque and send it only as a Bearer token.

Invalid, inactive, expired or corrupted codes all return the same generic `404`. Exchanges are rate-limited by caller IP and a non-reversible digest of the code.


## OpenAPI

````yaml frontend-openapi.json POST /v2/public/payments/checkout/exchange
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/checkout/exchange:
    post:
      tags:
        - Payments
      summary: Resolve a hosted checkout code
      description: >-
        Exchanges the 12-character Base58 code from a Stableyard-hosted
        `paymentUrl` for `paymentId + clientSecret`. The hosted checkout
        performs this server-side before loading the checkout engine. Invalid,
        inactive, expired, or corrupted codes return the same generic 404
        response. Exchanges are rate-limited by caller IP and a non-reversible
        code digest.
      operationId: exchangeCheckoutCode
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CheckoutCodeExchangeRequest'
            examples:
              example:
                summary: Resolve a hosted checkout code request
                value:
                  checkoutCode: 7Yf3KMpQ2xWa
      responses:
        '200':
          description: Signed browser credential
          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/CheckoutCodeExchangeResponse'
              examples:
                example:
                  summary: Resolve a hosted checkout code 200 response
                  value:
                    paymentId: payment_123
                    clientSecret: examplexxxxxxxxxxxxxxxxxxxxxxxxx
                    apiVersion: '2026-09-09'
                    expiresAt: '2026-08-28T10:00:00.000Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      security: []
components:
  schemas:
    CheckoutCodeExchangeRequest:
      type: object
      additionalProperties: false
      required:
        - checkoutCode
      properties:
        checkoutCode:
          type: string
          minLength: 12
          maxLength: 12
          pattern: ^[1-9A-HJ-NP-Za-km-z]{12}$
          example: 7Yf3KMpQ2xWa
          description: Case-sensitive Base58 code from the canonical paymentUrl.
    CheckoutCodeExchangeResponse:
      type: object
      additionalProperties: false
      required:
        - paymentId
        - clientSecret
        - apiVersion
        - expiresAt
      properties:
        paymentId:
          type: string
          pattern: ^payment_[A-Za-z0-9_-]+$
          example: payment_123
        clientSecret:
          type: string
          minLength: 32
          maxLength: 512
          description: >-
            Opaque browser credential for exactly one Payment. Do not parse it;
            send it only as a Bearer token.
        apiVersion:
          $ref: '#/components/schemas/StableyardApiVersion'
        expiresAt:
          type: string
          format: date-time
    StableyardApiVersion:
      type: string
      enum:
        - '2026-08-28'
        - '2026-09-09'
      example: '2026-09-09'
      description: >-
        Immutable date-based contract recorded on the resource. Historical
        values may appear on existing records; only versions advertised in
        x-stableyard-supported-api-versions are accepted for new requests.
    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: {}
  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
    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
    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

````

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