Create an invoice (partner perimeter).

Creates an invoice attributed to the authenticated partner. Defaults to status='draft'. Set publishOnCreate=true to atomically transition to published and allocate the underlying virtual account in one request. The partner identity (req.user.partnerId from PartnerHmacGuard) is recorded on bankrail.invoices.consumer_partner_id; invoice and credit callbacks are signed by the same partner attribution machinery as standalone payment-intents.

Authorization

X-Bankrail-Key-Id<token>

Partner-visible credential identifier issued by bank-rail at credential provisioning time. Names which credential signed the request; the corresponding signing secret never appears in any request.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

reference*string

Partner-supplied unique reference. Enforced unique per (consumer_partner_id, reference) — two partners can each use 'inv-001' without collision. 8-128 chars, alphanumerics + _ . - only.

title*string

Invoice title shown to the customer. 1-255 chars.

description?string

Optional free-text description or line description.

amountKobo*integer

Invoice amount in kobo (minor unit). Positive integer. v1 has no variable-amount invoices.

currency*string

ISO 4217 currency code. Today only 'NGN' is accepted.

customer*

Customer fields. Free-text per design §1.2 — bankrail does not maintain a customers table; partners with CRM needs use their own. Required.

dueAt?string

Optional ISO 8601 due-date. Threaded through to the composed payment-intent's expiresAt at publish time. Lazy-expiry transition is cron-driven (Phase 9F).

Formatdate-time

callbackUrl*string

Full HTTPS URL where bankrail delivers invoice-specific callbacks (invoice.paid, invoice.partially_paid, etc.). Required.

creatorMetadata?

Opaque key-value context. Stored verbatim and echoed back in every invoice callback. Useful for cross-call correlation.

persistentVirtualAccountId?string

Optional UUID of an existing persistent virtual account to attach this invoice to. When set, the invoice INHERITS the persistent VA's BRR (rather than minting a fresh one) and does NOT compose a fresh one-use payment-intent at publish time. Constraint: amount uniqueness across published invoices attached to the same VA — a partner cannot attach two published invoices of the same amount_kobo to the same persistent VA. Violations surface as 409 DUPLICATE_INVOICE_AMOUNT_ON_PERSISTENT_VA. The service layer additionally verifies the VA exists, belongs to the calling partner, and is type=persistent.

Formatuuid

publishOnCreate?boolean

When true, invoice transitions atomically draft → published at create time, allocating the underlying VA. When false (default), invoice lands at draft and the partner can later POST /invoice/:reference/publish to allocate the VA.

merchantDisplayName?string

Human-readable merchant name rendered on the checkout page header when publishOnCreate is true and the partner drives a hosted-checkout flow. Used only by the api-gateway public BFF.

returnUrl?string

Optional URL for the "Back to merchant site" link on the checkout page (relevant only when publishOnCreate is true).

brrBearing?boolean

Per-call BRR-bearing upgrade flag (Reading 2). For fintech partners, set to true to upgrade this invoice from reference-only to BRR-bearing; omit or set false for reference-only (default). Government and corporate partners are unconditionally BRR-bearing; the flag is accepted but ignored. Citizens cannot request BRR-bearing.

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/bankrail/invoice" \  -H "Content-Type: application/json" \  -d '{    "reference": "invoice-2026-001",    "title": "Consulting services — Q2 2026",    "amountKobo": 5000000,    "currency": "NGN",    "customer": {},    "callbackUrl": "https://partner.example.com/webhooks/bankrail/invoice"  }'

{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "reference": "string",  "partnerId": "bf408d53-df49-40a6-8455-a34bd4360901",  "status": "published",  "title": "string",  "description": "string",  "amountKobo": 0,  "amountPaidKobo": 0,  "currency": "string",  "customer": {},  "dueAt": "2019-08-24T14:15:22Z",  "publishedAt": "2019-08-24T14:15:22Z",  "paidAt": "2019-08-24T14:15:22Z",  "cancelledAt": "2019-08-24T14:15:22Z",  "persistentVirtualAccountId": "dc3e3963-3c41-4bb3-a139-f4a98adf9807",  "virtualAccount": "string",  "virtualAccountName": "string",  "virtualAccountBank": "string",  "trackingId": "string",  "checkoutToken": "string",  "createdAt": "2019-08-24T14:15:22Z",  "creatorMetadata": {}}

Empty

Create an invoice (partner perimeter).

Authorization

Request Body

Response Body

201application/json

400

401

409

503

`application/json`