Check a payment

Returns the effective status of a bank-issued virtual account: ACTIVE, USED or EXPIRED. For a single-use number, USED means exactly one accepted payment has been credited to the settlement account. That is the whole of what this call tells you; the amount, the payer and the time come from the webhook or the portal.

Prefer the webhook. This endpoint exists so that a client with no inbound endpoint, or one recovering from downtime, can confirm the state of a number it issued.

GET/api/legacy/agent/virtual_account/check/{accountNumber}/{reference}scope: virtual-accounts:read

Request

No body and no X-Agent-Account header.

Path segment	Description
`accountNumber`	The 10-digit virtual account number returned when you created it.
`reference`	The `external_ref` you passed at creation. The current code does not use it to look anything up; the number alone selects the record. Send it anyway so the URL stays correct if matching is added. It must not be empty.

cURL

curl https://api.bankcore.ng/api/legacy/agent/virtual_account/check/4000001042/ORD-1042 \
  -H "Authorization: Bearer $TOKEN"

Response

{
  "code": "0000",
  "desc": "USED"
}

`desc`	Meaning
`ACTIVE`	Still accepting payment. Not yet paid if single-use. For a multi-use number this says nothing about whether payments have landed.
`USED`	Single-use number that has received its payment. The settlement account has been credited with the net amount.
`EXPIRED`	The TTL elapsed, or you expired it. No further payment will be accepted.

The status is computed against the clock: a number whose TTL has passed reports EXPIRED even if the five-minute sweep has not yet written it.

Errors

Code	`desc`	When
`0012`	`Virtual account not found: ...`	No record with that number. In the current build a number from `createFVA` answers this too; see the caution on Create a non-expiring virtual account.
`0012`	any other text	Unexpected failure while reading. Retry once, then raise with the bank.

How to poll

Poll only single-use numbers, and only while you have not received the webhook for them.
Poll no more often than once every 30 seconds per number; the bank credits in seconds once NIBSS confirms, and your rate limit covers every call you make.
Stop at USED or EXPIRED. Stop at ACTIVE once your own TTL has passed plus a few minutes, and treat the number as abandoned.
Multi-use numbers cannot be checked this way. Use the webhook, or the portal’s Inflows page.

In the portal

The Virtual accounts page shows the same effective status per number, and Inflows shows each payment with its amount, sender and session id.