The KwikBillng API

A write answers 202 with a request_id and finishes on your webhook. Creating an invoice renders a PDF, builds a payment QR code and mails a customer, and none of that belongs in the time you are holding a connection open.

A person reads every request, and what you tell us about what you are building is most of what they go on. There is no plan requirement — any KwikBillng account can ask, from the developer section of the dashboard.

Not from the account’s plan. The two never touch: an account on the free plan with a funded wallet has a fully working API, and the same account raising an invoice through the dashboard spends plan quota and never the wallet. See Pricing.

A sk_test_… key writes records that stay out of the merchant’s real ones — no dashboard list, no export, no plan quota, no payout — and delivers to a separate test webhook URL. Test invoices are numbered TEST-INV-00001 in their own sequence, so a rehearsal never leaves a gap in the real one.

Build against a test key, but fund the wallet first. A rehearsal is metered at the same rates as a live call, and one the balance cannot cover is refused 402 exactly as a live one is.

Records raised over the API carry no author. They appear on the merchant’s dashboard tagged API rather than attributed to a colleague, and on their audit log with no actor — which is how an owner tells what their software did from what their staff did.

HMAC-SHA256 over "{timestamp}.{raw body}", keyed with your signing secret. Use the raw bytes — re-serialising the JSON changes the key order and the signature will not match.

const [, t] = header.match(/t=(\d+)/);
const [, v1] = header.match(/v1=([a-f0-9]+)/);

const expected = crypto
  .createHmac("sha256", process.env.KWIKBILLNG_WEBHOOK_SECRET)
  .update(t + "." + rawBody)
  .digest("hex");

const ok = crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(expected));

Reject anything more than a few minutes old. The timestamp is inside the signed string, which is what stops a captured delivery being replayed at you later.

Any 2xx counts as accepted — including 202 if you queue the event and handle it later, which is what we would do. We wait 20 seconds and no longer.

Redirects are not followed. A 3xx is recorded and retried, because delivering a signed payload to a host you did not register is how a misconfigured endpoint becomes a leak.

We retry for about eight hours — ten attempts, backing off from 30 seconds to a four-hour cap. Every attempt is kept, with the status your server returned and an excerpt of its body, and the merchant can read all of it in the portal and press resend once you have deployed a fix.

Wallet top-ups start at ₦50,000. That is per payment, not a balance you have to keep — you can spend it all the way down, and calls are only refused when the balance cannot cover the next one.

The cost is held when a call is accepted, taken only when the work succeeds, and given back when it does not. A failed call costs nothing, and GET /x/wallet shows what is held while one is in flight.

A sk_test_… key is metered exactly as a live one is: the same tariff, the same reservation, the same 402 when the balance will not stretch. That is deliberate, and it is what makes the sandbox worth rehearsing in — what you learn there about what a flow costs stays true when you swap the key.

What it spends is a separate sandbox wallet, credited free and instantly from the merchant’s portal. Rehearsing does not cost the merchant money and cannot drain the balance their live integration depends on. Sandbox charges are marked (test) on their own statement.