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

# Integrate Blockra Hosted Checkout for Crypto Payments

> Create a Blockra checkout session and redirect your buyer to a hosted payment page. Blockra handles coin selection, deposit UI, and confirmation.

Blockra's hosted checkout removes the need to build a coin-selection UI or a deposit-address screen yourself. You create a checkout session, redirect the buyer to the returned URL, and Blockra handles everything from there — the buyer picks their preferred coin, gets a deposit address, and pays. This guide shows you how to integrate hosted checkout end to end.

## When to use hosted checkout

Use hosted checkout when:

* You want to accept multiple coins without building a coin-picker UI
* You want Blockra to manage the deposit timer and UI state
* You are integrating Blockra into an existing e-commerce flow where a redirect is acceptable

Use the [direct payment API](/guides/accept-payments) instead when you need full control over the payment UI or want to restrict the buyer to a single asset.

## Creating a checkout session

<Steps>
  <Step title="Create the session">
    Call `POST /checkout/sessions` with the amount, currency, and optional redirect URLs. Requires the `payments:write` scope.

    <CodeGroup>
      ```bash cURL theme={null}
      curl https://api.blockra.io/checkout/sessions \
        -X POST \
        -H "X-API-Key: bk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
        -H "Content-Type: application/json" \
        -d '{
          "amount": 49.00,
          "currency": "USD",
          "label": "Pro plan — annual",
          "reference": "sub_5678",
          "success_url": "https://your-site.com/thanks",
          "cancel_url": "https://your-site.com/checkout"
        }'
      ```

      ```ts Node.js theme={null}
      const res = await fetch("https://api.blockra.io/checkout/sessions", {
        method: "POST",
        headers: {
          "X-API-Key": process.env.BLOCKRA_API_KEY!,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          amount: 49.00,
          currency: "USD",
          label: "Pro plan — annual",
          reference: "sub_5678",
          success_url: "https://your-site.com/thanks",
          cancel_url: "https://your-site.com/checkout",
        }),
      });
      const { data } = await res.json();
      // redirect buyer to data.url
      ```

      ```python Python theme={null}
      import requests, os

      res = requests.post(
          "https://api.blockra.io/checkout/sessions",
          headers={"X-API-Key": os.environ["BLOCKRA_API_KEY"]},
          json={
              "amount": 49.00,
              "currency": "USD",
              "label": "Pro plan — annual",
              "reference": "sub_5678",
              "success_url": "https://your-site.com/thanks",
              "cancel_url": "https://your-site.com/checkout",
          },
      )
      data = res.json()["data"]
      # redirect buyer to data["url"]
      ```
    </CodeGroup>

    The response contains the session `id` and the hosted `url`:

    ```json Response theme={null}
    {
      "data": {
        "id": "cs_7h8i9j0k1l2m3n4o5p6q",
        "url": "https://checkout.blockra.io/cs_7h8i9j0k1l2m3n4o5p6q"
      },
      "error": null
    }
    ```
  </Step>

  <Step title="Redirect the buyer">
    Send the buyer to `data.url`. Blockra's checkout page lets them select a coin, see the exact deposit amount, and send payment from their wallet.
  </Step>

  <Step title="Receive the result">
    When the payment completes or the buyer cancels, Blockra redirects them to your `success_url` or `cancel_url`. For server-side confirmation, listen for the `payment.completed` webhook — do not rely solely on the redirect.

    <Warning>
      Always verify payment completion via a [webhook](/webhooks) or by calling `GET /payments/{id}`. A buyer could navigate directly to `success_url` without paying.
    </Warning>
  </Step>
</Steps>

## Omitting the amount

If you omit `amount` from the request, Blockra's checkout page will display an amount entry field so the buyer can specify how much they want to pay. This is useful for donation flows or open-ended invoices.

```json theme={null}
{
  "currency": "USD",
  "label": "Donation",
  "reference": "donate_2026",
  "success_url": "https://your-site.com/thanks"
}
```

## Pre-filling customer email

Pass `customer_email` to pre-fill the email field on the checkout page and associate the payment with a customer record:

```json theme={null}
{
  "amount": 49.00,
  "currency": "USD",
  "customer_email": "buyer@example.com",
  "success_url": "https://your-site.com/thanks"
}
```