> ## 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. # Create a checkout session > Merchant-only. Creates a crypto checkout session for an organisation API key. Returns a `checkout_url` to send the payer to hosted checkout, plus quoted `crypto_options`. **Auth:** signed headers `X-Wakapay-Key`, `X-Wakapay-Timestamp`, `X-Wakapay-Signature` (HMAC-SHA256 of `{timestamp}.{rawBody}`). ## OpenAPI ````yaml /openapi/merchant.json post /checkout-sessions 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: post: tags: - Checkout summary: Create a checkout session description: >- Merchant-only. Creates a crypto checkout session for an organisation API key. Returns a `checkout_url` to send the payer to hosted checkout, plus quoted `crypto_options`. **Auth:** signed headers `X-Wakapay-Key`, `X-Wakapay-Timestamp`, `X-Wakapay-Signature` (HMAC-SHA256 of `{timestamp}.{rawBody}`). operationId: createCheckoutSession parameters: - name: Idempotency-Key in: header required: false description: >- Optional idempotency key. Replaying the same key for the same organisation returns the existing session. schema: type: string example: order-42 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateCheckoutRequest' example: user: id: cust_123 email: customer@example.com username: alice items: - name: Pro plan quantity: 1 unit_price: 5000 product_id: prod_pro currency: XAF expires_in_minutes: 30 metadata: order_id: ord_1001 responses: '201': description: Checkout session created (or idempotent replay). content: application/json: schema: $ref: '#/components/schemas/CheckoutSessionMerchantResponse' '400': description: Invalid request body (missing items, bad amounts, etc.). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Missing or invalid merchant signing headers / API key. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - WakapayKey: [] WakapayTimestamp: [] WakapaySignature: [] components: schemas: CreateCheckoutRequest: type: object required: - user - items - currency properties: user: $ref: '#/components/schemas/CheckoutUser' items: type: array minItems: 1 items: $ref: '#/components/schemas/CheckoutLineItem' currency: type: string description: >- Quote currency for line items (e.g. XAF, USD). Crypto amounts are derived from this total. example: XAF metadata: type: object additionalProperties: true example: order_id: ord_1001 expires_in_minutes: type: integer minimum: 5 maximum: 10080 default: 60 description: Session lifetime in minutes. example: 30 CheckoutSessionMerchantResponse: allOf: - $ref: '#/components/schemas/CheckoutSessionPublicResponse' - type: object properties: organisation_id: type: string format: uuid organisation_name: type: - string - 'null' organisation_deleted: type: boolean owner_user_id: type: - string - 'null' format: uuid checkout_url: type: string format: uri description: Hosted checkout URL to open for the payer. example: >- https://checkout.wakapay.cash/pay/550e8400-e29b-41d4-a716-446655440000 items: type: array items: type: object properties: name: type: string quantity: type: integer unit_price: type: string total_price: type: string product_id: type: - string - 'null' metadata: type: object additionalProperties: true created_at: type: string format: date-time 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 CheckoutUser: type: object required: - id - email properties: id: type: string description: Your internal customer id. example: cust_123 email: type: string format: email example: customer@example.com username: type: string example: alice CheckoutLineItem: type: object required: - name - quantity - unit_price properties: name: type: string example: Pro plan quantity: type: integer minimum: 1 example: 1 unit_price: type: number minimum: 0 description: Unit price in the checkout `currency`. example: 5000 product_id: type: string example: prod_pro CheckoutSessionPublicResponse: type: object properties: session_id: type: string format: uuid status: type: string enum: - pending - waiting_payment - partial - paid - expired - failed example: waiting_payment source: type: string example: API from_payment_link: type: boolean anonymous: type: boolean requires_payer_identity: type: boolean identity_options: type: array items: type: string product_payment_link_id: type: - string - 'null' format: uuid total_amount_crypto: type: - string - 'null' example: '8.33333333' crypto_currency: type: - string - 'null' example: USDT crypto_options: type: array items: $ref: '#/components/schemas/CryptoPaymentOption' fiat_currency: type: string example: XAF total_amount_fiat: type: string example: '5000.00000000' wallet_address: type: string description: Merchant receiving wallet. supported_networks: type: array items: type: string expires_at: type: string format: date-time overpaid: type: boolean bound_tx_hash: type: - string - 'null' payer_wallet_address: type: - string - 'null' chain_id: type: - string - 'null' user: type: object properties: id: type: string email: type: - string - 'null' telegram_id: type: - string - 'null' username: type: - string - 'null' CryptoPaymentOption: type: object properties: ticker: type: string example: USDT id: type: string example: tether unit_price_fiat: type: string description: Unit price of 1 crypto in the session quote currency. example: '600.00000000' amount: type: string description: Crypto amount the payer must send. example: '8.33333333' securitySchemes: WakapayKey: type: apiKey in: header name: X-Wakapay-Key description: Organisation API public key (merchant). WakapayTimestamp: type: apiKey in: header name: X-Wakapay-Timestamp description: Unix timestamp in milliseconds. Must be within ±5 minutes. WakapaySignature: type: apiKey in: header name: X-Wakapay-Signature description: HMAC-SHA256 hex of `{timestamp}.{rawBody}` using the API key secret. ````