DEV Community: Blockonomics

Bitcoin Payment Buttons and Widgets in Node.js with Blockonomics (no checkout UI to build)

Blockonomics — Thu, 11 Jun 2026 13:10:12 +0000

📌 TL;DR – What You’ll Build
A fully functional Bitcoin payment flow for your Node.js app:

✅ One-click “Pay with Bitcoin” button that opens a hosted checkout modal

✅ Inline payment widget (optional)

✅ Automatic order tracking via webhooks

✅ SQLite order storage for reconciliation

✅ Admin dashboard to view all Blockonomics orders

Here's a collection of runnable Node.js demos showing different ways to accept cryptocurrency payments with Blockonomics. Each demo lives in its own self-contained folder with its own package.json, source, and README. https://github.com/blockonomics/nodejsdemo

1) Overview: Why Skip Building Your Own Checkout UI?

If you’ve ever built a Bitcoin checkout from scratch, you know the pain: generate addresses, monitor transactions, handle confirmations, send emails, manage timeouts.

Building a Bitcoin checkout from scratch gives you ultimate control. With the Receive Payments API, you handle the address generation, QR codes, and order states yourself. But sometimes, that’s overkill. If you want to skip the heavy lifting, the Blockonomics Payment Buttons and Widgets API offers a faster route. You simply create a product via the API, drop in a button, and let Blockonomics manage the checkout UI, payment monitoring, and confirmation emails. In this post, we’ll walk through the Node.js and HTML implementation for both flows, and show you how to use the Merchant Orders API GET /api/merchant_orders to seamlessly sync transactions back to your database.

There are two integration models in the Blockonomics API, and they sit at opposite ends of the build-vs-buy axis:

Concern	Receive Payments API	Checkouts / Payment Button API
Address generation	You call /api/new_address	Blockonomics
Checkout UI	You build it	Blockonomics-hosted modal/widget
Customer fields (email, name, etc.)	You build the form	Built-in to the widget
Order state machine	You manage it	Blockonomics
Order confirmation emails	You send them	Blockonomics
Best for	Fully custom flows	Drop-in checkout on existing sites

2) What we're building?

Let's build a small Express app that:

Creates a temporary product on demand (price, description, customer metadata) using POST /api/create_temp_product
Renders an HTML page with a Blockonomics Payment Button that opens the hosted checkout modal
Receives the Order Callback when payment state changes (status 0, 1, 2, or -1)
Fetches the full order via GET /api/merchant_order/{uuid} so we can reconcile against our own DB
Lists all orders via GET /api/merchant_orders for an admin dashboard

3) The architecture:

sequenceDiagram
    autonumber
    participant B as Customer browser
    participant S as Your Express server
    participant K as Blockonomics

    B->>S: GET /product/123
    S->>K: POST /api/create_temp_product
    K-->>S: temp product uid
    S-->>B: HTML page with <a class="blockoPayBtn" data-uid="...">
    B->>K: Click Pay button (hosted checkout modal opens)
    K-->>S: GET /webhook/order?status=0&uuid=...
    S->>K: GET /api/merchant_order/{uuid}
    K-->>S: full order details
    K-->>S: GET /webhook/order?status=2&uuid=...

4) Prerequisites

You already have these from earlier posts in the series; reusing them:

A Blockonomics account with an API key (Dashboard → Stores)
A Bitcoin wallet xpub attached to the store
Node.js 18+

You also need one new thing specific to the Buttons/Widget flow: a parent product configured in the dashboard.

Why a parent product?

The Checkouts API uses a parent/temp-product model:

The parent product is the template — it defines the default price, description, customer fields to collect, and success/cancel URLs.
Temp products are short-lived copies of the parent, created per order with any overrides you need.

Setting up the parent product

Go to Dashboard → Buttons & Links → Products
Click Create Product
Fill in: product name (e.g. "Default Product"), default price, description, currency
Configure which customer fields to collect (email, name, address, phone, custom field 1, custom field 2)

Set the Success URL (where the customer lands after paying) and Cancel URL
Save, then copy the widget UID — you'll pass this as parent_uid in API calls

Setting up the Order Hook

You also need to set the Order Hook URL under Dashboard → Buttons & Links → Options:

https://yourserver.com/webhook/order?secret=YOUR_SECRET

⚠️ Heads up: there are two different webhook URLs

The Payments callback lives under Stores (you set this up in an earlier post).

The Order Hook for Buttons & Links lives under Buttons & Links → Options.

They are separate. If you only configured the Payments callback, the Payment Button flow will not fire callbacks to your server.

Environment

mkdir blockonomics-buttons && cd blockonomics-buttons
npm init -y
npm install express axios better-sqlite3 dotenv
npm install --save-dev nodemon

# .env
BLOCKONOMICS_API_KEY=your_api_key
PARENT_PRODUCT_UID=b5c04c7c395011ea           # from step 6 above
ORDER_CALLBACK_SECRET=any_random_long_string
PORT=3000
PUBLIC_URL=http://localhost:3000

5) The Build

Step 1: Create a temporary product on demand

When a customer clicks "Buy" on your product page, you create a fresh temp product. The temp product inherits everything from the parent and lets you override price, description, and attach an extra_data field for whatever order metadata you need to reconcile later (your internal order ID, customer ID, SKU, anything).

// src/blockonomics.js
import axios from "axios";

const BASE = "https://www.blockonomics.co/api";

