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

# Create Checkout

> Create a fiat on-ramp checkout session

Creates a checkout session for a fiat-to-crypto purchase. Returns a `checkoutUrl` that you redirect the user to for payment completion.

<ParamField body="fiatCurrency" type="string" required>
  The fiat currency code (e.g., `USD`, `EUR`, `GBP`).
</ParamField>

<ParamField body="cryptoAsset" type="string" required>
  The crypto asset symbol (e.g., `ETH`, `USDC`).
</ParamField>

<ParamField body="chainId" type="number" required>
  The chain ID to receive crypto on.
</ParamField>

<ParamField body="fiatAmount" type="number" required>
  The fiat amount to spend.
</ParamField>

<ParamField body="paymentMethod" type="string" required>
  Payment method: `credit_card`, `debit_card`, or `bank_transfer`.
</ParamField>

<ParamField body="walletAddress" type="string" required>
  The wallet address to receive crypto.
</ParamField>

<ParamField body="redirectUrl" type="string">
  URL to redirect the user to after payment. The order UID will be appended as a query parameter.
</ParamField>

<ParamField body="externalId" type="string">
  Your own reference ID for this order.
</ParamField>

<ResponseExample>
  ```json 200 theme={"system"}
  {
    "data": {
      "orderUid": "ord_abc123def456",
      "checkoutUrl": "https://checkout.rampnow.io/session/sess_xyz789",
      "fiatCurrency": "USD",
      "fiatAmount": 100,
      "cryptoAsset": "ETH",
      "chainId": 1,
      "estimatedCryptoAmount": "0.029615",
      "walletAddress": "0xYourAddress",
      "expiresAt": 1711236377,
      "status": "CREATED"
    },
    "error": null,
    "meta": {
      "requestId": "r8a9b0c1-d2e3-4567-1234-678901234567",
      "timestamp": 1711234578,
      "rateLimit": {
        "limit": 2000,
        "remaining": 1982,
        "reset": 1711234627
      }
    }
  }
  ```
</ResponseExample>

<CodeGroup>
  ```typescript TypeScript theme={"system"}
  const checkout = await client.createOnrampCheckout({
    fiatCurrency: "USD",
    cryptoAsset: "ETH",
    chainId: 1,
    fiatAmount: 100,
    paymentMethod: "credit_card",
    walletAddress: "0xYourAddress",
    redirectUrl: "https://yourapp.com/onramp/complete",
    externalId: "order-12345",
  });

  // Redirect the user to complete payment
  console.log("Redirect to:", checkout.data.checkoutUrl);
  console.log("Track with order UID:", checkout.data.orderUid);
  ```

  ```bash cURL theme={"system"}
  curl -X POST "https://api.hypermid.io/v1/onramp/checkout" \
    -H "Content-Type: application/json" \
    -H "X-API-Key: your-api-key" \
    -d '{
      "fiatCurrency": "USD",
      "cryptoAsset": "ETH",
      "chainId": 1,
      "fiatAmount": 100,
      "paymentMethod": "credit_card",
      "walletAddress": "0xYourAddress",
      "redirectUrl": "https://yourapp.com/onramp/complete"
    }'
  ```

  ```go Go theme={"system"}
  body := `{
    "fiatCurrency": "USD",
    "cryptoAsset": "ETH",
    "chainId": 1,
    "fiatAmount": 100,
    "paymentMethod": "credit_card",
    "walletAddress": "0xYourAddress",
    "redirectUrl": "https://yourapp.com/onramp/complete"
  }`

  req, _ := http.NewRequest("POST",
      "https://api.hypermid.io/v1/onramp/checkout",
      strings.NewReader(body))
  req.Header.Set("Content-Type", "application/json")
  req.Header.Set("X-API-Key", "your-api-key")
  resp, _ := http.DefaultClient.Do(req)
  ```
</CodeGroup>

<Warning>
  Checkout URLs expire. Redirect the user promptly after creating the session.
</Warning>


## OpenAPI

