NimBillDocs

Pay with NimBill

Pay with NimBill

Take payments in your store, get a webhook when they land.

Add NimBill as a payment option in your online store. Your server creates the invoice, the customer pays it from their wallet straight into yours, and NimBill sends your server a signed message the moment the payment is confirmed on-chain. NimBill never holds the money.

No API key

One webhook secret signs both ways: your requests to NimBill, and NimBill's webhooks to you.

Non-custodial

Payments go wallet to wallet. A leaked secret can only create invoices that pay you.

NIM and USDT

Prices in your currency (USD, NGN, EUR…), paid in NIM or USDT on Polygon at a locked rate.

How it works

  1. Your server creates the invoice.

    It calls POST /api/pay/{tag}/invoices on your own board, signed with your webhook secret, with the amount, your order id and where to send the customer afterwards. Save the invoice.id it returns with the order.

  2. The customer pays on NimBill.

    Redirect them to /i/{invoice.id}. They lock a price and pay from Nimiq Pay or any wallet. Afterwards a Back to your shop button takes them to your returnUrl.

  3. NimBill confirms the payment on-chain.

    Even if the customer closes the tab, NimBill keeps watching the blockchain for the payment.

  4. Your server gets an invoice.paid webhook.

    Signed, retried for about 3 days until you answer with a 2xx within 10 seconds. See Receive webhooks.

Set it up

  1. Get a tag.

    Sign in to NimBill with Nimiq Pay and claim a tag such as ada@nimbill. Your store creates invoices on that board. To accept USDT too, add a Polygon address in Settings.

  2. Turn on webhooks.

    In Settings, open Webhooks (tagged For developers, closed by default) and enter the https URL that receives webhooks and, optionally, your store's address (where customers may be sent back to). Copy the secret it shows. It is shown only once; you can make a new one any time.

  3. Store the secret on your server.

    For example as NIMBILL_WEBHOOK_SECRET. Never put it in a web page or an app: whoever has it can create invoices in your store's name.

  4. Send a test event.

    Send test event in Settings delivers a webhook.test with a made-up paid invoice, so you can check your handler without paying anything. Open the event under Recent events to see what your server answered and the exact body it was sent.

Three rules

  • Verify every signature before trusting a webhook, using the raw request body.
  • Expect duplicates. Delivery is at least once: skip events whose id you already handled.
  • Answer fast. Return 2xx right away and do slow work (emails, fulfilment) afterwards.

Next