const client = axios.create({
    baseURL: BASE,
    headers: { Authorization: `Bearer ${process.env.BLOCKONOMICS_API_KEY}` },
});

/**
 * Create a temporary product (one-off) under a parent product.
 * Temp products are auto-deleted after 7 days; orders against them persist.
 *
 * @param {object} opts
 * @param {string} opts.parentUid - Widget UID of the parent product
 * @param {string} [opts.productName] - Override the product name
 * @param {string} [opts.productDescription] - e.g. "Red T-shirt size L"
 * @param {number} [opts.valueMinor] - Price in the smallest unit (e.g. cents/pence)
 * @param {string} [opts.extraData] - Anything you want echoed back on the order
 * @returns {Promise<{ uid: string }>}
 */
export async function createTempProduct({
    parentUid,
    productName,
    productDescription,
    valueMinor,
    extraData,
}) {
    const body = { parent_uid: parentUid };
    if (productName) body.product_name = productName;
    if (productDescription) body.product_description = productDescription;
    if (valueMinor != null) body.value = valueMinor;
    if (extraData) body.extra_data = extraData;

    const { data } = await client.post("/create_temp_product", body);
    // Response: { "uid": "f7570454529a11e7-1ee5f340" }
    return { uid: data.uid };
}

/**
 * Fetch a single order's details by UUID. Used after the order callback.
 */
export async function getMerchantOrder(uuid) {
    const { data } = await client.get(`/merchant_order/${uuid}`);
    return data;
}

/**
 * List all payment-button orders.
 * @param {number} [limit=500]
 */
export async function listMerchantOrders(limit = 500) {
    const { data } = await client.get("/merchant_orders", { params: { limit } });
    return data; // array of orders, newest first
}

A few things worth knowing about create_temp_product:

value is in the smallest unit of the currency (cents, pence, satoshis, etc.) — not the major unit. £5.00 in GBP = value: 500. This is the same convention Stripe uses; easy to overlook the first time.
All overridable fields are optional. If you omit value, the parent's price is used. Pass it when you want a dynamic price (e.g. cart total).
extra_data is the magic field. It's echoed back on the order and accessible via merchant_order/{uuid}. Put your internal order ID, user ID, cart hash — whatever you need to look up the order in your DB when the callback arrives. This is how you avoid the "callback arrives but I don't know which order it belongs to" problem.

Step 2: The product page with a Payment Button

The product page calls your /checkout endpoint, gets back a temp product UID, and renders a Blockonomics Payment Button bound to that UID.

// src/server.js
import "dotenv/config";
import express from "express";
import crypto from "node:crypto";
import { createTempProduct, getMerchantOrder, listMerchantOrders } from "./blockonomics.js";
import { db, upsertOrder, getOrderByUuid } from "./db.js";
const app = express();
app.use(express.json());
app.use(express.urlencoded({ extended: true }));
// Show a product page
app.get("/product/:productId", async (req, res) => {
    const productId = req.params.productId;
    // Pretend we look up the product from our DB. For the demo, hardcode:
    const product = {
        productId,
        name: "Vintage t-shirt",
        description: "Red, size L — pre-loved",
        priceMinor: 3000, // £30.00
        currency: "GBP",
    };
    // Generate an internal order ID we want echoed back on the callback
    const internalOrderId = `ord_${crypto.randomBytes(6).toString("hex")}`;
    // Create the temp product on Blockonomics
    const { uid } = await createTempProduct({
        parentUid: process.env.PARENT_PRODUCT_UID,
        productName: product.name,
        productDescription: product.description,
        valueMinor: product.priceMinor,
        extraData: internalOrderId,
    });
    // Persist a placeholder row so the callback handler can find this order
    upsertOrder({
        internalOrderId,
        blockonomicsUuid: null, // we get this on the first callback
        tempProductUid: uid,
        productName: product.name,
        valueMinor: product.priceMinor,
        currency: product.currency,
        status: "created",
    });
    res.send(`
<!doctype html>
<html>
<head>
    <title>Buy ${product.name}</title>
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <style>
        body { font-family: system-ui, sans-serif; max-width: 480px; margin: 2rem auto; padding: 1rem; }
        h1 { margin-bottom: 0.5rem; }
        .desc { color: #555; }
        .price { font-size: 1.5rem; font-weight: 600; margin: 1rem 0; }
        .pay { margin-top: 1.5rem; }
    </style>
</head>
<body>
    <h1>${product.name}</h1>
    <p class="desc">${product.description}</p>
    <p class="price">£${(product.priceMinor / 100).toFixed(2)}</p>
    <!-- The Blockonomics Payment Button -->
    <div class="pay">
        <a href="" class="blockoPayBtn" data-toggle="modal" data-uid="${uid}">
            <img width="160" src="https://www.blockonomics.co/img/pay_with_bitcoin_medium.png" alt="Pay with Bitcoin" />
        </a>
    </div>
    <script src="https://blockonomics.co/js/pay_button.js"></script>
</body>
</html>
    `);
});

The Payment Button is the snippet from the Blockonomics docs, reformatted for clarity:

<a href="" class="blockoPayBtn" data-toggle="modal" data-uid="UID_FROM_API">
    <img width="160" src="https://www.blockonomics.co/img/pay_with_bitcoin_medium.png" />
</a>
<script src="https://blockonomics.co/js/pay_button.js"></script>

When the customer clicks it, Blockonomics' hosted checkout modal opens over your page. They enter the customer fields you configured on the parent product, see the BTC amount, get a QR code, scan from their wallet, and watch the payment confirm — all without leaving your page. When they're done, they're redirected to the parent product's success URL.

