Create an invoice on a board
Turns “I want to buy this” or “I want to pay 25 USD for that” into an invoice the merchant will recognise. Send a productId to buy a product, or amount + currency + description to pay any amount (only when merchant.openAmounts is true).
POSThttps://nimbill.mblob.me/api/pay/{tag}/invoices
Path parameters
Path
- tag stringrequired
- The board's tag.
Body
Body (JSON)
- payerName stringrequired
- Who is paying. The merchant sees it on the order. Agents: say who you act for, e.g. “Shop bot for Tunde”.
- productId string
- A product id from the board. Use this or amount.
- quantity integer
- How many of the product, 1 to 100. Default 1.
- amount number
- Amount to pay when not buying a product.
- currency string
- Currency of amount, e.g. USD, NGN, EUR.
- description string
- What the amount is for, up to 120 characters.
- 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.
Request
Example request
curl -X POST https://nimbill.mblob.me/api/pay/ada/invoices \
-H 'content-type: application/json' \
-d '{"productId":"g3exvt33mh","quantity":2,"payerName":"Shop bot for Tunde"}'Response
Example response · 200
{
"invoice": {
"id": "89mwch33sp",
"number": "NMN-89MWC-H33SP",
"merchantName": "Ada Studio",
"clientName": "Shop bot for Tunde",
"items": [
{
"description": "Logo pack",
"quantity": 2,
"unitPrice": 120000
}
],
"currency": "NGN",
"total": "240000.00",
"status": "unpaid",
"memo": "NimBill 89mwch33sp"
}
}When it goes wrong
- 400 VALIDATION: a field is missing or wrong (the message says which)
- 400 BAD_REQUEST: the board doesn't take open amounts, or reference/metadata/returnUrl were sent without a signature
- 401 UNAUTHORIZED: a NimBill-Signature header was sent but doesn't match, is older than 5 minutes, or webhooks are off
- 404 NOT_FOUND: no such tag, or the product isn't available
- 429 RATE_LIMITED: more than 30 invoices on this board in 10 minutes (300 for the merchant's own signed requests), or more than 10 a minute from one address. Wait RateLimit-Reset seconds