How to Accept Payments with the Blockra API

This guide walks through accepting a payment end to end: creating a checkout session for a single customer, sending them to the hosted payment page, and confirming the result via a webhook. The funds land directly in your own wallet — Blockra never holds them.

There are two ways to take money. A checkout session (this guide) is single-use — one customer, one order — and is what you create from your server at the moment of purchase. A payment link is reusable and shareable — one URL you hand out or embed. The direct POST /payments endpoint has been removed; every payment now starts from a session or a link.

Prerequisites

A Blockra account (app.blockra.io) with a wallet set up — this is where crypto lands. See Set Up Your Wallet; it is created in your browser under Settings → Payment Methods, and takes about a minute. To take cards as well, connect your Stripe account on the same page.
An API key with the payments:write and payments:read scopes — see Authentication.

Step-by-step

Create a checkout session

Call POST /checkout/sessions with the amount, currency, and where to send the buyer afterwards. Blockra returns a hosted checkout url.

curl https://api.blockra.io/checkout/sessions \
  -X POST \
  -H "X-API-Key: bk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 9.99,
    "currency": "USD",
    "reference": "order_1234",
    "success_url": "https://store.example.com/thanks",
    "cancel_url": "https://store.example.com/cart"
  }'

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: 9.99,
    currency: "USD",
    reference: "order_1234",
    success_url: "https://store.example.com/thanks",
    cancel_url: "https://store.example.com/cart",
  }),
});
const { data } = await res.json();

import requests, os

res = requests.post(
    "https://api.blockra.io/checkout/sessions",
    headers={"X-API-Key": os.environ["BLOCKRA_API_KEY"]},
    json={
        "amount": 9.99,
        "currency": "USD",
        "reference": "order_1234",
        "success_url": "https://store.example.com/thanks",
        "cancel_url": "https://store.example.com/cart",
    },
)
data = res.json()["data"]

Response

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

Send the customer to checkout

Redirect the buyer to data.url, or open it in an embedded checkout so they pay without leaving your site. On the page they pick a coin, see the exact amount and a QR code, and pay. The quote is valid for 30 minutes.

Confirm via webhook

Register an endpoint under Developers → Webhooks and listen for payment.completed. Match the event to your order with the reference you passed:

payment.completed event

{
  "type": "payment.completed",
  "created": "2026-07-08T12:52:00.000Z",
  "data": {
    "id": "pay_a1b2c3d4e5f6g7h8i9j0k1l2",
    "status": "completed",
    "fiat_amount": 9.99,
    "reference": "order_1234"
  }
}

By the time this fires, the funds are already in your wallet. See Webhooks for signature verification.

Poll the payment status (alternative)

If you can’t receive webhooks, poll GET /payments/{id} until status is terminal. The payment id arrives on the payment.* webhooks, or you can list payments filtered by your reference.

Node.js

async function waitForPayment(id: string) {
  while (true) {
    const res = await fetch(`https://api.blockra.io/payments/${id}`, {
      headers: { "X-API-Key": process.env.BLOCKRA_API_KEY! },
    });
    const { data } = await res.json();
    if (["completed", "overpaid", "expired", "failed", "cancelled"].includes(data.status)) {
      return data;
    }
    await new Promise((r) => setTimeout(r, 5000)); // poll every 5s
  }
}

Prefer webhooks over polling — they are faster and use fewer API requests.

Handling edge cases

What happens if a payment expires?

If the buyer doesn’t send funds within the 30-minute quote window, the payment status changes to expired and you receive a payment.expired webhook. Create a new session if the buyer still wants to complete the purchase — the exchange rate is re-locked.

What if the buyer sends too little or too much?

Blockra marks the payment underpaid or overpaid. Because the deposit address is yours, any coins the buyer sent are already in your wallet — resolve the order with them (refund or top-up) directly. The webhook payload and dashboard show the exact amounts.

How do I associate a payment with a customer?

Pass customer_email when creating the session. Blockra creates a customer record (or matches an existing one) and links the payment to it. Retrieve it from GET /payments/{id} in the customers field.

Get Started

Integration

How to Accept Payments with the Blockra API

Prerequisites

Step-by-step

Handling edge cases

​Prerequisites

​Step-by-step

​Handling edge cases

Prerequisites

Step-by-step

Handling edge cases