````yaml POST /v1/onramp/checkout
openapi: 3.0.3
info:
  title: Hypermid Partner API
  version: 1.0.0
  description: >-
    Cross-chain swap aggregator API. Supports 30+ EVM chains, Solana, Bitcoin,
    Sui, and Near Intents chains (NEAR, TON, Tron, XRP, etc.).


    ## Authentication

    Pass your API key via the `X-API-Key` header. Public endpoints work without
    a key (anonymous tier). Partner endpoints (`/v1/partner/*`) require a valid
    key.


    ## Rate Limits

    - **Anonymous**: 30 requests/minute (per IP)

    - **Partner (authenticated)**: 100 requests/minute (per API key)


    These limits are designed for human-driven widget usage and mirror our
    upstream aggregator (LiFi) limits to prevent any single user from exhausting
    shared quota.


    Rate limit info is returned in `meta.rateLimit` on every response.


    ## Response Envelope

    All responses follow the shape:

    ```json

    { "data": <T | null>, "error": <{ code, message, details? } | null>, "meta":
    { "requestId", "timestamp", "rateLimit?" } }

    ```
  contact:
    name: Hypermid
    url: https://hypermid.io
servers:
  - url: https://api.hypermid.io
    description: Production
security:
  - ApiKeyAuth: []
  - {}
tags:
  - name: Swap
    description: Cross-chain swap quoting, routing, status, and reference data
  - name: Execute
    description: Transaction execution and deposit management for Near Intents swaps
  - name: On-Ramp
    description: Fiat-to-crypto on-ramp via RampNow
  - name: Partner
    description: Partner account, analytics, and webhook management (requires X-API-Key)
  - name: Tracking
    description: Swap event tracking for partner attribution
  - name: System
    description: Health check and API metadata
paths:
  /v1/onramp/checkout:
    post:
      tags:
        - On-Ramp
      summary: Create a fiat-to-crypto checkout session
      description: >-
        Creates a hosted checkout session. Returns a redirect URL where the user
        completes payment.
      operationId: createOnrampCheckout
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OnrampCheckoutRequest'
      responses:
        '200':
          description: Checkout session created
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/OnrampCheckoutResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '502':
          $ref: '#/components/responses/UpstreamError'
components:
  schemas:
    OnrampCheckoutRequest:
      type: object
      properties:
        walletAddress:
          type: string
          description: Destination wallet address
        cryptoToken:
          type: string
          example: USDC
        cryptoChain:
          type: string
          example: base
        fiatCurrency:
          type: string
          example: USD
        fiatAmount:
          type: number
          example: 50
        email:
          type: string
          format: email
        paymentMode:
          type: string
          example: card
        returnUrl:
          type: string
          description: >-
            Redirect URL after payment. Use __UID__ as placeholder for the order
            ID.
      required:
        - walletAddress
        - cryptoToken
        - cryptoChain
        - fiatCurrency
        - fiatAmount
    ApiResponse:
      type: object
      properties:
        data:
          description: Response payload (null on error)
        error:
          nullable: true
          type: object
          properties:
            code:
              type: string
              example: INVALID_PARAMS
            message:
              type: string
              example: 'Missing required parameters: fromChain'
            details:
              type: object
              additionalProperties: true
          required:
            - code
            - message
        meta:
          $ref: '#/components/schemas/Meta'
      required:
        - data
        - error
        - meta
    OnrampCheckoutResponse:
      type: object
      properties:
        redirectUrl:
          type: string
          description: URL to redirect the user to for payment
        orderUid:
          type: string
        externalOrderUid:
          type: string
    Meta:
      type: object
      properties:
        requestId:
          type: string
          format: uuid
        timestamp:
          type: integer
          description: Unix epoch seconds
        rateLimit:
          type: object
          properties:
            limit:
              type: integer
            remaining:
              type: integer
            reset:
              type: integer
              description: Unix epoch seconds when the window resets
      required:
        - requestId
        - timestamp
  responses:
    BadRequest:
      description: Invalid or missing parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiResponse'
    UpstreamError:
      description: Upstream provider error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiResponse'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: >-
        Partner API key. Optional for public endpoints, required for
        /v1/partner/*.

````