Skip to content
BankCore Partner API

Wallet-to-wallet transfer

This transfer moves money between two accounts held at the bank (“wallet” is the previous core’s word for an account, kept in the path and the page name). It posts immediately, carries no platform fee, and never touches NIBSS. Use it to pay out from your own account to any account at the bank, to move money between your own accounts, or to collect from an agent or merchant you are allowed to debit.

The source must be yours to debit under the ownership model: your own customer’s accounts, or the account of an agent or merchant you onboarded when your client has sub-agent access and holds sub-agents:debit (see Acting on an agent’s money). The destination can be any active account in your bank tenant.

POST/api/legacy/provider/wallets/transactions/transferscope: transactions:transfer

Request

Section titled “Request”
Field Type Required Description
fromAccountNumber string Yes 10-digit source account.
toAccountNumber string Yes 10-digit destination account.
amount decimal Yes Naira, greater than zero.
memo string No Narration on both statement lines. Default Wallet transfer.
transactionRef string No Your reference. Unique per tenant among outbound transfers. Strongly recommended.
Terminal window
curl -X POST https://api.bankcore.ng/api/legacy/provider/wallets/transactions/transfer \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "fromAccountNumber": "6020012345",
    "toAccountNumber": "6020067890",
    "amount": 12500.00,
    "memo": "Commission week 14",
    "transactionRef": "COM-W14-00917"
  }'

Response

Section titled “Response”
{
  "code": "0000",
  "desc": "Successful",
  "retRef": "TRF20260401143000A1B2",
  "clientRef": "COM-W14-00917",
  "fromAccount": "6020012345",
  "toAccount": "6020067890",
  "availableBalance": "87500.00",
  "ledgerBalance": "87500.00",
  "transdatetime": "20260401143000"
}
Field Description
retRef BankCore’s reference for the outbound leg (TRANSFER_OUT). The inbound leg is retRef with -IN appended.
clientRef Your transactionRef, echoed.
availableBalance, ledgerBalance The source account after the debit, as two-decimal strings.
transdatetime yyyyMMddHHmmss, server time.

Both legs carry senderName, senderAccount, beneficiaryName and beneficiaryAccount in their metadata, and each fires a transaction.completed webhook.

Errors

Section titled “Errors”
Code When
0004 The source account’s available balance is below amount.
0012 Missing source, destination or amount; the source is not yours to debit.
0062 The source account is locked.
0094 transactionRef already used.
0096 Unknown source or destination (Account not found), a frozen, PND, dormant or closed account, a velocity limit on the source customer, a currency mismatch, or a system error. desc says which.

Notes

Section titled “Notes”
  • Above ₦5,000,000 the transfer is created PENDING for the bank’s high-value approval and the reply is still 0000. Balances move only on approval; Check a transaction returns 0009 in the meantime.
  • Virtual accounts as destination are routed through the virtual-account inflow path. See Virtual accounts.
  • Idempotency is by transactionRef, exactly as for fund and charge.

Agent twin: transfer from an agent’s account

Section titled “Agent twin: transfer from an agent’s account”
POST/api/legacy/agent/transact/transfer/mobilescope: transactions:transfer

The same transfer, sourced from an agent’s or merchant’s transaction account. The agent is named by the X-Agent-Account header, and you need sub-agents:debit to spend from it.

Header Required Description
X-Agent-Account Yes The agent’s 10-digit transaction account.
Field Type Required Description
toAccountNumber string Yes A 10-digit account number, or an 11-digit phone number, which resolves to that customer’s first account. subscriberId is accepted as an alias.
amount decimal Yes Naira.
memo string No Narration.
transactionRef string No Your reference.

Differences from the provider endpoint:

  • The channel on the transaction is stamped MOBILE.
  • When the agent is a genuine cash-handling agent, the movement is recorded as an agent cash-in (one CASH_IN transaction with both sides) rather than a TRANSFER_OUT/TRANSFER_IN pair. A corporate using the route gets the ordinary pair.
  • The reply reports the agent’s transaction account balance.
  • The transaction metadata is stamped initiatedByPartner so the agent’s statement shows that you moved the money.

The response and error codes are otherwise the same.

In the portal

Section titled “In the portal”

The Transactions register lists both legs. For an agent’s account the same lines appear under Agents, attributed to your client.