Step 3: Embed a Widget instead (optional)

If you want the checkout inline on the page instead of in a modal, use the Widget snippet:

<div id="payment_area"></div>
<script src="https://blockonomics.co/js/pay_widget.js"></script>
<script>
    function pay() {
        Blockonomics.widget({
            msg_area: 'payment_area',
            uid: `${uid}`,
            email: 'customer@email.com' // optional pre-fill
        });
    }
    pay(); // auto-render on page load
</script>

The widget renders into the

you provide. Same checkout flow, just inline rather than modal. Useful for dedicated checkout pages or donation widgets where you want the BTC payment visible without an extra click.

When to use which:

Button → product pages, listings, "Pay with Bitcoin" on a checkout option list. Less visual real estate, opens modal on click.
Widget → dedicated checkout pages, donation pages, paywall unlocks. Inline, always visible.

Both hit the same UID, both fire the same Order Callback, both populate the same merchant_orders list.

Step 4: Handle the Order Callback

When the order state changes (customer started checkout, paid, fully confirmed, or errored), Blockonomics hits your Order Hook URL.Same shape as the payments callback from Monday's post: HTTP GET with query parameters. Easy gotcha LLMs and a lot of stale tutorials describe this as a JSON POST. It isn't.

The format is:

GET https://yourserver.com/webhook/order
?secret=YOUR_SECRET
&status=2
&uuid=2b0c7e2cd523458098b2

The status values for the Order Callback are slightly different from the Payments callback:

status	Meaning
-1	PAYMENT_ERROR — paid BTC amount doesn't match expected value
0	UNPAID (customer entered checkout, hasn't paid yet)
1	IN_PROCESS (transaction seen, awaiting confirmation)
2	PAID (fully confirmed)

Don't confuse this with the Payments callback status enum (0/1/2, where 1 means "partially confirmed"). The Order Callback uses different semantics: 1 here means "in process" (see table above), not "partially confirmed". They're separate APIs with separate state machines.

Notice that the callback only gives you status and uuid. To get the full order — customer email, amount paid, txid, extra_data — you call GET /api/merchant_order/{uuid}. Two calls is fine; it keeps the webhook payload tiny and means you always get the freshest order state from Blockonomics rather than a possibly-stale snapshot.

// src/server.js (continued)
app.get("/webhook/order", async (req, res) => {
    const { secret, status, uuid } = req.query;

    // 1. Verify the secret
    if (secret !== process.env.ORDER_CALLBACK_SECRET) {
        return res.status(403).send("forbidden");
    }

    // 2. Fetch the full order
    let order;
    try {
        order = await getMerchantOrder(uuid);
    } catch (err) {
        console.error(
            "merchant_order fetch failed:",
            err.response?.data || err.message
        );
        // Return 200 anyway so Blockonomics doesn't retry while we debug
        return res.status(200).send("ok");
    }

    // 3. Reconcile against our internal order using extra_data
    // (we set extra_data = internalOrderId when creating the temp product)
    const internalOrderId =
        order.data?.["Custom Field1"] || order.extra_data || null;

    // 4. Map status
    const statusInt = parseInt(status, 10);
    let derived = "unknown";
    if (statusInt === -1) derived = "error";
    if (statusInt === 0) derived = "unpaid";
    if (statusInt === 1) derived = "in_process";
    if (statusInt === 2) derived = "paid";

    // 5. Upsert (callback might fire before we've stored the uuid)
    upsertOrder({
        internalOrderId,
        blockonomicsUuid: uuid,
        tempProductUid: order.code,
        productName: order.name,
        valueMinor: order.value,
        currency: order.currency,
        status: derived,
        paidSatoshi: order.paid_satoshi,
        txid: order.txid,
        customerEmail: order.data?.emailid,
        customerName: order.data?.name,
    });

    // 6. Trigger business logic on paid
    if (derived === "paid") {
        await fulfillOrder(internalOrderId, order);
    }

    res.status(200).send("ok");
});

async function fulfillOrder(internalOrderId, order) {
    // Ship the t-shirt, send the receipt, etc.
    console.log(
        `✓ ORDER PAID: ${internalOrderId} — ${order.paid_satoshi} sats from ${order.data?.emailid}`
    );
}

The OrderResponse object from /api/merchant_order/{uuid} includes everything you need:

Field	Meaning
code	The temp product UID
order_id	Blockonomics' unique order ID
address	The BTC address used for this order
value	Order value in fiat (in the smallest unit, e.g. cents)
satoshi	Order value in satoshis
paid_satoshi	Actual amount paid in satoshis
txid	Transaction ID (nullable until paid)
status	Integer order status
data.emailid, data.name, etc.	Customer fields collected by the widget
data.Custom Field1/2	Whatever extra fields you configured
currency	Fiat currency code
timestamp	Unix timestamp of order creation

Pull what you need, persist it.

Step 5: The SQLite layer

// src/db.js
import Database from "better-sqlite3";

export const db = new Database("orders.db");

db.exec(`
CREATE TABLE IF NOT EXISTS orders (
    internalOrderId  TEXT PRIMARY KEY,
    blockonomicsUuid TEXT UNIQUE,
    tempProductUid   TEXT,
    productName      TEXT,
    valueMinor       INTEGER,
    currency         TEXT,
    status           TEXT NOT NULL,
    paidSatoshi      INTEGER,
    txid             TEXT,
    customerEmail    TEXT,
    customerName     TEXT,
    createdAt        INTEGER NOT NULL DEFAULT (strftime('%s','now')),
    updatedAt        INTEGER NOT NULL DEFAULT (strftime('%s','now'))
);

CREATE INDEX IF NOT EXISTS idx_orders_uuid ON orders(blockonomicsUuid);
CREATE INDEX IF NOT EXISTS idx_orders_status ON orders(status);
`);

const cols = [
    "internalOrderId",
    "blockonomicsUuid",
    "tempProductUid",
    "productName",
    "valueMinor",
    "currency",
    "status",
    "paidSatoshi",
    "txid",
    "customerEmail",
    "customerName",
];

export function upsertOrder(order) {
    const existing = db
        .prepare("SELECT * FROM orders WHERE internalOrderId = ?")
        .get(order.internalOrderId);

    if (!existing) {
        const placeholders = cols.map((c) => `@${c}`).join(", ");
        db.prepare(`
            INSERT INTO orders (${cols.join(", ")})
            VALUES (${placeholders})
        `).run(Object.fromEntries(cols.map((c) => [c, order[c] ?? null])));
        return;
    }

    // Only update non-null fields, so later callbacks don't blank out earlier data
    const updates = cols
        .filter((c) => order[c] != null && order[c] !== existing[c])
        .map((c) => `${c} = @${c}`);

    if (updates.length === 0) return;

    updates.push("updatedAt = strftime('%s','now')");

    db.prepare(`
        UPDATE orders SET ${updates.join(", ")}
        WHERE internalOrderId = @internalOrderId
    `).run({ ...order, internalOrderId: order.internalOrderId });
}

export function getOrderByUuid(uuid) {
    return db.prepare("SELECT * FROM orders WHERE blockonomicsUuid = ?").get(uuid);
}

// Why upsert: the callback at status 0 arrives before you've even stored the UUID locally
// (you only got the temp product UID back from create_temp_product, not the order UUID —
// that's only generated when the customer enters checkout).
// So you create a placeholder when the temp product is made, then the callback fills in the UUID,
// customer email, satoshi amount, txid, etc. as they become known.

// Step 6: An admin dashboard (using merchant_orders)
// The GET /api/merchant_orders endpoint returns every order across your account, newest first.
// Useful for an admin dashboard, daily reconciliation cron, or exporting to accounting.

// src/server.js
app.get("/admin/orders", async (req, res) => {
    const limit = parseInt(req.query.limit || "100", 10);

    // Fetch from Blockonomics (source of truth)
    const remote = await listMerchantOrders(limit);

    // Also pull our local snapshot for comparison
    const localByUuid = Object.fromEntries(
        db.prepare("SELECT * FROM orders").all().map((o) => [o.blockonomicsUuid, o])
    );

    // Reconcile: flag any orders Blockonomics knows about but we don't
    const enriched = remote.map((r) => ({
        ...r,
        localOrderId: localByUuid[r.order_id]?.internalOrderId || null,
        inSync: !!localByUuid[r.order_id],
    }));

    const drift = enriched.filter((o) => !o.inSync);

    res.json({
        total: enriched.length,
        drift: drift.length,
        orders: enriched.slice(0, 50),
    });
});

A few real-world uses for /api/merchant_orders:

Daily reconciliation cron. Once a day, fetch the last 24h of orders from Blockonomics and compare to your DB. Any drift gets emailed to ops. This is your safety net if a callback ever gets dropped.
CSV export for accounting. Paid orders → spreadsheet → accountant.
Refund decisioning. Customer complaints "I paid but didn't get the goods" — look up the order, confirm paid_satoshi >= satoshi, check txid on a block explorer, decide.
The limit parameter defaults to 500. For larger merchants, do it in chunks across multiple calls.

6) Which flow should you pick?

Now that you've seen both approaches in code, here's when to pick which:

Use case	Pick
Custom-designed checkout page, on-brand UI	Receive Payments API (Mon–Thu)
Drop-in "Pay with Bitcoin" button on a Shopify-style product page	Payment Button
Dedicated donation page or paywall	Widget
Selling 1 product with a fixed price	Either, Payment Button is faster
Selling 10,000 products with dynamic pricing	Payment Button with create_temp_product per checkout
You want the customer's email / phone collected automatically	Payment Button / Widget (built in)
You want full control of confirmation emails, partial-payment handling, RBF logic	Receive Payments API
You're integrating into an existing app with its own order management	Receive Payments API
Internal tooling for one-off invoices	Payment Button (or even just the dashboard UI, no code)

The two flows aren't mutually exclusive. A common pattern is: use the Payment Button for the public storefront (fast to ship, low maintenance) and the Receive Payments API for backend invoicing or subscription renewals where you want programmatic control.

7) Common errors and pitfalls

create_temp_product returns 400. Almost always a missing or wrong parent_uid. Re-copy it from the Buttons & Links → Products page in the dashboard. The UID has a hyphen in it — make sure you copied the whole thing.

The Payment Button renders but clicking it does nothing. The pay_button.js script either failed to load, or you have a CSP that blocks third-party scripts. Open dev tools → Network → check for the script. CSP needs script-src 'self' https://blockonomics.co.

value price looks 100x off in the checkout. You passed value: 30 thinking "£30" instead of value: 3000 for "£30.00". Same mistake everyone makes once with Stripe.

