Read an invoice by reference (partner perimeter).
Returns the current state of an invoice owned by the authenticated partner. Payment-surface fields (virtualAccount, virtualAccountName, virtualAccountBank, trackingId, checkoutToken) populated only when status >= 'published'.
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
Path Parameters
Partner-supplied invoice reference.
Response Body
application/json
curl -X GET "https://example.com/api/v1/bankrail/invoice/invoice-2026-001"{ "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": {}}Create an invoice (partner perimeter). POST
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.
Publish a draft invoice (partner perimeter). POST
Transitions invoice from 'draft' to 'published'. Allocates the underlying virtual account by composing payment-intent creation. Idempotency: if invoice is already published, returns 409 with the current state in the error details — partner can re-fetch via GET to recover the published response. If invoice is in any other non-draft state ('paid', 'cancelled', etc.), returns 409.