NimBillDocs

Board API

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