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

# Submit a transaction for a checkout payment

> Submit transaction evidence for Routing, direct Movement or supported direct EVM escrow.

Submits an untrusted `transactionHash` for an `optionId`:

* **Routing** methods always use this endpoint for the payer's source transaction, across EVM, Solana, Movement, Tron and Bitcoin sources. Stableyard verifies the source transaction and the final settlement.
* **Direct Movement** payments require hash submission.
* **Supported direct EVM escrow** also accepts the hash. Detection stays automatic (`confirmationMode: provider_webhook`): submitting the hash only lets Stableyard catch a reverted transfer sooner, and does not credit the Payment.
* **Direct Solana** payments are detected automatically and do not use this endpoint. Tron and Bitcoin cannot be direct Payment destinations.

A `202` response means the candidate was accepted for verification.


## OpenAPI

````yaml frontend-openapi.json POST /v2/public/payments/{paymentId}/transactions
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}/transactions:
    post:
      tags:
        - Payments
      summary: Submit transaction candidate
      description: >-
        Submits an untrusted transaction hash for a Payment option.
        Direct-method submission is supported for Movement and supported EVM
        escrow. Every returned Routing method uses this endpoint for payer
        source evidence, including EVM, Solana, Movement, Tron, and Bitcoin
        sources. Direct EVM payments are detected automatically; submitting
        their hash also lets Stableyard detect a reverted transfer sooner and
        does not itself credit the Payment. Direct Solana payments are detected
        automatically and do not support this endpoint; Tron and Bitcoin cannot
        be direct Payment destinations. For Routing options, Stableyard verifies
        the source transaction and the final destination settlement. Direct
        Movement payments require hash submission.
      operationId: submitPublicPaymentTransaction
      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.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubmitCanonicalPaymentTransactionRequest'
            examples:
              example:
                summary: Submit transaction candidate request
                value:
                  optionId: option_123
                  transactionHash: >-
                    0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
      responses:
        '202':
          description: Transaction accepted for verification
          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/PaymentTransactionSubmission'
              examples:
                example:
                  summary: Submit transaction candidate 202 response
                  value:
                    transactionHash: >-
                      0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
                    purpose: destination_escrow
                    status: submitted
                    failureCode: null
                    submittedAt: '2026-08-28T10:00:00.000Z'
                    verifiedAt: null
        '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:
        - paymentClientSecret: []
components:
  schemas:
    SubmitCanonicalPaymentTransactionRequest:
      type: object
      additionalProperties: false
      required:
        - optionId
        - transactionHash
      properties:
        optionId:
          type: string
          minLength: 1
          maxLength: 128
        transactionHash:
          type: string
          minLength: 1
          maxLength: 256
    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
    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: bad_request
              value:
                error:
                  code: bad_request
                  message: The request is invalid
    Unauthorized:
      description: Unauthorized
      headers:
        Stableyard-Version:
          description: >-
            Effective date-based Stableyard API contract version for this
            response.
          schema:
            type: string
            enum:
              - '2026-09-09'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            example:
              summary: unauthorized
              value:
                error:
                  code: unauthorized
                  message: Authentication is required
    Forbidden:
      description: The app secret does not include the required scope
      headers:
        Stableyard-Version:
          description: >-
            Effective date-based Stableyard API contract version for this
            response.
          schema:
            type: string
            enum:
              - '2026-09-09'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            example:
              summary: forbidden
              value:
                error:
                  code: forbidden
                  message: The credential does not allow this operation
    NotFound:
      description: Not found
      headers:
        Stableyard-Version:
          description: >-
            Effective date-based Stableyard API contract version for this
            response.
          schema:
            type: string
            enum:
              - '2026-09-09'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            example:
              summary: not_found
              value:
                error:
                  code: not_found
                  message: The resource was not found
    Conflict:
      description: Conflict
      headers:
        Stableyard-Version:
          description: >-
            Effective date-based Stableyard API contract version for this
            response.
          schema:
            type: string
            enum:
              - '2026-09-09'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            example:
              summary: idempotency_conflict
              value:
                error:
                  code: idempotency_conflict
                  message: >-
                    The Idempotency-Key was already used with a different
                    request
    UnprocessableEntity:
      description: >-
        The request is valid but this account, method, or route cannot perform
        it
      headers:
        Stableyard-Version:
          description: >-
            Effective date-based Stableyard API contract version for this
            response.
          schema:
            type: string
            enum:
              - '2026-09-09'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            example:
              summary: payment_method_not_supported
              value:
                error:
                  code: payment_method_not_supported
                  message: The requested payment method is not supported
    FailedDependency:
      description: This feature is not configured for your app or environment
      headers:
        Stableyard-Version:
          description: >-
            Effective date-based Stableyard API contract version for this
            response.
          schema:
            type: string
            enum:
              - '2026-09-09'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            example:
              summary: chain_config_missing
              value:
                error:
                  code: chain_config_missing
                  message: The requested network is not configured for this environment
    TooManyRequests:
      description: Too many requests. Retry after the `Retry-After` interval.
      headers:
        Stableyard-Version:
          description: >-
            Effective date-based Stableyard API contract version for this
            response.
          schema:
            type: string
            enum:
              - '2026-09-09'
        Retry-After:
          description: Seconds until the caller should retry.
          schema:
            type: integer
            minimum: 1
        RateLimit-Limit:
          description: Quota for the most constrained policy.
          schema:
            type: integer
            minimum: 1
        RateLimit-Remaining:
          description: Requests remaining in that policy window.
          schema:
            type: integer
            minimum: 0
        RateLimit-Reset:
          description: Seconds until that policy window resets.
          schema:
            type: integer
            minimum: 0
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            example:
              summary: rate_limited
              value:
                error:
                  code: rate_limited
                  message: Too many requests
  securitySchemes:
    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.