PIN change and move income

Both routes sit under agents:manage, a scope partners may hold. They are unrelated in effect: one does nothing, the other moves money.

Change PIN (A18)

POST/api/legacy/agent/change_pinscope: agents:manage

BankCore does not hold agent PINs. PINs belong to the application the agent signs in to, which is yours. This route exists only so integrations ported from the previous core do not break; it reads no header and no body and always answers success.

{ "code": "0000", "desc": "PIN change handled by channel" }

Do not call it as a confirmation of anything. If your application manages agent PINs, manage them in your application.

Move income (A19)

POST/api/legacy/agent/move_incomescope: agents:manage

Every agent has two accounts: the transaction account it spends from, and a fee account that receives its commission. This call sweeps the entire available balance of the fee account into the transaction account as one internal transfer. There is no amount parameter and no body.

Request

Header	Required	Description
X-Agent-Account	Yes	The agent’s transaction account number.

cURL

curl -X POST https://api.bankcore.ng/api/legacy/agent/move_income \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Agent-Account: 0000123456"

Response

{
  "code": "0000",
  "desc": "Successful",
  "retRef": "TXN20260401143000001",
  "fromAccount": "0001123456",
  "toAccount": "0000123456",
  "availableBalance": "265000.00",
  "ledgerBalance": "265000.00",
  "transdatetime": "20260401143000"
}

Response

Field	Description
retRef	The transfer’s reference.
fromAccount	The fee account.
toAccount	The transaction account.
availableBalance, ledgerBalance	The transaction account’s balances after the sweep, as two-decimal strings.
transdatetime	yyyyMMddHHmmss, server local time.

The transfer is narrated Move income to main account, posts under your channel, and appears on both accounts’ statements as TRANSFER_OUT on the fee account and TRANSFER_IN on the transaction account.

Errors

Code	desc	When
0004	No income to move	The fee account’s available balance is zero or negative. Not a failure to retry.
0012	No fee account found for agent	The transaction account is not in an agent range that has a paired fee account.
0012	Agent account not found: ...	The header names an unknown account.
0012	Account ... is not linked to this API client	The agent is not yours, or sub-agent access is off.
0012	Account ... belongs to a sub-agent; debiting it requires the sub-agents:debit scope	You can see the agent but may not spend its money.
0062		The fee or transaction account is locked, frozen or under PND.
0096	X-Agent-Account header is required	Header missing.
0096	Move income failed: ...	Unexpected failure. Check the fee account’s statement before retrying; the sweep may have posted.

Ownership

Reading the agent needs sub-agent access. The sweep is a debit of the fee account, and the fee account belongs to the agent, so on a sub-agent this call needs the sub-agents:debit scope as well, and the transfer is stamped with initiatedByPartner. Both accounts belong to the same agent, so the money never leaves the agent; the stamp is still written, because the agent did not initiate it. See Acting on a sub-account’s money.

On your own organisation’s agent profile, if you have one, no extra scope is needed.

Notes

• Not idempotent. A second call immediately after a success answers 0004, because the fee account is now empty. A second call after a 0096 may sweep again if commission has arrived in between. Use retRef and the fee-account statement (A5 with accountType=01) to reconcile.
• Whole balance only. To move a partial amount, use a transfer from the fee account to the transaction account; the fee account number is feeAccountNumber from onboarding. See Wallet-to-wallet transfer.
• Commission arrives by itself. Bill payment and POS commission are credited to the fee account by the platform as each transaction completes; this call is only the sweep.

In the portal

The Accounts page shows both the transaction and fee accounts of any agent profile your organisation holds. Sub-agents’ fee balances appear as income on the API only; the Agents page shows each agent’s largest available balance.