Skip to content
BankCore Partner API

Onboard an agent or merchant

An agent or merchant is a customer of the bank of type AGENT, with an agent profile and two accounts: a transaction account for cash-out, transfers and bills, and a fee account that collects its commission. Creating one through your client stamps the profile with your client id, which is what makes it your sub-agent (see Ownership model).

Verify the person’s BVN or NIN with your own provider first. The date of birth you send is expected to come from that verification, and it is mandatory because it is a matching key for the bank’s sanctions and PEP screening.

POST/api/legacy/agent/admin/add_agentscope: sub-agents:create

The same route is open to the bank’s channel servers under agents:create, which partners can never hold. With sub-agents:create the agent is always parented to you; you cannot create an unowned agent.

Request

Section titled “Request”

JSON body. The body is not bean-validated, so a missing required field is reported by the service with a descriptive desc (and, today, code 0096; see Errors).

Field Type Required Description
firstName string Yes
lastName string Yes
otherNames string No Stored as middle name.
phoneNumber string Yes Nigerian mobile. Must not already belong to another agent.
email string No
bvn string One of bvn or nin Exactly 11 digits.
nin string One of bvn or nin Exactly 11 digits.
dateOfBirth string Yes yyyy-MM-dd.
gender string No M, F, MALE, FEMALE. An unrecognised value is dropped rather than refused.
address string No Street address.
state string No State of residence.
localgovt string No LGA of residence.
agentCategory string Yes AGENT or MERCHANT.
businessType string Yes INDIVIDUAL or REGISTERED_BUSINESS.
businessName string If REGISTERED_BUSINESS The trading name. Becomes the account name and the agent’s display name.
cacRegistrationNumber string No CAC or BN number.
tinNumber string No Tax identification number.
kycLevel string No TIER_1, TIER_2, TIER_3 (or LEVEL_n). Default TIER_1. An unknown value falls back to TIER_1.
Terminal window
curl -X POST https://api.bankcore.ng/api/legacy/agent/admin/add_agent \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Adebayo",
    "lastName": "Ogundimu",
    "phoneNumber": "08012345678",
    "email": "adebayo@example.com",
    "bvn": "22222222222",
    "dateOfBirth": "1990-05-15",
    "gender": "M",
    "address": "14 Allen Avenue",
    "state": "Lagos",
    "localgovt": "Ikeja",
    "agentCategory": "MERCHANT",
    "businessType": "REGISTERED_BUSINESS",
    "businessName": "Adebayo Stores",
    "cacRegistrationNumber": "BN1234567",
    "kycLevel": "TIER_2"
  }'

Response

Section titled “Response”

HTTP 201, not 200, on success. The body is the created agent, not the { code, desc } envelope.

{
  "customerId": "e41cc8ae-f521-4859-91da-d489f091a9b9",
  "customerNumber": "C000123456",
  "agentProfileId": "7c1d2e3f-0000-0000-0000-000000000002",
  "agentCode": "0000123456",
  "txnAccountNumber": "0000123456",
  "feeAccountNumber": "0001123456",
  "agentCategory": "MERCHANT",
  "businessType": "REGISTERED_BUSINESS",
  "displayName": "Adebayo Stores"
}
Field Description
customerId The agent’s customer id.
customerNumber The bank’s customer number.
agentProfileId The agent profile id.
agentCode Equal to the transaction account number.
txnAccountNumber The transaction account. This is the value you send as X-Agent-Account on every agent call.
feeAccountNumber The fee account. Derived from the transaction number by the bank’s agent range; read it, do not compute it.
displayName Business name for a registered business, otherwise first and last name.

Errors

Section titled “Errors”

Failures use the legacy envelope at HTTP 200.

Code desc When
0012 This API client is not permitted to onboard agents Your client lacks sub-agents:create at the service level, or is not linked to a customer.
0012 BVN is on the NIBSS watchlist ... / ... deceased list The BVN is listed. Nothing is created.
0012 Invalid field value: dateOfBirth and similar A value could not be read, for example a date not in yyyy-MM-dd.
0014 Agent with this phone number already exists Phone already on another agent.
0014 An agent with this BVN already exists / ... NIN ... Identity number already on another agent. The same number on a customer of another type (an individual account the bank opened) does not conflict.
0096 Agent category is required, Business type is required, Business name is required for registered businesses, Date of birth is required ..., At least one of BVN or NIN is required A required field is missing. These are reported under the generic code; read desc.
0096 anything else Unexpected failure. Nothing is created; retry once.

Ownership and permission are checked before any account numbers are drawn, so a refused request does not consume numbers from the range or leave an orphaned customer behind.

What is created

Section titled “What is created”
  1. A customer of type AGENT, status ACTIVE, KYC status verified at the tier you asked for, nationality NG, tagged with your channel.
  2. A transaction account (SAVINGS, NGN) named after the display name.
  3. A fee account (SAVINGS, NGN) named <display name> - Fee, marked with the role FEE.
  4. An agent profile stamped with your client id as creator. If your own organisation is itself an agent, your profile is also recorded as the aggregator for commission purposes; that link carries no API authority.
  5. A customer.created webhook carrying the transaction account number, TIN and CAC number, followed by agent.profile.created.

Date of birth, gender, address, state and LGA are written once here; the identity-update route changes BVN/NIN only.

Notes

Section titled “Notes”
  • No idempotency key. Retry on timeout by looking the agent up with find by phone before resending; a resend after a success answers 0014.
  • Tier. TIER_2 and TIER_3 are accepted as sent. The bank’s tier policy for agents is applied through its own review; see KYC uploads.
  • Nothing is funded. Both accounts open at zero. Fund the transaction account from your settlement account with the calls on Fund and charge a wallet.

In the portal

Section titled “In the portal”

The Agents page lists every agent your organisation has onboarded: name and agent code, type (AGENT or MERCHANT, individual or registered business), whether it is active, how many accounts it holds, its largest available balance with currency, and when it last transacted. The page is read-only; it appears in the rail once you have at least one agent.