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

# Create or replay a crypto checkout session

> Requires a merchant API key and eligible business. Decimal strings preserve exact amounts.
Reuse the same Idempotency-Key and identical payload after a timeout. Reference and key are
scoped to the merchant and test/live environment; conflicting details return409.
API-key type fixes test/live mode. Browser flags cannot switch a session's mode.
Callback delivery is transactional and signed with the merchant webhook secret. Browser
return URLs and iframe messages are display signals, not proof to fulfill an order.




## OpenAPI

````yaml /api-reference/openapi.json post /api/v1/checkout/create
openapi: 3.0.3
info:
  contact:
    email: support@rachfinance.com
    name: Rach Finance Support
  description: >
    Complete REST API for the Rach Finance platform — covering authentication,
    KYC, crypto payment gateway,

    Wallet-as-a-Service (WaaS) HD wallets, remittance/FX transfers, OTC trading,
    virtual accounts,

    analytics, webhooks, push notifications, and all admin operations.


    ## Authentication

    Three authentication methods are supported depending on the endpoint group:


    | Method | Header | Used For |

    |--------|--------|----------|

    | JWT Bearer | `Authorization: Bearer <token>` | Dashboard / user-facing
    endpoints |

    | API Key | `X-API-Key: <key>` | Server-to-server integrations (remittance,
    checkout, WaaS) |

    | Admin Token | `X-Admin-Token: <token>` | Admin-only operations |


    ## API Key Environments


    Every business has two server-to-server API keys. The key **prefix is
    authoritative** —

    the environment is determined by which key you send, not a toggle in your
    dashboard:


    | Prefix | Type | Behaviour |

    |--------|------|-----------|

    | `test_sk_` | Test (sandbox) | Testnet addresses, no real funds move, no
    blockchain confirmations needed |

    | `live_sk_` | Production | Mainnet addresses, real transactions, webhooks
    fire on real confirmations |


    **Use the same code path for both environments** — swap the key, not the
    logic.

    The `is_test_mode` flag is locked onto every checkout session and wallet
    operation

    at the moment the request is authenticated, so mode cannot drift mid-flow
    even if

    you later toggle sandbox mode in the dashboard.


    Sandbox toggle (`POST /api/v1/api-keys/toggle-sandbox`) only affects legacy
    keys

    (no prefix). If you use prefixed keys it has no effect.


    ## Base URL

    `https://api.rach.finance/api/v1/`


    (Rach CaaS — Card-as-a-Service — is served separately at
    `https://api.rach.finance/caas/api/v1/`.)


    ## Official SDKs


    Client libraries covering every endpoint on this page:


    | Language | Install | Source |

    |----------|---------|--------|

    | **JavaScript / Node** | `npm install rachfinance` | `sdk/javascript/` |

    | **Python** | `pip install rachfinance` | `sdk/python/` |

    | **Go** | `go get github.com/rach-finance/rachfinance-go` | `sdk/go/` |

    | **Flutter / Dart** | add `rachfinance` to `pubspec.yaml` | `sdk/flutter/`
    |


    **JavaScript quick start:**

    ```js

    const RachFinance = require('rachfinance');

    const rach = new RachFinance({ apiKey: 'live_sk_...' });

    const session = await rach.checkout.create({ amount: 100, currency: 'USD',
      customerEmail: 'user@example.com', reference: 'ORDER-001' });
    ```


    **Python quick start:**

    ```python

    from rachfinance import RachFinance

    rach = RachFinance(api_key='live_sk_...')

    session = rach.checkout.create(amount=100, currency='USD',
        customer_email='user@example.com', reference='ORDER-001')
    ```


    **Go quick start:**

    ```go

    c, _ := rachfinance.New(rachfinance.WithAPIKey("live_sk_..."))

    session, err := c.Checkout.Create(ctx, rachfinance.CreateCheckoutRequest{
        Amount: 100, Currency: "USD",
        CustomerEmail: "user@example.com", Reference: "ORDER-001",
    })

    ```


    **Flutter quick start:**

    ```dart

    final rach = RachFinance(apiKey: 'live_sk_...');

    final session = await rach.checkout.create(
        amount: 100, currency: 'USD',
        customerEmail: 'user@example.com', reference: 'ORDER-001');
    ```


    ## Common Error Format

    ```json

    { "error": "Human-readable error message" }

    ```
  title: Rach Finance API
  version: 1.0.0
servers:
  - url: https://api.rach.finance
