How partner-maintained numbers work

On a partner-maintained band the bank assigns you a contiguous block of 10-digit numbers and keeps no record of the individual numbers inside it. You decide what each number means: which invoice, which pupil, which wallet. The bank finds out by asking you, at the moment a payer’s bank runs a name enquiry. The portal and the bank’s own screens call this a REMOTE band; a bank-issued band is LOCAL.

There is no create call, no expire call and no check call. Every number from the band’s start to its end is yours the moment the band is approved, and a number stops working when you tell the bank so at name enquiry. Two endpoints you host do all the work:

• Your validation endpoint answers “is this number real, and whose is it?”
• Your payment notification endpoint is told when a payment has been credited.

What the bank sets up for you

Each band is one record at the bank. You cannot change any of it through the API; ask your relationship manager.

Setting	What it is
Start and end	The block of numbers. Every number from start to end inclusive routes to you; there is no list of which ones you have handed out.
Validation URL	The HTTPS endpoint each name enquiry is POSTed to. Required: a band cannot be approved without one.
Notification URL	The HTTPS endpoint each credit is POSTed to. Optional. With none set, credits still post to your account and every notification is recorded as SKIPPED.
MAC key	One shared secret that signs both messages. It is write-only: the bank gives it to you out of band, no screen shows it, and the portal reports only whether one is set.
Settlement account	The account credits land in unless you nominate another. Required at setup.
Nominable accounts	An allow-list of your accounts that you may name at name enquiry as the destination for a particular number. Empty by default: a band with none can never be redirected.
Partner amounts	A switch, off by default, that lets you state at name enquiry what a number should be paid and have other amounts refused.
Use validation result	Whether the responseDesc you return is shown to the payer as the account name. Off, the payer sees the band owner’s registered name whatever you return.
BVN	The BVN returned to the payer’s bank at name enquiry for every number in the band. The KYC tier returned is always 3.
Fixed or minimum amount	Band-wide amount rules, checked before any per-number amount you state.
Fee	As on any band; see Concepts. The notification reports the gross amount.
Status	A new band is PENDING_APPROVAL until a Bank Admin or Compliance Officer approves it. Only an approved, active band routes payments.

What you give the bank: the two URLs, the accounts you intend to nominate, whether you want your responseDesc shown as the name, and whether you want partner amounts. What the bank gives you: the start and end, the MAC key, and confirmation of each switch. Keep a written record of which switches are on; your endpoint cannot tell from any response.

The activation and approval of a band is a staff workflow inside the bank. Its routes (/api/va-activations) refuse partner tokens.

The sequence

1. The payer enters one of your numbers in their banking app. Their bank sends a NIBSS name enquiry.
2. The bank finds your band by containment and POSTs custid, channel and an HMAC-SHA1 mac to your validation URL.
3. You answer responseCode 0000 for a number you recognise, optionally with responseDesc, beneficiaryAccount, amount and enforceAmount. Anything else declines. The bank records what you said about the number and relays the answer to the payer’s bank.
4. The credit arrives with a NIP session id, seconds or minutes later. The bank checks the band’s amount rules and any amount you enforced, and refuses before acknowledging if they fail. No money moves on a refusal.
5. The bank posts the credit to the band’s settlement account, or to the account you nominated for that number if the bank has it on the allow-list and it can take credits. The band fee, if any, is withheld. A NIP_INWARD transaction is booked.
6. A job that runs every 30 seconds POSTs the notification, signed with an HMAC-SHA256 mac, to your notification URL.
7. You answer 2xx once you have stored it. Anything else is retried every 30 seconds, up to 48 attempts, then marked FAILED.
8. You can resend a notification from the portal’s Inflows page, or ask the bank to.
9. NIBSS settles with the bank the next business day. Your account was credited at step 5.

A transfer from another account at the same bank to one of your numbers skips steps 1 to 4 and is notified the same way. A payment replayed from a NIBSS settlement file also arrives with no enquiry in front of it. Both reasons are why your instructions at step 3 outlive the enquiry they came with; see How long each field lasts.

Bank-issued versus partner-maintained

	Bank-issued (LOCAL)	Partner-maintained (REMOTE)
Who allocates a number	The bank, when you call create	You, from anywhere in the band
Record per number at the bank	Yes: name, status, expiry, amount rule, settlement account	None. The bank holds only what you last said at name enquiry
Name enquiry answered from	The record	Your validation endpoint
Where the money lands	The settlement account chosen at creation	The band’s settlement account, or an allow-listed account you nominate
How you are told	transaction.completed webhook	POST to your notification endpoint
Per-number rules	Expiry, single-use, exact amount, set at creation	An expected amount you state at each enquiry, if the bank enabled partner amounts
Stop a number	Expire it	Decline it at the next enquiry

Security

Two signatures, one key. The enquiry is signed HMAC-SHA1(key, custid + "mobile"); the notification is signed HMAC-SHA256(key, reference + amount + accountNumber). Both are lowercase hex, both use the same MAC key as UTF-8 bytes, and both are an empty string if the band has no key. Verify in constant time. The wire detail is on each endpoint page.

Key rotation is done by the bank, takes effect on the next message in both directions, and has no overlap period: there is one key per band, so reject nothing until you have switched. A resend replays the original body with its original mac, so a notification first sent under the old key will fail your check after rotation; agree rotations with the bank and resend before, not after.

Source addresses. The bank’s requests come from the bank’s own egress addresses, which the platform does not publish; ask your relationship manager for the current list if you filter by IP. Treat IP filtering as a second layer: the mac is the check that matters, and the enquiry carries no timestamp, so a captured request stays valid until the key changes.

Timeouts. The bank waits 10 seconds to connect and 15 seconds to read, on both endpoints. Answer the enquiry from a cache or a fast lookup; answer the notification after storing it and before processing it.

Idempotency on your side. The notification’s reference is the NIP session id (the bank’s own TXR... reference for an internal transfer). It is identical on every retry and every resend. Dedupe on it and answer 2xx to a duplicate.

When your validation endpoint is down, the payer’s bank is answered 97 (system error) and the payer sees a failure before any money moves; it may retry. A responseCode other than 0000 is answered 07 (account not found). A band with no validation URL answers 07 to everything.

Caution

The 97 versus 07 split is verified on the bank’s bridge connection to NIBSS. On its ISO 20022 connection the code your endpoint returns is relayed as received; the payer-side wording for an outage there could not be confirmed from the code.

When your notification endpoint is down, nothing about the money changes. The credit is already in your account; the notification is retried every 30 seconds for 48 attempts (about 24 minutes), then marked FAILED on the Inflows page with your endpoint’s HTTP status and error text. Resend from the portal, limited to 20 resends per band per hour, or let the bank resend.

Reversals produce no notification. A sending bank’s recall debits the account that received the credit and marks the inflow REVERSED; nothing is POSTed to you. Reconcile from the portal, or hold a webhook subscription for transaction.reversed beside your notification endpoint. See Reconciling a day.

In the portal

Virtual accounts lists the band with its start and end, mode REMOTE, whether it is active, the owner, the notification URL and the settlement account; never the key or the validation URL. Inflows lists each credit with the notification outcome and the Resend action. The per-number destination and amount the bank currently holds for you are on the bank’s operations screen; ask your relationship manager to read them back when a payment did not land where you expected.