Introduction

The BankCore Partner API is for organisations that hold a partner API client at a bank running BankCore: corporates collecting payments, and aggregators running an estate of agents and merchants. Your client is tied to one customer record at the bank (your corporate or agent profile), and everything you do through the API happens in that customer’s name. Your reach is that customer’s own accounts plus the agents and merchants you onboard, whether individuals or registered businesses; a partner does not open or manage accounts for the bank’s other customers.

This is not the bank’s internal channel API. The bank’s own USSD, mobile and web servers use the same endpoints with much wider rights; a partner client is deliberately narrower, and this documentation describes only what a partner can reach.

What you can do

• Collect with virtual accounts. Issue dynamic (one payment, with a time limit) or fixed (permanent) account numbers that anyone at any Nigerian bank can transfer to, and be told when money lands. See Virtual accounts.
• Run an estate of agents and merchants. Onboard agents and merchants parented to you, individuals or registered businesses, and read balances and statements across the whole estate. See Ownership model.
• Move money. Fund and charge accounts against your settlement account, transfer between accounts at the bank, send interbank (NIP) transfers, pay bills and buy airtime, from your own accounts or an agent’s you may debit. See Fund and charge a wallet.
• Receive webhooks. Signed events for completed transactions and inflows, with retries you can inspect. See Events and payloads.

Three checks on every call

Every request you make passes three independent checks before it reaches any business logic. Understanding them explains most refusals you will ever see.

Check	Question it answers	Where it is configured	Refusal
Scope	May this client perform this kind of operation at all?	The scope list on your client	HTTP 403, SCOPE_DENIED
Ownership guard	May this client act on this account?	Your own customer record and the sub-agents you onboarded (see Ownership model for what that does and does not include)	PARTNER_ACCOUNT_FORBIDDEN or PARTNER_SUBAGENT_FORBIDDEN (legacy endpoints report 0012)
IP allowlist	May this client call from this address?	The allowlist on your client	HTTP 403, IP_NOT_ALLOWED

Scopes say what, the ownership guard says whose, the allowlist says where from. Nothing in a request body can widen any of them: the tenant, the customer you act for, the scopes and the fee and settlement accounts all travel inside your bearer token. See Scopes, IP allowlist and rate limits and Ownership errors.

The partner portal

The partner portal is an administrative console that sits beside the API; it is not required to integrate. Your finance and operations staff use it to see account balances and statements, virtual account inflows, interbank transfers, webhook subscriptions and their deliveries, and the API fees your usage is charged. Every page of this documentation ends with a short “In the portal” section naming the portal page that shows the same thing, so that engineering and operations are reading the same facts. See The partner portal.

Getting credentials

Partner API access is requested through your relationship manager at the bank, not self-served.

1. Your relationship manager raises a request against your customer record naming the client, the scopes you need, the IP addresses you will call from, and the account your API fees are charged to. That fee account must belong to your customer record.
2. The request goes through the bank’s approval workflow. Until it is approved the client exists but cannot authenticate.
3. On approval the bank generates your client_id and client_secret and hands them to you out of band. The secret is shown once and never returned by any endpoint.

Sandbox and production are separate clients with separate credentials; see Environments and base URLs.

Who at the bank approves

A request is submitted by your business manager at the bank and approved by a bank administrator or compliance officer. The names of those roles are the bank’s; you only need to know that approval is a human step and that your relationship manager can tell you where a request is.

Where to start

1. Set up

Environments, then Authentication, then Request headers.

2. Understand the rules

Scopes, IP allowlist and rate limits, Responses and error codes, Idempotency.

3. Build

Collecting? Start at Virtual accounts. Running an estate? Start at Ownership model. Paying out? Start at Fund and charge a wallet. Then wire up Webhooks.

4. Ship

Work through the Go-live checklist. The Walkthrough takes a merchant from onboarding to its first inflow end to end.

In the portal

The API access page shows the client your organisation holds, its scopes, rate limits and IP allowlist, and the fees it has been charged.