Order Callback never fires. Three usual suspects: (1) you set the Order Hook URL in the wrong place — it's under Buttons & Links → Options, not Stores; (2) your URL doesn't include the secret param so your handler rejects it as forbidden; (3) ngrok tunnel restarted with a new URL but the dashboard still points at the old one. The dashboard has a "Test callback" button — use it.

I get one callback but never a second one. Blockonomics fires callbacks on status changes. If a transaction goes straight from 0 (created) to 2 (confirmed) because the customer paid and waited for confirmation before closing their wallet, you might only see the 2 callback. Always fetch via merchant_order/{uuid} on the callbacks you do receive, rather than trying to reconstruct state from a sequence.

Order's extra_data is empty when I fetch it. Two things: (1) you didn't pass extra_data to create_temp_product, or (2) you're reading the wrong field — depending on how the dashboard is configured, your data can come back under extra_data, data["Custom Field1"], or description. Log the full order object once and you'll see exactly where Blockonomics put it for your setup.

8) Production checklist

Before turning the Payment Button flow live:

[ ] Parent product configured in dashboard with success/cancel URLs pointing at your domain
[ ] Order Hook URL configured under Buttons & Links → Options (not under Stores)
[ ] Order Hook secret matches ORDER_CALLBACK_SECRET in .env
[ ] extra_data set to your internal order ID on every create_temp_product call
[ ] Callback handler is idempotent (use the same webhook_events dedup table from
[ ] Callback handler returns 200 before doing heavy work
[ ] Daily reconciliation cron running against /api/merchant_orders to catch any missed callbacks
[ ] CSP allows https://blockonomics.co for script-src and frame-src
[ ] value is always in minor units (cents/pence) — write a helper, don't trust yourself to remember
[ ] Tested the full happy path on Bitcoin testnet before mainnet
[ ] Tested the -1 PAYMENT_ERROR path (send slightly less than the amount due) to confirm your error handling works

🔗 Resources

Blockonomics API Reference

GitHub Repo – Full Example Code

Previous Post: Receive Payments API in Node.js

Accept Bitcoin payments in Node.js with Blockonomics: a complete non-custodial guide

Blockonomics — Wed, 27 May 2026 04:19:44 +0000

In this tutorial you'll build a working Bitcoin checkout in Node.js using the Blockonomics API. Customers pay you in BTC, the payment lands directly in your wallet (Blockonomics never holds the funds), and your server gets notified via a webhook. No KYC, no custodian, no fiat conversion middleman. If you've tried adding crypto payments to a Node app before, you've probably hit the same wall I did: every "Bitcoin payment gateway" turns out to be a custodian. They hold the coins, they hand you fiat, and the moment something goes wrong with their bank rails, your customers get stuck mid-checkout.

This guide takes the other path. We're going to wire up a payment flow where:

The customer's BTC goes straight to your wallet — Blockonomics generates fresh receive addresses derived from an extended public key (xpub) you control.
Your server is notified by webhook the moment a payment hits the mempool, and again on confirmation.
There's no KYC, no custody, no chargebacks.

We’ll cover three key components: POST /api/new_address, GET /api/price, and the callback notification system. We’ll wrap up by building a complete checkout example running directly on mainnet.

The full tutorial is roughly 25 minutes of reading and 45 minutes of coding. Let's go.

What you'll build

A minimal Express server with three responsibilities:

POST /checkout — accepts an order (e.g. one t-shirt for £30 GBP), asks Blockonomics for a fresh BTC address, converts £30 to BTC at the current rate, stores the order, and returns a payment page URL.
GET /pay/:orderId — a simple HTML page showing the BTC address, the exact amount due in BTC, a QR code, and a live payment status that updates as the transaction confirms.
GET /webhook/blockonomics — receives callbacks from Blockonomics as the payment progresses through status=0 (unconfirmed), status=1 (partial), status=2 (confirmed).

We'll persist everything in SQLite so a callback arriving 20 minutes later can be matched back to the right order.

Prerequisites

Before writing any code, you need three things:

1. A Bitcoin wallet that gives you an extended public key (xpub)

Blockonomics is non-custodial, which means it derives receive addresses from your wallet's xpub — your private keys never leave your wallet. Nearly every modern Bitcoin wallet provides this xpub:

Electrum: Wallet → Information → Master Public Key
BlueWallet: Wallet → Settings → Show wallet xpub
Sparrow / Ledger / Trezor: each has a similarly named export option

Copy that string (it starts with xpub, ypub, or zpub depending on the address format) — you'll paste it into the Blockonomics dashboard, not into your code.

Never paste your seed phrase or private key anywhere. Only the xpub. The xpub allows us to safely generate new receiving addresses for your customers, but it has zero spending power.

2. A Blockonomics account and an API key

Go to Dashboard → Stores
Your API key is shown directly in the Stores section. Copy it.
In the same Stores section, attach your wallet by pasting in your xpub.
Set your HTTP Callback URL to where your server's webhook lives. For local development you'll want something like https://abc123.ngrok.io/webhook/blockonomics?secret=YOUR_SECRET — more on the secret in the webhook section.

📍 Where exactly is the API key? Dashboard → Stores. This is the current location as of November 2025. If a tutorial or LLM tells you to look under "Wallet Watcher" or "Merchants → API", that's outdated. The Stores section is the canonical place — and it's also where you rotate the key with the 🔄 button.

3. Node.js 18+ and the project skeleton

mkdir blockonomics-checkout && cd blockonomics-checkout

npm init -y

npm install express axios better-sqlite3 qrcode dotenv

npm install --save-dev nodemon

Create a .env file in the project root:

# .env
BLOCKONOMICS_API_KEY=your_api_key_from_the_blockonomics_dashboard
CALLBACK_SECRET=any_long_random_string_you_make_up
PORT=3000
PUBLIC_URL=http://localhost:3000

The CALLBACK_SECRET is a value you invent and include in your webhook URL — Blockonomics will echo it back to you on every callback, so you can verify the request actually came from them and not a random scanner hitting your endpoint.

Step 1: Generate a payment address

This is the single most important call in the entire integration. When a customer starts checkout, you ask Blockonomics for a fresh receive address derived from your xpub.

The endpoint is:

POST https://www.blockonomics.co/api/new_address

Authorization: Bearer YOUR_API_KEY

Query parameters:

Param	Required	Notes
match_callback	yes	A string Blockonomics will use to match against your configured callback URL. Partial matches work — you don't need to paste the full URL.
crypto	no	`BTC` (default) or `USDT`.
reset	no	`0` (default) generates a new address on each call; `1` reuses the last one. Must be the integer 0 or 1, not true/false.

Here's the wrapper, in src/blockonomics.js:

// src/blockonomics.js
import axios from "axios";

const BASE = "https://www.blockonomics.co/api";
const apiKey = process.env.BLOCKONOMICS_API_KEY;

const client = axios.create({
    baseURL: BASE,
    headers: { Authorization: `Bearer ${apiKey}` },
});

/**
 * Generate a fresh BTC receive address.
 *
 * @param {string} matchCallback - substring of your callback URL used to identify the store
 * @returns {Promise<{address: string}>}
 */
export async function newAddress(matchCallback) {
    const { data } = await client.post("/new_address", null, {
        params: { match_callback: matchCallback, crypto: "BTC", reset: 0 },
    });

    // Successful response shape: { address: "bc1q...", reset: 0 }
    return { address: data.address };
}

/**
 * Get current price of 1 BTC in a given fiat currency.
 *
 * @param {string} currency - "GBP", "USD", "EUR", etc.
 * @returns {Promise<number>} - price of 1 BTC in that currency
 */
export async function btcPrice(currency = "GBP") {
    const { data } = await client.get("/price", {
        params: { crypto: "BTC", currency },
    });

    // Response shape: { price: 127866.85 }
    return data.price;
}

A few things worth noting that the API docs make explicit:

The address is derived from your xpub — Blockonomics doesn't custody it. Funds sent to it land in your wallet.
Calling new_address again without reset=1 will give you the next address in the derivation chain. Each customer gets their own address. This is what makes order reconciliation clean: address ↔ order is one-to-one.
If you accidentally lose track of an address client-side (e.g. browser crashes mid-checkout), reset=1 gives you the most recent address back without burning a new one.

Step 2: Convert fiat price to BTC

Bitcoin prices move every second, so you can't hard-code a BTC amount on your product. Instead, you fetch the live BTC/GBP (or USD, EUR, etc.) rate at the moment of checkout and lock in the BTC amount for that order.

The btcPrice() helper above wraps GET /api/price. To work out how much BTC a £30 order costs:

const pricePerBtc = await btcPrice("GBP"); // e.g. 52000
const btcAmount = +(30 / pricePerBtc).toFixed(8); // 0.00057692 BTC

Bitcoin has 8 decimal places (1 BTC = 100,000,000 satoshis), so we round to 8. Store both the fiat amount and the BTC amount on the order — you'll need the BTC amount to verify the customer paid enough, and the fiat amount for your accounting.

Step 3: The order endpoint

Now we tie steps 1 and 2 together. When the user clicks "Pay with Bitcoin" on your site, your frontend POSTs to /checkout:

// src/server.js
import "dotenv/config";
import crypto from "node:crypto";
import express from "express";

import { btcPrice, newAddress } from "./blockonomics.js";
import { createOrder, getOrder } from "./db.js";

const app = express();
app.use(express.json());
app.use(express.urlencoded({ extended: true }));

app.post("/checkout", async (req, res) => {
    try {
        const { amountFiat = 30, currency = "GBP", productName = "T-shirt" } =
            req.body;

        // 1) Fetch live BTC price
        const pricePerBtc = await btcPrice(currency);
        const amountBtc = +(amountFiat / pricePerBtc).toFixed(8);

        // 2) Generate a fresh receive address
        // match_callback can be any substring of your configured callback URL.
        // We use the path because we only have one store.
        const matchCallback = "/webhook/blockonomics";
        const { address } = await newAddress(matchCallback);

        // 3) Persist the order so the webhook can find it later
        const orderId = crypto.randomBytes(8).toString("hex");
        createOrder({
            orderId,
            address,
            amountFiat,
            currency,
            amountBtc,
            pricePerBtc,
            productName,
            status: "pending",
        });

        res.json({
            orderId,
            paymentUrl: `${process.env.PUBLIC_URL}/pay/${orderId}`,
        });
    } catch (err) {
        console.error("checkout error:", err.response?.data || err.message);
        res.status(500).json({ error: "could not create order" });
    }
});

The key idea: store the address with the order the moment you create it. This is the single most common production bug in homemade Bitcoin checkouts — people generate an address, show it to the customer, and never write it down anywhere. When the webhook arrives 30 minutes later carrying that address, they have no way to match it back to an order. Always persist address ↔ orderId before you return a response to the customer.

Step 4: The payment page (showing address + QR)

The payment page just renders what's already in the database:

// src/server.js (continued)
import QRCode from "qrcode";

app.get("/pay/:orderId", async (req, res) => {
    const order = getOrder(req.params.orderId);
    if (!order) return res.status(404).send("Order not found");

    // bitcoin: URI is the standard format wallets understand
    const bip21 = `bitcoin:${order.address}?amount=${order.amountBtc}`;
    const qrDataUrl = await QRCode.toDataURL(bip21);

    res.send(`
<!doctype html>
<html>
    <head>
        <title>Pay with Bitcoin — ${order.productName}</title>
        <meta name="viewport" content="width=device-width, initial-scale=1" />
        <style>
            body { font-family: system-ui, sans-serif; max-width: 480px; margin: 2rem auto; padding: 1rem; }
            .qr { text-align: center; }
            .addr { word-break: break-all; font-family: monospace; background: #f4f4f4; padding: 0.75rem; border-radius: 6px; }
            .status { padding: 0.75rem; border-radius: 6px; margin-top: 1rem; }
            .pending { background: #fff3cd; }
            .confirmed { background: #d4edda; }
        </style>
    </head>
    <body>
        <h1>${order.productName}</h1>
        <p>Send <strong>${order.amountBtc} BTC</strong> (£${order.amountFiat}) to:</p>
        <div class="addr">${order.address}</div>
        <div class="qr"><img src="${qrDataUrl}" alt="Bitcoin QR code" /></div>
        <div class="status pending" id="status">Waiting for payment…</div>
        <script>
            // Poll for status updates every 5 seconds
            async function check() {
                const r = await fetch("/pay/${order.orderId}/status");
                const { status } = await r.json();
                const el = document.getElementById("status");

                if (status === "partial") {
                    el.textContent = "Payment received, waiting for confirmation…";
                }

                if (status === "paid") {
                    el.textContent = "✓ Payment confirmed. Thank you!";
                    el.className = "status confirmed";
                }

                if (status !== "paid") setTimeout(check, 5000);
            }
            check();
        </script>
    </body>
</html>
    `);
});

app.get("/pay/:orderId/status", (req, res) => {
    const order = getOrder(req.params.orderId);
    if (!order) return res.status(404).json({ error: "not found" });
    res.json({ status: order.status });
});

A bitcoin: URI (BIP-21) is the standard format every Bitcoin wallet understands. Scanning the QR code opens the customer's wallet with the address and amount pre-filled, so they just tap "Send."

🔄 A note on polling: we're using a 5-second poll here for simplicity. In production you'd want WebSockets so the customer sees confirmation the instant it happens — Blockonomics has a real-time WebSocket endpoint for exactly this. We'll cover that in Tuesday's post.

Step 5: Handle the callback webhook

This is where most homemade integrations break. The Blockonomics callback is an HTTP GET request with query parameters — not a POST with a JSON body. This is the single biggest thing LLMs get wrong about this API, so write it on your wall.

When a payment lands on one of your addresses, Blockonomics hits your callback URL like this:

GET /webhook/blockonomics?secret=YOUR_SECRET&txid=abc123def456...&addr=bc1q...&value=50000&status=0&rbf=1
Host: yourserver.com

Field	Type	Meaning
secret	string	The secret you put in your callback URL when you configured it in the dashboard. Use this to verify the request is genuine.
txid	string	The Bitcoin transaction ID.
addr	string	The receive address — your link back to the order.
value	integer	Payment amount in satoshis (1 BTC = 100,000,000 sats).
status	integer	0 = seen in mempool (unconfirmed), 1 = partially confirmed, 2 = fully confirmed (2 confirmations).
rbf	integer	Present only on unconfirmed transactions that signal Replace-By-Fee. 1 = opted in, 2 = inherited.

Your server must respond with HTTP 200 to acknowledge receipt. If you don't, Blockonomics retries up to 7 times with exponential backoff starting at 4 seconds.

Here's the handler:

// src/server.js (continued)
app.get("/webhook/blockonomics", (req, res) => {
    const { secret, txid, addr, value, status, rbf } = req.query;

    // 1) Verify the secret
    if (secret !== process.env.CALLBACK_SECRET) {
        console.warn("rejected callback with bad secret");
        return res.status(403).send("forbidden");
    }

    // 2) Find the order by address
    const order = db.prepare("SELECT * FROM orders WHERE address = ?").get(addr);
    if (!order) {
        console.warn("callback for unknown address:", addr);
        return res.status(200).send("ok"); // still 200 so they stop retrying
    }

    // 3) Map Blockonomics status -> our order status
    const statusInt = parseInt(status, 10);
    const valueSats = parseInt(value, 10);
    const valueBtc = valueSats / 1e8;
    const expectedBtc = order.amountBtc;

    // Sanity check: did they pay enough? Allow 5% under for price slippage.
    if (valueBtc < expectedBtc * 0.95) {
        console.warn(
            `underpayment on ${order.orderId}: got ${valueBtc}, expected ${expectedBtc}`,
        );
        updateOrderStatus(order.orderId, "underpaid", { txid });
        return res.status(200).send("ok");
    }

    // Reject zero-conf payments that signal RBF — they can be reversed.
    if (statusInt === 0 && rbf) {
        console.warn(`rejecting RBF payment for ${order.orderId}`);
        return res.status(200).send("ok");
    }

    if (statusInt === 0) updateOrderStatus(order.orderId, "partial", { txid });
    if (statusInt === 1) updateOrderStatus(order.orderId, "partial", { txid });
    if (statusInt === 2) updateOrderStatus(order.orderId, "paid", { txid });

    res.status(200).send("ok");
});

The status mapping deserves a careful read:

status=0 — the transaction has been broadcast to the network but hasn't been included in a block yet. Treat this as "we've seen the payment, but it could still be reversed." Show a "payment detected, waiting for confirmation" message to the customer. Don't release goods yet.
status=1 — partially confirmed. The transaction is in a block but Blockonomics' system hasn't yet flagged it as final. Still don't release goods if your goods are valuable.
status=2 — confirmed (2 confirmations). This is the point at which the payment is effectively irreversible. Release goods, fire your order-fulfillment logic, send a receipt email.

The RBF check matters. If a transaction has rbf=1 or rbf=2 and is still at status=0, the sender can replace it with a different transaction (potentially one that doesn't pay you). For digital goods that you deliver instantly, reject any zero-conf payment that includes an rbf flag. For physical goods that ship in days, you have time to wait for confirmations, so it doesn't matter.

Step 6: Persist the order ↔ address mapping

Here's the SQLite layer. Boring but essential:

// src/db.js
import Database from "better-sqlite3";

export const db = new Database("orders.db");

db.exec(`
CREATE TABLE IF NOT EXISTS orders (
    orderId     TEXT PRIMARY KEY,
    address     TEXT UNIQUE NOT NULL,
    amountFiat  REAL NOT NULL,
    currency    TEXT NOT NULL,
    amountBtc   REAL NOT NULL,
    pricePerBtc REAL NOT NULL,
    productName TEXT,
    status      TEXT NOT NULL DEFAULT 'pending',
    txid        TEXT,
    createdAt   INTEGER NOT NULL DEFAULT (strftime('%s','now')),
    updatedAt   INTEGER NOT NULL DEFAULT (strftime('%s','now'))
);

CREATE INDEX IF NOT EXISTS idx_orders_address ON orders(address);
CREATE INDEX IF NOT EXISTS idx_orders_status ON orders(status);
`);

export function createOrder(order) {
    db.prepare(`
        INSERT INTO orders (
            orderId,
            address,
            amountFiat,
            currency,
            amountBtc,
            pricePerBtc,
            productName,
            status
        )
        VALUES (
            @orderId,
            @address,
            @amountFiat,
            @currency,
            @amountBtc,
            @pricePerBtc,
            @productName,
            @status
        )
    `).run(order);
}

export function getOrder(orderId) {
    return db.prepare("SELECT * FROM orders WHERE orderId = ?").get(orderId);
}

export function updateOrderStatus(orderId, status, extra = {}) {
    const fields = ["status = ?", "updatedAt = strftime('%s','now')"];
    const values = [status];

    if (extra.txid) {
        fields.push("txid = ?");
        values.push(extra.txid);
    }

    values.push(orderId);

    db.prepare(`UPDATE orders SET ${fields.join(", ")} WHERE orderId = ?`).run(
        ...values,
    );
}

The two things that matter here:

address has a UNIQUE constraint. Each address is only ever used for one order. If somehow the same address came back twice (it shouldn't with reset=0), the insert fails loudly rather than silently overwriting.
Index on address. The webhook arrives carrying an address, not an orderId — your lookup must be fast even with a million orders in the table.

Step 7: Run it locally with ngrok

Blockonomics needs a public URL to send webhooks to. For local dev, use ngrok:

# terminal 1
npm run dev

# terminal 2
ngrok http 3000

Copy the https://something.ngrok.io URL ngrok prints, then in the Blockonomics dashboard set your callback URL to:

https://something.ngrok.io/webhook/blockonomics?secret=YOUR_SECRET

Now create an order:

curl -X POST http://localhost:3000/checkout \\
    -H 'Content-Type: application/json' \\
    -d '{"amountFiat": 0.50, "currency": "GBP", "productName": "Test"}'

(50p is a good test amount — small enough not to break the bank, large enough to be above the dust limit.) Open the returned paymentUrl in your browser, scan the QR with a wallet, send the payment, and watch your server log fill up with callback events.

Common errors and fixes

A few things you'll hit, and how to handle them:

409 Conflict – Required wallet not attached to store: You called new_address but haven't attached your xpub to a store yet. Go to Dashboard → Stores → attach your wallet.
422 Unsupported Cryptocurrency: You passed crypto=ETH or similar. The endpoint accepts only BTC or USDT. For other coins you need different endpoints.
400 Bad request with no obvious cause: Almost always a missing match_callback parameter. It's required.
The webhook never fires: Three usual suspects: (1) your callback URL in the dashboard doesn't actually contain the substring you passed to match_callback; (2) ngrok tunnel died and you forgot to restart it; (3) you configured the callback URL for the wrong store. The dashboard has a "Test callback" button — use it.
The webhook fires but you get a 403: You forgot the secret query param in the URL configured in the dashboard, or it doesn't match CALLBACK_SECRET in your .env.
My customer paid but the amount looks wrong: The value field in the callback is in satoshis, not BTC. Divide by 1e8.
The same callback fires multiple times: It shouldn't — Blockonomics dedupes on (txid, status, addr). But if your server returned non-200 on the first delivery, it'll retry. Always return 200, even for "I don't recognize this address" — that prevents wasted retries.