Skip to content
BankCore Partner API

Balance and statement

Every balance and statement read runs the ownership guard: the agent you name must be your own organisation’s agent profile, or an agent or merchant you onboarded with sub-agent access switched on. Anything else answers 0012. See Ownership model.

Balances are read from the posting engine, not from a cached column, so they reflect the last committed posting. An agent has two accounts: the transaction account (main) and the fee account (income), where commission lands. Both reads below report available balances, which is what can be spent now; holds are already deducted.

Agent calls name the agent in the X-Agent-Account header: the agent’s 10-digit transaction account number, as returned in txnAccountNumber at onboarding. See Read your estate for the header rules.

Agent balance (A4)

Section titled “Agent balance (A4)”
GET/api/legacy/agent/balancescope: accounts:read
Header Required Description
X-Agent-Account Yes The agent’s 10-digit transaction account.
Terminal window
curl https://api.bankcore.ng/api/legacy/agent/balance \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Agent-Account: 6020012345"
Field Description
main Available balance of the transaction account.
income Available balance of the fee (commission) account, or 0 when the agent has none.

A failure replaces the body with { "code": "0012", "desc": "..." } for an unknown account or one you cannot reach, and { "code": "0096", ... } when the header is missing or names an account that is not an agent’s.

Downline balance (A21)

Section titled “Downline balance (A21)”
GET/api/legacy/agent/downlines/{realId}/balancescope: agents:read

The same { main, income } answer, addressed by path instead of by header: realId is the downline’s 10-digit transaction account number. No X-Agent-Account is read. The ownership guard runs on the account in the path, so a number outside your estate answers 0012 with is not linked to this API client, and an unknown one 0012 with Downline account not found.

Terminal window
curl https://api.bankcore.ng/api/legacy/agent/downlines/6020012345/balance \
  -H "Authorization: Bearer $TOKEN"

Use A4 when you already act for the agent on other calls; use A21 when you are walking the downlines list and have account numbers in hand. Both read the same balances.

Agent statement (A5)

Section titled “Agent statement (A5)”
GET/api/legacy/agent/statementscope: transactions:read

Posted entries on one of the agent’s two accounts, newest first by effective posting date. The response is always the bare array; there is no { success, total, data } envelope and no total. For the enveloped form use the transaction list (A23) on Read your estate, which has the same entry shape.

Parameter Description
accountType 00 for the transaction account (default), 01 for the fee account. 01 on an agent with no fee account falls back to the transaction account.
from, to Calendar dates, yyyy-MM-dd or dd/MM/yyyy, read in Africa/Lagos. to is inclusive of the whole day.
start_date, end_date The same window as epoch milliseconds. When both forms are sent, the epoch form wins.
page 1-based.
after Alternative to page: a 0-based page index, default 0. page wins when both are sent.
size Entries per page, default 50, capped at 200.
trantype Accepted for compatibility and not applied; every transaction type is returned.

Omit from and the window opens at the beginning of the account’s history; omit to and it closes now. There is no server-side cap on the span, so page rather than widen. An unparseable date answers 0012 instead of being ignored.

Terminal window
curl "https://api.bankcore.ng/api/legacy/agent/statement?accountType=00&from=2026-03-01&to=2026-03-31&page=1&size=50" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Agent-Account: 6020012345"

Entry fields

Section titled “Entry fields”
Field Description
id Transaction id.
amount Always positive. Direction is in type.
narration The transaction description.
date Posting time, falling back to creation time for an entry not yet posted.
type CREDIT or DEBIT from this account’s point of view.
balance Running ledger balance after this entry.
reference BankCore’s transaction reference.
channel The source channel of the transaction.
transactionType TRANSFER_IN, TRANSFER_OUT, NIP_OUTWARD, NIP_INWARD, BILL_PAYMENT, AIRTIME_PURCHASE, FEE, TAX, STAMP_DUTY, REVERSAL, CASH_IN, CASH_OUT, DEPOSIT, WITHDRAWAL and others; see Field dictionaries.
status COMPLETED, PENDING, FAILED, REVERSED and others.
metadata The transaction’s own context: beneficiary and sender details, NIP session id, biller and receipt for bills, fee components, and initiatedByPartner when you debited an agent’s account. The same object reaches webhook subscribers.

Fees, VAT and stamp duty on an interbank transfer are separate DEBIT entries that share the principal’s external reference. Commission on bills and POS arrives on the fee account (accountType=01) as each transaction completes.

Errors

Section titled “Errors”
Code When
0012 Account not found (Agent account not found, Downline account not found); the agent is not yours (is not linked to this API client); unparseable date; non-numeric page or size.
0096 X-Agent-Account missing on an agent call (X-Agent-Account header is required); the header names an account that is not an agent’s or a corporate’s (Account does not belong to an agent).

Notes

Section titled “Notes”
  • Display add-back. For accounts migrated from the previous core with an unreconciled slice, the balance reads add the remaining unreconciled amount back into the available figure for display. Debit enforcement uses the real available balance, so a debit for the full displayed figure can still answer 0004.
  • Time zone. Calendar dates are Lagos days; timestamps in entries are UTC (Z).
  • Your own accounts. The agent routes also accept your own organisation’s transaction account in X-Agent-Account (an agent or a corporate profile both resolve), so A4 and A5 read your own balance and statement too. A corporate with no fee account reports income as 0. Your relationship manager confirms which account number to send; see Request headers.

In the portal

Section titled “In the portal”

The Accounts page shows available and ledger balance for each of your organisation’s own accounts and opens into a statement with the same date window and export. The agents and merchants you onboarded appear on the Agents page with their available balance and last activity.