Expire a virtual account

Marks a bank-issued virtual account EXPIRED now, whatever its TTL. Use it when the order was cancelled, the invoice was paid another way, or you issued the number by mistake. From the next name enquiry the payer’s bank is told the account is declined, and a credit that arrives afterwards is refused before the money moves.

PATCH/api/legacy/agent/virtual_account/expire/{accountNumber}scope: virtual-accounts:create

Request

No body and no X-Agent-Account header.

Path segment	Description
accountNumber	The 10-digit bank-issued virtual account number.

cURL

curl -X PATCH https://api.bankcore.ng/api/legacy/agent/virtual_account/expire/4000001042 \
  -H "Authorization: Bearer $TOKEN"

Response

{
  "code": "0000",
  "desc": "Virtual account expired"
}

Calling it again on an already expired number succeeds with the same response.

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 and only the bank can switch it off; see the caution on Create a non-expiring virtual account.
0012	Virtual account does not belong to this tenant	The number exists at another bank on the platform.

Notes

• It cannot be undone. There is no reactivate call. Issue a new number with a new external_ref.
• A payment already in flight still posts. A credit the bank accepted from NIBSS while the number was live is credited even if you expire the number while NIBSS is confirming it. Reconcile on the webhook, not on the fact that you expired the number.
• Expiring a USED number sets it to EXPIRED. The payment it took is unaffected.
• The call does not check which band the number is on beyond the tenant. Keep your own record of the numbers you issued, and only expire those.

In the portal

The number shows as EXPIRED on the Virtual accounts page immediately.