security: []
tags:
  - name: Checkout (Crypto Gateway)
  - name: WaaS (Wallet-as-a-Service)
  - description: >
      Unified token swap API for merchants. Same-chain swaps on POL/BSC are
      executed via the

      Rach FiatSwapV2 smart contract; cross-chain pairs are routed through LiFi.
      Merchants

      consume one API — routing is invisible to them.


      **Auth:** Quote is public. Execute and history require `X-API-Key`.
    name: Swap
  - description: >
      Real-time crypto market data service — included with every merchant
      account.

      Prices for 100+ coins served from Rach's edge cache with no additional
      setup required.


      **Auth:** `X-API-Key` or `Authorization: Bearer <key>`. Health check is
      public.


      **Rate limit:** 120 REST requests per merchant per minute.


      **WebSocket:** Connect to `/v1/market/ws?key=<api-key>`, send a subscribe
      message, then receive

      a snapshot immediately followed by real-time price ticks as they change.
    name: Market Data
  - name: Value-Added Services
    description: >
      Airtime and data top-ups, gift cards, and utility bill payments — one
      service over

      three product families, with one order model and one status vocabulary.


      You hold a **prepaid balance**, funded with USDT or USDC on Polygon or
      BSC, and set

      your own margin on top of the price Rach quotes you. Every purchase debits
      that

      balance before anything is spent with the provider, and a failed order is
      refunded

      automatically.


      Three rules worth knowing before you integrate:


      1. `reference` is your idempotency key and must be **reused on retries** —
      repeating
         it returns the original order rather than buying twice.
      2. Amounts are validated against each operator's real denomination rules
      before any
         money moves, so a bad amount is a clean 400.
      3. A **503** means the platform is topping up its own provider balance:
      nothing was
         attempted and you were not charged.
paths:
  /api/v1/checkout/create:
    post:
      tags:
        - Checkout (Crypto Gateway)
      summary: Create or replay a crypto checkout session
      description: >
        Requires a merchant API key and eligible business. Decimal strings
        preserve exact amounts.

        Reuse the same Idempotency-Key and identical payload after a timeout.
        Reference and key are

        scoped to the merchant and test/live environment; conflicting details
        return409.

        API-key type fixes test/live mode. Browser flags cannot switch a
        session's mode.

        Callback delivery is transactional and signed with the merchant webhook
        secret. Browser

        return URLs and iframe messages are display signals, not proof to
        fulfill an order.
      parameters:
        - description: >-
            Stable order-attempt key. Reuse after uncertainty; never generate a
            new key for the same retry.
          in: header
          name: Idempotency-Key
          schema:
            maxLength: 180
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCheckoutRequest'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateCheckoutResponse'
          description: Session created, or original session replayed.
        '400':
          description: >-
            Invalid amount, currency, address, asset, callback or embed/return
            URL.
        '401':
          description: Missing or invalid API credential.
        '402':
          description: Subscription or monthly transaction entitlement prevents creation.
        '403':
          description: Business or requested live access is not approved.
        '409':
          description: Reference or Idempotency-Key conflicts with different details.
        '503':
          description: A required service or verified rail is unavailable.
      security:
        - ApiKeyAuth: []
components:
  schemas:
    CreateCheckoutRequest:
      properties:
        amount:
          description: >-
            Exact positive decimal amount. A decimal string avoids binary
            floating-point rounding.
          oneOf:
            - example: '49.95000001'
              type: string
            - exclusiveMinimum: true
              minimum: 0
              type: number
        callback_url:
          description: >-
            Public HTTPS webhook override. Omit to use the configured merchant
            webhook URL. Never a browser redirect.
          format: uri
          type: string
        currency:
          enum:
            - USD
            - USDT
            - USDC
          type: string
        customer_email:
          format: email
          type: string
        customer_name:
          type: string
        description:
          type: string
        embed_origin:
          description: >-
            Exact HTTPS origin allowed to embed this session; loopback HTTP is
            allowed only in test mode.
          format: uri
          type: string
        metadata:
          additionalProperties: true
          type: object
        network:
          description: >-
            Optional asset-network code. Use the public session available_assets
            catalogue.
          type: string
        payment_method:
          default: crypto
          enum:
            - crypto
          type: string
        reference:
          type: string
          description: >-
            Stable merchant order reference, scoped to business and API-key
            environment.
        return_url:
          description: HTTPS browser destination after payment; never financial proof.
          format: uri
          type: string
      required:
        - amount
        - currency
        - reference
      type: object
    CreateCheckoutResponse:
      properties:
        amount:
          description: Legacy numeric display amount. Use amount_exact for accounting.
          type: number
        amount_exact:
          example: '49.95000001'
          type: string
        charged_amount_exact:
          description: >-
            Actual verified settled total; differs from requested amount_exact
            on overpayment.
          type: string
        currency:
          type: string
        deposit_address:
          type: string
        embed_url:
          format: uri
          type: string
        expires_at:
          format: date-time
          type: string
        instructions:
          additionalProperties:
            type: string
          type: object
        invoice_currency:
          type: string
          description: Original invoice currency, retained after asset selection.
        is_test_mode:
          description: Immutable API-key environment for this session.
          type: boolean
        network:
          type: string
        payment_method:
          enum:
            - crypto
          type: string
        payment_url:
          format: uri
          type: string
        qr_code:
          type: string
        reference:
          type: string
        return_url:
          format: uri
          type: string
        session_id:
          format: uuid
          type: string
        status:
          enum:
            - pending
            - paid
            - expired
            - failed
          type: string
      required:
        - session_id
        - reference
        - amount_exact
        - currency
        - invoice_currency
        - status
        - is_test_mode
      type: object
  securitySchemes:
    ApiKeyAuth:
      description: |
        Business API key for server-to-server integrations.
        Key prefix determines the environment — no separate flag needed:
        `test_sk_*` = sandbox/testnet, `live_sk_*` = production/mainnet.
      in: header
      name: X-API-Key
      type: apiKey

````

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