Field dictionaries

Values are case-sensitive and sent exactly as written here. Lists marked open may gain values; parse defensively.

Legacy response codes

Every /api/legacy/... route answers HTTP 200 with { "code", "desc", ... }. desc is a human-readable description or, on success, the thing you asked for (an account number, a reference, a name).

code	Meaning	What to do
0000	Success	Read desc and any extra fields.
0004	Insufficient funds	The source account’s available balance is below amount plus fees.
0009	Pending / in flight	Money may have moved. Do not blindly retry; check the transaction by reference.
0012	Invalid or not found	Validation failure, unknown account, velocity limit, or an ownership refusal (PARTNER_ACCOUNT_FORBIDDEN, PARTNER_SUBAGENT_FORBIDDEN map here).
0014	Duplicate record	BVN, NIN or phone already exists in that customer category.
0062	Account not active	Frozen, PND-restricted, dormant beyond the credit gate, suspended or closed.
0094	Duplicate reference	Your transactionRef was already used for this kind of transaction.
0096	System error	Retry with the same reference; the duplicate guard protects you.

A money-movement success carries extra fields: retRef (BankCore reference), clientRef (your reference echoed), fromAccount, toAccount, availableBalance, ledgerBalance (strings, two decimals), transdatetime (yyyyMMddHHmmss), and for bills token, units, receipt, providerRef, subscriberAddress. Name enquiry adds kycTier, accountDesignation, idType, nameEnquirySessionId.

Transaction types

The txType on statements and on transaction.completed / transaction.reversed.

txType	Meaning
TRANSFER_OUT, TRANSFER_IN	The two legs of a transfer between BankCore accounts, including funding and charging an account against your settlement account, and campaign awards.
NIP_OUTWARD	Principal debit of an interbank transfer. Its fee legs are FEE, TAX (VAT) and STAMP_DUTY.
NIP_INWARD	Credit received from another bank, including through a virtual account.
VA_CREDIT_OUT, VA_CREDIT_IN	A payment into a virtual account made from a BankCore account rather than over NIP.
BILL_PAYMENT, AIRTIME_PURCHASE	Debit for a bill or airtime. BILL_SETTLEMENT is the biller-side credit.
CASH_IN, CASH_OUT	Agent counter cash-in and cash-out.
DEPOSIT, WITHDRAWAL	Branch cash.
FEE, TAX, STAMP_DUTY	Separate statement lines for bank fee, VAT and stamp duty.
REVERSAL	The reversing leg of a reversed transaction.
CARD_PURCHASE, CARD_WITHDRAWAL, CARD_TRANSFER, CARD_BILL_PAYMENT	Card activity.
WEB_ACQUIRING_CREDIT, WEB_ACQUIRING_CHARGEBACK	Card or web acquiring credits and their chargebacks.
INTEREST_CREDIT, INTEREST_DEBIT, ADJUSTMENT, EXTERNAL_TRANSFER_OUTWARD, EXTERNAL_TRANSFER_REVERSAL, MIGRATION_OPENING_BALANCE, MIGRATION_UNRECONCILED_BALANCE	Rare on partner accounts; shown for completeness.

Transaction metadata keys

Every money movement writes a metadata map onto the transaction. It appears as metadata on statement lines and is merged into the top level of webhook payloads.

Kind	Keys
NIP outward	beneficiaryName, beneficiaryAccount, beneficiaryBank (6-digit NIBSS), beneficiaryBankCbnCode, beneficiaryBankName, nipSessionId, senderName, senderAccount, feeAmount, vatAmount, stampDutyAmount, clientReference
NIP inward	senderName, senderAccount, senderBank, senderBankName, nipSessionId, narration
NIP inward through a virtual account	the inward keys plus virtualAccountNumber, virtualAccountName, externalRef, beneficiaryAccount, beneficiaryName, grossAmount, feeAmount, netAmount; a remote-validated band sends beneficiarySource instead of virtualAccountName and externalRef
Internal transfer	beneficiaryName, beneficiaryAccount, senderName, senderAccount, channel; plus initiatedByPartner (your client id) and initiatedByPartnerCustomerId when you debited a sub-agent
Virtual account credit from a BankCore account	virtualAccountNumber, virtualAccountName, virtualAccountExternalRef, virtualAccountPaymentRef, vaMode, beneficiaryAccount, beneficiaryName, senderName, senderAccount, grossAmount, netAmount, feeAmount, channel, clientReference
Bill payment / airtime	billPaymentRef, billerName, billerCode, billType, productName, subscriberId, subscriberName, subscriberAddress, amount, feeAmount, totalDebit (decimal strings), clientReference
Agent cash-in / cash-out	agentAccountNumber, agentName, customerAccountNumber, customerName, operationType (CASH_IN / CASH_OUT)
POS	terminalId, merchantName, cardMasked, rrn, authCode, posTransactionType (CASHOUT / BILL_PAY)
Card	cardMasked, merchantName, merchantId, terminalId, authCode, rrn, responseCode
Reversal of an inward credit	reversalOf, reversalReason, originalSessionId, originalAmount, feeAmount, netReversed

