> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wakapay.cash/llms.txt
> Use this file to discover all available pages before exploring further.

# Bind on-chain transaction

> Binds the payer's broadcast transaction to the checkout session (and locks crypto if not already selected). Required so matching can attribute the transfer when multiple sessions share a merchant wallet. No merchant API key required.



## OpenAPI

````yaml /openapi/merchant.json post /checkout-sessions/{id}/bind-tx
openapi: 3.1.0
info:
  title: WakaPay Merchant API
  description: >-
    Crypto checkout API for WakaPay merchants. Create sessions with a signed
    organisation API key, then track payment through status, asset selection,
    and on-chain binding.
  version: 1.0.0
servers:
  - url: https://api.wakapay.cash
    description: Production
  - url: http://localhost:8080
    description: Local
security: []
tags:
  - name: Checkout
    description: Crypto checkout sessions for merchants and payers.
paths:
  /checkout-sessions/{id}/bind-tx:
    post:
      tags:
        - Checkout
      summary: Bind on-chain transaction
      description: >-
        Binds the payer's broadcast transaction to the checkout session (and
        locks crypto if not already selected). Required so matching can
        attribute the transfer when multiple sessions share a merchant wallet.
        No merchant API key required.
      operationId: bindCheckoutTransaction
      parameters:
        - name: id
          in: path
          required: true
          description: Checkout session UUID.
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BindTxRequest'
            example:
              crypto_currency: ETH
              tx_hash: >-
                0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
              payer_wallet_address: '0x12DaF51B28e904D7583040933595eC4624f91383'
              chain_id: '1'
      responses:
        '200':
          description: Transaction bound (or idempotent replay of the same hash).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BindTxResponse'
        '400':
          description: Expired session, invalid state, or unsupported crypto.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Checkout session not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Session already bound to a different hash, or hash already used.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security: []
components:
  schemas:
    BindTxRequest:
      type: object
      required:
        - crypto_currency
        - tx_hash
        - payer_wallet_address
        - chain_id
      properties:
        crypto_currency:
          type: string
          enum:
            - BTC
            - USDT
            - BNB
            - SOL
            - USDC
            - ETH
          example: ETH
        tx_hash:
          type: string
          pattern: ^0x[a-fA-F0-9]{64}$
          description: 0x-prefixed 64-character hex transaction hash.
          example: '0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa'
        payer_wallet_address:
          type: string
          pattern: ^0x[a-fA-F0-9]{40}$
          description: 0x-prefixed 40-character hex payer address.
          example: '0x12DaF51B28e904D7583040933595eC4624f91383'
        chain_id:
          type: string
          description: Chain ID the payment was sent on.
          example: '1'
    BindTxResponse:
      type: object
      properties:
        session_id:
          type: string
          format: uuid
        bound_tx_hash:
          type: string
        crypto_currency:
          type: string
          example: ETH
        total_amount_crypto:
          type: string
          example: '0.01234567'
        status:
          type: string
          example: waiting_payment
        idempotent:
          type: boolean
          description: True when the same tx hash was already bound.
    ErrorResponse:
      type: object
      properties:
        statusCode:
          type: integer
          example: 401
        message:
          oneOf:
            - type: string
            - type: array
              items:
                type: string
          example: Missing X-Wakapay-Key, X-Wakapay-Timestamp, or X-Wakapay-Signature
        error:
          type: string
          example: Unauthorized

````