Integrate Blockra Hosted Checkout for Crypto Payments

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 instead when you need full control over the payment UI or want to restrict the buyer to a single asset.

Creating a checkout session

Create the session

Call POST /checkout/sessions with the amount, currency, and optional redirect URLs. Requires the payments:write scope.

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"
  }'

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

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"]

The response contains the session id and the hosted url:

Response

{
  "data": {
    "id": "cs_7h8i9j0k1l2m3n4o5p6q",
    "url": "https://checkout.blockra.io/cs_7h8i9j0k1l2m3n4o5p6q"
  },
  "error": null
}

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.

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.

Always verify payment completion via a webhook or by calling GET /payments/{id}. A buyer could navigate directly to success_url without paying.

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.

{
  "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:

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

​When to use hosted checkout

​Creating a checkout session

​Omitting the amount

​Pre-filling customer email

When to use hosted checkout

Creating a checkout session

Omitting the amount

Pre-filling customer email