1. Invoice
Virtual Account Services
  • Introduction
  • Terminologies
  • Webhooks
  • Authentication
  • Account
    • Create Account
      POST
    • Balance Inquiry
      GET
    • Rename Account
      POST
    • Create Bulk Accounts
      POST
    • List Accounts
      GET
  • Transaction
    • Credit Account
      POST
    • Debit Account
      POST
    • Credit Account [Agency Banking]
      POST
    • Debit Account [Agency Banking]
      POST
    • Transaction Query
      GET
    • Transaction Details
      GET
    • Transaction History
      GET
  • Transfer
    • Interbank Transfer
      • Interbank Transfer
      • Interbank Transfer [Sync]
      • Transfer Query
      • Transfer Enquiry
    • Intrabank Transfer
      • Intrabank Transfer [Same Groupcode]
      • Intrabank Transfer [Different Group Codes]
      • Intrabank Transfer [Savings Account]
      • Intrabank Transfer Query
    • Name Inquiry
      POST
    • Get Institutions
      GET
  • Invoice
    • Create Invoice
      POST
    • Get Invoice Detail
      GET
    • Get Invoice Status
      GET
    • List Merchant Invoices
      GET
  • Refunds
    • Get Refunds
      GET
    • Initiate Refund
      POST
    • Get Refund Status
      GET
  • Notifications
    • Notification
    • Send Notification
  • Group Code
    • Create Group Code
  • Overdraft
    • Draw Overdraft
  • Merchant
    • Account
      • Get Account
      • Activate Sub Ledger For Merchant
      • Get SubLedger Callback Urls
      • Set SubLedger Callback Urls
      • Get Collection Accounts
    • Transfer
      • Get Transfer Details
      • Name Inquiry
      • Get Transfer History
      • Get Subledger transfers
    • Refund
      • Refund Details
    • Create Merchant Account
    • Activate Sub Ledger For Merchant
    • Get KYC Information
    • Get Group Code Collection Account
    • Get Collection Accounts
    • Set Collection Account
    • Get Transfer Details
    • Name Inquiry
  • Admin
    • Accounting
      • Get Classification Codes
      • Get GL Accounts
    • Dashboard
      • Dashboard Summary
      • Dashboard Transaction Details
      • Dashboard Transactions
    • Group Codes
      • Create Group Code
      • Set Collection Account
      • Get Group Codes
    • Reporting
      • Get Report Parameters
      • Get Reports
      • Create Report
      • Get Reports Details
      • Get Reports
    • Get Reports
    • Get Report Parameters
  • Schemas
    • VACreateGroupCodeRequest
    • SubLedgerGroup
    • InvalidParameterError
    • TransactionPointError
    • UnauthorizedError
    • SpringDefaultError
  1. Invoice

Get Invoice Status

GET
/invoice/status/{invoiceReference}

Get Invoice Status#

Retrieves the current status of an invoice.
If the invoice has not yet been paid, the response contains the invoice details and payment status.
If the invoice has been paid, the response additionally includes the payment and settlement information used for reconciliation.

Path Parameters#

ParameterTypeRequiredDescription
invoiceReferenceStringYesUnique invoice reference generated during invoice creation

Example URL#

Success Response (Pending Invoice)#

HTTP Status#

Response Body#

{
  "subLedgerID": "1110028207",
  "description": "Power Vend",
  "customerEmail": "customer@example.com",
  "customerName": "Sample Customer",
  "invoiceReference": "79335133509367370786",
  "amount": 50100.00,
  "subledgergroupcode": "8RFVJ70FK4",
  "status": "Pending",
  "allocatedNuban": "3863478563",
  "expiryDate": "2026-06-30T21:59:20Z",
  "statusDate": "2026-06-30T19:59:36Z"
}

Success Response (Paid Invoice)#

HTTP Status#

Response Body#

{
  "subLedgerID": "1110034309",
  "description": "Wallet Funding By Merchant User ID: 70",
  "customerEmail": "customer@example.com",
  "customerName": "Sample Customer",
  "invoiceReference": "06181019987536383471",
  "amount": 100.00,
  "subledgergroupcode": "8RFVJ70FK4",
  "status": "Paid",
  "allocatedNuban": "5543689958",
  "sourceAccountNumber": "0175601702",
  "sourceAccountName": "Sample Customer",
  "sourceAccountBank": "Sample Bank",
  "destinationAccountNumber": "5543689958",
  "destinationAccountName": "Sample Customer",
  "destinationAccountBank": "Sample Bank",
  "sessionID": "416555083410621981186915581533",
  "transactionReference": "416555083410621981186915581533",
  "expiryDate": "2026-07-02T12:02:13Z",
  "statusDate": "2026-07-02T10:02:14Z",
  "createdDate": "2026-07-02T10:02:14Z"
}

Response Parameters#

FieldTypeDescription
subLedgerIDStringIdentifier of the invoice sub-ledger account
descriptionStringDescription of the invoice or payment purpose
customerEmailStringCustomer email address (may be masked or null)
customerNameStringName of the customer associated with the invoice
invoiceReferenceStringUnique invoice reference
amountDecimalInvoice amount
subledgergroupcodeStringInternal sub-ledger grouping code
statusStringCurrent invoice status
allocatedNubanStringVirtual account (NUBAN) allocated to the invoice
expiryDateString (ISO 8601)Date and time when the invoice expires
statusDateString (ISO 8601)Date and time when the current status was recorded

Additional Fields Returned for Paid Invoices#

FieldTypeDescription
sourceAccountNumberStringBank account from which payment originated
sourceAccountNameStringName of the payer's account
sourceAccountBankStringBank of the payer's account
destinationAccountNumberStringVirtual account credited
destinationAccountNameStringName on the destination account
destinationAccountBankStringBank hosting the destination account
sessionIDStringNIP session identifier for the payment transaction
transactionReferenceStringUnique transaction reference
createdDateString (ISO 8601)Timestamp when the payment transaction was created

Possible Status Values#

StatusDescription
PendingInvoice has been generated but payment has not yet been received.
PaidPayment has been received and transaction details are available.

Example Request#

Notes#

A Pending response indicates that payment has not yet been received or confirmed.
Once the invoice status changes to Paid, additional payment and settlement information is included in the response.
The transactionReference and sessionID can be used for transaction reconciliation and support investigations.
The invoice cannot receive payments after its expiryDate.

Request

Path Params

Request Code Samples

Shell
JavaScript
Java
Swift
Go
PHP
Python
HTTP
C
C#
Objective-C
Ruby
OCaml
Dart
R
Request Request Example
Shell
JavaScript
Java
Swift
curl --location '/invoice/status/'

Responses

🟢200Response
application/json
Bodyapplication/json

Example
{}
🟠400| Source | Error | When |
🟠401| Source | Error | When |
Modified at 2026-11-02 12:41:29
Previous
Get Invoice Detail
Next
List Merchant Invoices
Built with