clientReference is always the reference you supplied on the originating request (transactionRef, external_ref), when there was one. The set is open.

NIP transfer status

Internally a transfer moves through eight states. The portal and the partner-facing status collapse them to five, which answer the only question that matters: where is the money.

You see	Internal states	Meaning
PROCESSING	INITIATED, DEBITED, SENT	Authorised, debited, handed to NIBSS. Outcome not yet known.
COMPLETED	CONFIRMED, SETTLED	The beneficiary was paid. SETTLED adds that NIBSS has since settled the bank’s position, which does not change anything for you. For an inward credit: in the account.
FAILED	FAILED	Did not happen, nothing was taken.
REVERSED	REVERSED	Did not happen, the debit has been returned.
UNDER_INVESTIGATION	ESCALATED	Automatic requeries ran out and the bank’s operations team owns it. The money is held, not lost. Nothing for you to do.

Filtering a transfer list by one of the five asks for all of its internal states.

Virtual account status

Status	Meaning
ACTIVE	Accepts payments, subject to expiry_date and the amount rules set at creation.
USED	A single-use account received its payment. No further credits are accepted.
EXPIRED	The TTL elapsed or you expired it. No further credits are accepted.

A virtual account with an expiry_date in the past is treated as expired even while its stored status is still ACTIVE. Fixed virtual accounts (createFVA) are always multi-use and never expire; they are a separate record with an active flag rather than this status.

Virtual account inflow (portal)

Each row on Payments received carries the credit’s details and whether your systems were told about it.

Field	Values
status	The underlying transfer’s status; an inward credit is normally CONFIRMED or SETTLED.
notificationChannel	VA_CALLBACK (a callback to the notifyUrl on your remote-validated range), CHANNEL_WEBHOOK (a webhook subscription), NONE (nothing was owed).
notificationStatus	NOT_APPLICABLE (nothing owed), PENDING (owed, not yet attempted), DELIVERED, FAILED (attempted, never completed, nothing will retry it), SKIPPED (retired without sending).
notificationTarget, notificationHttpStatus, notificationError	Present only when the notification went to a URL on your own range; withheld for a shared webhook subscription.
notificationLegacy	true when the outcome comes from an older job’s counters and there is no HTTP status to show.

Settlement with NIBSS is not shown on this surface.

Webhook delivery status

PENDING, RETRYING, DELIVERED, FAILED, CANCELLED, and the reserved DELIVERING. Defined in Delivery and retries.

Agent categories and business types

Field	Values
agentCategory	AGENT (agency-banking agent), MERCHANT (accepts payments for goods and services)
businessType	INDIVIDUAL, REGISTERED_BUSINESS (requires businessName; cacRegistrationNumber and tinNumber optional)

Customer types and channels

Field	Values
customerType	INDIVIDUAL, CORPORATE, AGENT. Sub-agents and merchants are AGENT.
sourceChannel	API (your client), MOBILE, USSD, POS, ATM, INTERNET_BANKING, BRANCH (bank staff), SYSTEM (inbound NIP, scheduled jobs).

KYC tiers

kycLevel	Notes
LEVEL_1	Default for a new agent or merchant.
LEVEL_2	An agent that holds both a BVN and a NIN is upgraded automatically.
LEVEL_3	Full KYC. Upgrades are reviewed by the bank.

The onboarding routes also accept the legacy spellings TIER_1 to TIER_3 and plain 1 to 3; anything else is treated as LEVEL_1.

Document types

Accepted values of documentType on an upload.

Group	Values
Identity	NIN, BVN, VOTERS_CARD, INTL_PASSPORT, DRIVERS_LICENSE, PASSPORT_PHOTO, SIGNATURE
Address	UTILITY_BILL, BANK_STATEMENT, ADDRESS_VERIFICATION_DOC, ADDRESS_VERIFICATION_PHOTO
Liveness	LIVENESS_SELFIE, LIVENESS_VIDEO
Corporate	CAC_CERTIFICATE, CAC_FORM_CO2, CAC_FORM_CO7, MEMART, SCUML, AUTHORIZATION_LETTER, MANDATE_LETTER, OPERATIONAL_LICENSE, BUSINESS_NATURE_DOC, BYLAWS
Directors and principals	DIRECTOR_ID, DIRECTOR_UTILITY_BILL, DIRECTOR_PASSPORT, PRINCIPAL_ID, PRINCIPAL_UTILITY_BILL, PRINCIPAL_PASSPORT
Other	SCREENING_SCORE_DOC, OTHER

Document status moves PENDING to VERIFIED or REJECTED; a channel upload flagged preVerified starts at VERIFIED.

Per-type size caps

The old channel guide listed a size cap per document type (2 MB for a signature up to 50 MB for a liveness video). We could not confirm those figures in the current code; treat them as indicative and expect HTTP 413 or a validation error above the real limit.

In the portal

Statuses on the Transfers, Payments received and Webhook endpoints pages use the values on this page; the portal shows the five-state NIP status, never the internal eight.