Name enquiry

Name enquiry confirms who holds an account before you pay it. For an account at the bank it is a local lookup; for an account anywhere else it is a NIBSS name enquiry sent under the bank’s institution code. Both come back in the same shape, and the fields on a NIBSS answer are meant to be echoed on the interbank transfer that follows.

POST/api/legacy/provider/wallets/transactions/name_enquiryscope: nip:name-enquiry

Request

Field	Type	Required	Description
accountNumber	string	Yes	The 10-digit NUBAN to resolve.
bankCode	string	Yes	311 for an account at the bank; otherwise the destination bank’s code from the institutions list.

cURL (other bank)

curl -X POST https://api.bankcore.ng/api/legacy/provider/wallets/transactions/name_enquiry \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "accountNumber": "0123456789", "bankCode": "058" }'

Request body (local)

{ "accountNumber": "6020012345", "bankCode": "311" }

Response

{
  "code": "0000",
  "desc": "ADEBAYO OGUNDIMU",
  "bvn": "22222222222",
  "kycTier": "2",
  "accountDesignation": "1",
  "idType": "1",
  "nameEnquirySessionId": "100003260401143000000001"
}

Field	Description
desc	The account name. Pass it as toAccountName on the transfer.
bvn	The holder’s BVN as the bank or NIBSS reports it. Do not store it.
kycTier, accountDesignation, idType	NIBSS beneficiary attributes. Echo them on the transfer as beneficiaryKycTier, beneficiaryAccountDesignation and beneficiaryIdType.
nameEnquirySessionId	NIBSS’s session id for this enquiry. Present only for an enquiry at another bank. Echo it as nameEnquirySessionId on the transfer.

Local versus NIBSS

	bankCode = 311	Any other code
Where it looks	The bank’s own accounts, in your tenant.	NIBSS, under the bank’s institution code.
Ownership	Not restricted to accounts you own; any account at the bank resolves.	n/a
nameEnquirySessionId	Absent.	Present.
Time	Milliseconds.	Up to about 20 seconds; NIBSS can be slow. Set your HTTP timeout accordingly.

The local code is fixed at 311

The code treats 311 as “this bank” regardless of tenant. If your bank’s CBN code is not 311, confirm with your relationship manager which value to send for a local lookup; the transfer endpoint itself accepts either the 3-digit CBN or the 6-digit NIBSS code, but name enquiry passes any non-311 code straight to NIBSS.

Reusing the enquiry on the transfer

Send the values back on POST /wallets/transactions/banktransfer:

{
  "fromAccountNumber": "6020012345",
  "toAccountNumber": "0123456789",
  "toAccountName": "ADEBAYO OGUNDIMU",
  "destinationBankCode": "058",
  "amount": 25000.00,
  "beneficiaryBvn": "22222222222",
  "beneficiaryKycTier": "2",
  "beneficiaryAccountDesignation": "1",
  "beneficiaryIdType": "1",
  "nameEnquirySessionId": "100003260401143000000001",
  "transactionRef": "PAY-20260401-001"
}

The transfer carries these to NIBSS as the creditor details. Values you supply always win over anything the platform cached from the enquiry; omit them and the platform fills what it can.

Errors

Code	When
0012	Local: no such account. NIBSS: the enquiry was declined, with NIBSS’s description in desc (invalid account, closed account, and so on).
0096	The NIBSS call failed or timed out. Retry after a pause; a name enquiry has no side effects.

Agent twin

POST/api/legacy/agent/transact/nameenquiryscope: nip:name-enquiry

Identical request and response. The X-Agent-Account header is not read by this call.

In the portal

Name enquiries are not recorded as transactions and do not appear in the portal. The name you confirm is shown on the Interbank transfers page as the beneficiary of the transfer you then send.