NimBillDocs

Get started

Quick start

Buy a product with curl.

Try it against any board. Replace ada with a real tag (the part before @nimbill), and the ids with the ones you get back.

Buy a product with curl

  1. Read the board.

    Note a product id, or check merchant.openAmounts if you want to pay any amount.

    curl https://nimbill.mblob.me/api/pay/ada
  2. Create the invoice.

    You get back invoice.id and the total.

    curl -X POST https://nimbill.mblob.me/api/pay/ada/invoices \
      -H 'content-type: application/json' \
      -d '{"productId":"PRODUCT_ID","quantity":1,"payerName":"Shop bot for Tunde"}'
  3. Lock the price.

    The quote says exactly how much to send, where, with which memo, and until when.

    curl -X POST https://nimbill.mblob.me/api/invoices/INVOICE_ID/quote \
      -H 'content-type: application/json' \
      -d '{"asset":"NIM"}'
  4. Pay.

    Send quote.amount Luna to quote.recipient with quote.memo as data (see Sending the payment). Or open the invoice link and pay in Nimiq Pay:

    link
    https://nimbill.mblob.me/i/INVOICE_ID
  5. Confirm.

    Repeat every few seconds while the answer is "pending".

    curl -X POST https://nimbill.mblob.me/api/invoices/INVOICE_ID/verify \
      -H 'content-type: application/json' \
      -d '{"asset":"NIM","txHash":"TX_HASH"}'

The same in JavaScript

For your own agent or backend:

pay-board.mjs
const base = "https://nimbill.mblob.me";
const post = (path, body) =>
  fetch(base + path, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(body) })
    .then(async (r) => { const j = await r.json(); if (!r.ok) throw new Error(j.error.message); return j; });

const board = await fetch(`${base}/api/pay/ada`).then((r) => r.json());
const { invoice } = await post("/api/pay/ada/invoices", {
  productId: board.products[0].id, quantity: 1, payerName: "My agent for Tunde",
});
const { quote } = await post(`/api/invoices/${invoice.id}/quote`, { asset: "NIM" });

// Send BigInt(quote.amount) Luna to quote.recipient with quote.memo as data, before quote.expiresAt,
// using your wallet library. Then:
const txHash = await sendNim(quote); // your code

let result;
do {
  await new Promise((r) => setTimeout(r, 3000));
  result = await post(`/api/invoices/${invoice.id}/verify`, { asset: "NIM", txHash });
} while (result.status === "pending");
console.log(result.status, result.invoice?.number); // "paid", "INV-0042"