Acting on an agent's money

A sub-agent’s account holds a different legal person’s money. The platform lets you move it, under a separate grant, and it writes your identity onto every such transaction so the sub-agent and the bank can see who acted. This page is the contract for that.

What you need

Three things, all set by the bank:

The agent must be a sub-agent you onboarded (its profile carries your client id).
Sub-agent access must be switched on for your client.
Your client must hold the sub-agents:debit scope.

Missing 1 or 2 means the account is unreachable and the call answers 0012 with is not linked to this API client. Missing 3 alone answers 0012 with belongs to a sub-agent; debiting it requires the sub-agents:debit scope. The ordinary scope for the call (transactions:withdraw, nip:transfer and so on) is still required on top.

The check runs inside the money core, not at the route, so it applies identically whether you reach a transfer through a provider money route naming the agent’s account in the body, an agent route with X-Agent-Account, or a BankCore-native route.

Which calls are covered

Any call whose source account is the sub-agent’s. The debit target is whatever account the request names as the one being charged.

Call	Where documented	Source account named by
Charge (C9)	Fund and charge a wallet	`fromAccountNumber`
Transfer between accounts at the bank (C10)	Wallet-to-wallet transfer	`fromAccountNumber`
Interbank transfer (C11, A7, native `POST /api/nip-transfers`)	Interbank transfer (NIP)	`fromAccountNumber`, or `X-Agent-Account` on the agent route
Bill payment and airtime (C16, C17, A12, A13, native `POST /api/bill-payments`)	Bill payments and airtime	`fromAccountNumber`, or `X-Agent-Account`
Agent transfer (`/transact/transfer/mobile`)	Wallet-to-wallet transfer	`X-Agent-Account`
Move income (A19)	PIN change and move income	`X-Agent-Account` (the fee account is the source)

Credits are different. Fund (C8) and deposit (C20) debit your settlement account and credit the account you name; the destination is not ownership-checked, so you can fund a sub-agent, or indeed any active account at the bank, with the scope alone. The guard protects what is taken out, not what is put in.

What gets recorded

On every debit of an account that is not your own customer’s, the transaction’s metadata gains two keys before it is saved:

{
  "beneficiaryName": "JOHN DOE",
  "beneficiaryAccount": "0123456789",
  "beneficiaryBank": "058",
  "nipSessionId": "100003202604011500000002",
  "senderName": "ADEBAYO STORES",
  "senderAccount": "0000123456",
  "feeAmount": 52.50,
  "vatAmount": 3.94,
  "stampDutyAmount": 0,
  "initiatedByPartner": "pa_ab12cd34",
  "initiatedByPartnerCustomerId": "9f8e7d6c-0000-0000-0000-000000000003"
}

Key	Meaning
`initiatedByPartner`	Your `client_id`.
`initiatedByPartnerCustomerId`	The id of your organisation’s customer record. Not the sub-agent’s.

The stamp is applied on the principal debit of internal transfers and charges, on the principal debit of an interbank transfer, and on the debit of a bill payment. It is never written when you debit your own accounts, and never by staff, channel servers or background jobs.

What the sub-agent sees

The sub-agent’s statement entry for the debit carries that metadata in full (see the entry shape on Balance and statement). The same object is rendered on the transaction detail page the bank’s staff use, and it is included in the transaction.completed and nip.transfer.completed webhook payloads any subscriber receives for that transaction.

What the sub-agent does not see is your narration dressed up as its own instruction. Write the memo or narration so that it reads correctly from the sub-agent’s side: name the purpose and your organisation, not “transfer”.

Fees

Fees, VAT and stamp duty on a sub-agent’s interbank transfer are debited from the sub-agent’s account as separate statement lines, exactly as they would be if the sub-agent had sent the transfer itself. Your own API usage fee, where your client has one, is charged to your fee account as usual. See Fees, VAT and stamp duty.

Handling disputes

Expect the sub-agent to query a debit it did not initiate. Prepare for it:

Keep your own record of every sub-agent debit keyed by the retRef (or your transactionRef) the call returned, with the business reason. The bank will ask you for it.
Reconcile daily against the sub-agent’s statement (A5 or A23 on the transaction account) filtered to entries whose metadata.initiatedByPartner is your client id.
Reversals are the bank’s. There is no API to reverse a completed debit. A disputed debit is raised with your relationship manager, who can see the attribution on the transaction. Do not “reverse” by funding the sub-agent from your settlement account unless your agreement with it says so; that creates a second transaction, not a reversal.
Pending is not failed. A 0009 on an interbank transfer means the money may have left the sub-agent’s account; check the transaction before retrying. See Check a transaction.

In the portal

The Transactions page shows debits on sub-agents’ accounts alongside your own, flagged as belonging to an agent, with the counterparty and narration.