Create a signed invoice
From your store's server, when the customer checks out.
It's the same call any visitor or agent uses to pay your board, POST /api/pay/{tag}/invoices, plus one header. The signature proves the request came from your store, so NimBill accepts your order details and sends you webhooks for the invoice.
Sign the request
- Serialize the JSON body to a string once, and send exactly that string.
- Take the current Unix time in seconds, t.
- Compute HMAC-SHA256 of "<t>.<body>", keyed with your whole webhook secret (including whsec_), as lowercase hex.
- Send it in the header below, with a fresh timestamp for every request.
NimBill-Signature: t=1763116731,v1=9c1e4f…(64 hex characters)
Body
Every field of the normal request: a productId from your board, or an amount, currency and description (your board must accept any amount for that). Signed requests may also send:
Signed requests only
- reference string
- Pay with NimBill only (signed requests): your own order id, up to 100 characters. Sent back in webhooks; never shown publicly.
- metadata object
- Pay with NimBill only: up to 20 string keys and values of your own, sent back in webhooks.
- returnUrl string
- Pay with NimBill only: where the payer goes back to after paying. Must be on the store address saved in NimBill.
reference and metadata are private to you and NimBill: they never appear on the public invoice page. returnUrl must be on the store address saved in Settings → Webhooks, so nobody can use your invoices to send customers to another site.
Code
Runs on your server when the customer picks "Pay with NimBill" at checkout:
import { createHmac } from "node:crypto";
const NIMBILL = "https://nimbill.mblob.me";
const TAG = "ada"; // your tag, without @nimbill
const SECRET = process.env.NIMBILL_WEBHOOK_SECRET; // "whsec_…", from Settings → Webhooks
export async function startNimbillPayment(order) {
const body = JSON.stringify({
payerName: order.customerName,
amount: order.total, // 25
currency: order.currency, // "USD"
description: `Order ${order.id}`,
reference: order.id,
metadata: { cart: order.cartId },
returnUrl: `https://shop.example.com/orders/${order.id}`,
});
const t = Math.floor(Date.now() / 1000);
const v1 = createHmac("sha256", SECRET).update(`${t}.${body}`).digest("hex");
const res = await fetch(`${NIMBILL}/api/pay/${TAG}/invoices`, {
method: "POST",
headers: { "content-type": "application/json", "nimbill-signature": `t=${t},v1=${v1}` },
body, // exactly the string you signed
});
const json = await res.json();
if (!res.ok) throw new Error(json.error.message);
await db.orders.update(order.id, { nimbillInvoiceId: json.invoice.id }); // webhooks are matched by this
return `${NIMBILL}/i/${json.invoice.id}`; // redirect the customer here
}Send the customer to pay
Redirect them to the invoice page (or show it in a new tab). It shows your name, the items and the total in your currency, locks a price in NIM or USDT, and opens their wallet:
https://nimbill.mblob.me/i/{invoice.id}When the payment is confirmed the page says so and shows a Back to <your store> button that opens your returnUrl. Don't treat the customer arriving there as proof of payment: wait for the webhook, or check the invoice yourself with GET /api/invoices/{id}.
When it goes wrong
Errors specific to signed requests
- 401 UNAUTHORIZEDsignature doesn't match
- The body you sent isn't byte-for-byte the string you signed, or the secret is wrong (an old one after the 24-hour overlap, say).
- 401 UNAUTHORIZEDtimestamp off
- t is more than 5 minutes from NimBill's clock. Sign each request right before sending it.
- 401 UNAUTHORIZEDwebhooks off
- Webhooks are turned off or removed in Settings, so signed requests are refused.
- 400 BAD_REQUESTunsigned extras
- reference, metadata or returnUrl were sent without a NimBill-Signature header.
- 400 VALIDATIONreturnUrl
- returnUrl isn't on the store address saved in Settings, or no store address is saved.
A wrong signature is always an error, never quietly treated as an anonymous request, so a misconfigured store finds out on its first try instead of silently missing webhooks.
Rate limits
Your store has its own allowance of 300 invoices per 10 minutes, apart from everyone else's, so traffic on your public board can't block your checkout. (Unsigned requests share 30 per board per 10 minutes, and 10 per minute per IP address.) Every answer says where you stand:
RateLimit-Limit: 300 RateLimit-Remaining: 287 RateLimit-Reset: 412 seconds until the window frees up Retry-After: 412 only on 429 Too Many Requests