amount. Numero mints a one-time virtual account for it and returns the account details (and a hosted pay-page token). When the account is funded, the invoice is marked paid and a FUNDING_NOTIFICATION webhook fires.
Endpoint
POST /api/v1/business/invoices
Headers
| Header | Required | Description |
|---|---|---|
X-Numero-Api-Key | Yes | Your API key |
X-Numero-Signature | Yes | Base64 HMAC-SHA256 over the exact raw request body (POST) or the canonicalised query string (GET), keyed with your Public Key. See Request signing. |
X-Numero-Signature-Version | Yes | Always v2. |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
amount | number | Yes | Invoice amount in major units (naira) |
currency | string | No | Defaults to NGN |
description | string | No | What the invoice is for |
customerName | string | No | Bill-to name |
customerEmail | string | No | Bill-to email (the invoice email is sent here) |
dueDate | datetime | No | When payment is due |
expiresInMinutes | integer | No | Validity window for the payment account |
Request example
curl -X POST "https://api.usenumero.com/numeroaccount/api/v1/business/invoices" \
-H "Content-Type: application/json" \
-H "X-Numero-Api-Key: your_api_key" \
-H "X-Numero-Signature: $SIGNATURE" \
-H "X-Numero-Signature-Version: v2" \
-d '{
"amount": 25000,
"currency": "NGN",
"description": "Design retainer — January",
"customerName": "John Doe",
"customerEmail": "[email protected]",
"dueDate": "2024-01-31T23:59:59Z"
}'
Response
{
"data": {
"invoiceNumber": "INV-2024-000123",
"currency": "NGN",
"amount": 25000,
"status": "Pending",
"description": "Design retainer \u2014 January",
"customerName": "John Doe",
"customerEmail": "[email protected]",
"dueDate": "2024-01-31T23:59:59Z",
"publicToken": "pay_9fbc\u2026",
"paymentAccountNumber": "8012345678",
"paymentAccountName": "Your Business Ltd",
"paymentBankName": "Providus Bank",
"dateCreated": "2024-01-15T12:00:00Z"
},
"error": null,
"meta": {
"request_id": "req_365123ebc73323f1482508560ce6400e",
"pagination": null
}
}
| Field | Type | Description |
|---|---|---|
invoiceNumber | string | Use this on all /invoices/{invoiceNumber} calls |
status | string | Pending until funded |
publicToken | string | Token for the hosted pay page |
paymentAccountNumber | string | NUBAN the customer pays into |
paymentAccountName / paymentBankName | string | The payment account’s name + bank |