Fund and charge a wallet

Three endpoints move money between your settlement account and another account at the bank. Fund (C8) and deposit (C20) credit an account from the settlement account; charge (C9) debits an account into it. All three are ordinary internal transfers between two accounts the bank holds, so nothing is created or destroyed: every credit to an account is a debit of the same amount somewhere else. The paths still say wallets, which is the name the previous core gave every account; read it as “account”.

The settlement account is configured on your API client by the bank and carried in your token as settlementAccountId. You never name it in a request. If your client has no settlement account, all three calls refuse with 0012.

The typical uses are paying an agent or merchant in your estate (fund) and collecting from one (charge). A charge is a debit, so its source must be your own account or an agent’s you may debit under the ownership model.

The settlement account must be funded

Funding an account draws on the settlement account’s available balance. When it is short, the fund call fails with 0004 and the desc states the available and required amounts. Keep it topped up, and watch its balance on the portal’s Accounts page.

Fund an account (C8)

POST/api/legacy/provider/wallets/transactions/fundscope: transactions:deposit

Credits toAccountNumber from your settlement account.

Field	Type	Required	Description
toAccountNumber	string	Yes	The account to credit, typically an agent’s or merchant’s transaction account. Any active account in your bank tenant is accepted; the destination is not ownership-checked.
amount	decimal	Yes	Naira, greater than zero.
memo	string	No	Narration on both statement lines. Default Wallet funding.
transactionRef	string	No	Your reference. Unique per tenant; see Idempotency. Strongly recommended.
surcharge	decimal	No	Accepted for compatibility with the old contract. It is not applied to the transfer.

cURL

curl -X POST https://api.bankcore.ng/api/legacy/provider/wallets/transactions/fund \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "toAccountNumber": "6020012345",
    "amount": 50000.00,
    "memo": "Salary April 2026",
    "transactionRef": "SAL-20260401-001"
  }'

Request body

{
  "toAccountNumber": "6020012345",
  "amount": 50000.00,
  "memo": "Salary April 2026",
  "transactionRef": "SAL-20260401-001"
}

Charge an account (C9)

POST/api/legacy/provider/wallets/transactions/chargescope: transactions:withdraw

Debits fromAccountNumber into your settlement account. The source must be an account you may debit: one of your own customer’s accounts, or the account of an agent or merchant you onboarded, with sub-agent access on and sub-agents:debit held (see Ownership model). Any other account is refused with 0012.

Field	Type	Required	Description
fromAccountNumber	string	Yes	10-digit account to debit.
amount	decimal	Yes	Naira, greater than zero.
memo	string	No	Narration. Default Wallet charge.
transactionRef	string	No	Your reference. Unique per tenant.

{
  "fromAccountNumber": "6020012345",
  "amount": 1500.00,
  "memo": "Subscription May",
  "transactionRef": "SUB-20260501-0042"
}

When you debit an agent’s account, the transaction metadata is stamped with initiatedByPartner (your client id) and initiatedByPartnerCustomerId, so the agent’s statement shows who acted.

Deposit (C20)

POST/api/legacy/provider/wallets/{accountNumber}/deposit

Identical to fund, with the account in the path and the old jCard field names in the body.

Field	Type	Required	Description
amount	decimal	Yes	Naira, greater than zero.
narration	string	No	Default Wallet deposit.
TransactionID	string	No	Your reference (note the capitalisation). Unique per tenant.

No scope rule on this route

The scope filter has no entry for POST /wallets/{accountNumber}/deposit, so today any active partner token reaches it. Treat it as if it required transactions:deposit, which is what the equivalent fund call needs; the bank may add the rule at any time.

Response

All three return the same shape on success.

{
  "code": "0000",
  "desc": "Successful",
  "retRef": "TRF20260401143000A1B2",
  "clientRef": "SAL-20260401-001",
  "fromAccount": "6020000001",
  "toAccount": "6020012345",
  "availableBalance": "150000.00",
  "ledgerBalance": "150000.00",
  "transdatetime": "20260401143000"
}

Field	Description
retRef	BankCore’s reference for the outbound leg. Use it, or your clientRef, with Check a transaction.
clientRef	Your transactionRef echoed back. Absent if you sent none.
fromAccount, toAccount	Fund and deposit: settlement account to the named account. Charge: the named account to the settlement account.
availableBalance, ledgerBalance	Two-decimal strings. Fund and deposit report the credited account’s balance after the credit; charge reports the debited account’s balance after the debit.
transdatetime	yyyyMMddHHmmss, server time.

Both statement lines carry metadata (senderName, senderAccount, beneficiaryName, beneficiaryAccount) and your channel, and each fires a transaction.completed webhook. See Events and payloads.

Errors

Code	When
0004	Not enough available balance on the source: the settlement account for fund and deposit, the named account for charge.
0012	Missing account number or amount; no settlement account configured on your client; the source is not yours to debit (PARTNER_ACCOUNT_FORBIDDEN, PARTNER_SUBAGENT_FORBIDDEN).
0062	The named account is locked.
0094	transactionRef already used. Nothing moved.
0096	Everything else, with the cause in desc: an unknown account number (Account not found), a frozen, PND-restricted, dormant or closed account, a velocity limit on the customer, a currency mismatch, or a genuine system error.

Read desc on any 0096 before retrying: most of them are a decision, not an outage.

Notes

• Amounts above ₦5,000,000 are not posted immediately. The pair is created PENDING for the bank’s high-value approval workflow, and the call still answers 0000. The balance does not move until a bank officer approves. Check a transaction answers 0009 until then.
• Velocity limits apply to the customer whose account is debited: your corporate for fund and deposit, the account holder for charge.
• Virtual account destinations. If toAccountNumber is a virtual account issued in your tenant, the credit is routed through the virtual-account inflow path (band fees, callbacks). See Virtual accounts.
• Same currency only. All accounts in a transfer must share a currency.

Idempotency

transactionRef (or TransactionID on deposit) is the idempotency key. It must be unique per tenant among outbound transfers; a second call with the same value answers 0094 and moves nothing, whatever the amount or accounts. That holds for a reference whose first attempt failed or was reversed too, so a genuine retry of a failed payment needs a new reference. Without a reference, every call moves money.

If you never saw the reply, do not resend: call Check a transaction with the reference first. See Idempotency.

In the portal

The Accounts page shows the settlement account’s balance and statement. The Transactions register lists each leg as TRANSFER_OUT or TRANSFER_IN with the counterparty from the metadata.