NimBillDocs

Pay with NimBill

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

  1. Serialize the JSON body to a string once, and send exactly that string.
  2. Take the current Unix time in seconds, t.
  3. Compute HMAC-SHA256 of "<t>.<body>", keyed with your whole webhook secret (including whsec_), as lowercase hex.
  4. Send it in the header below, with a fresh timestamp for every request.
header
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:

redirect to
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:

response headers
RateLimit-Limit: 300
RateLimit-Remaining: 287
RateLimit-Reset: 412        seconds until the window frees up
Retry-After: 412            only on 429 Too Many Requests