Deposits & Balances

When someone transfers money to a customer’s virtual account number, the deposit is verified, credited to the customer’s dedicated ledger wallet, and announced with a customer.deposit.credited webhook — exactly once per deposit.

Check a Wallet Balance

const balance = await client.customer.wallet.getBalance(customerId, walletId);
 
console.log(balance.data.ledger.available);   // spendable NGN
console.log(balance.data.restricted);         // true if the ledger is negative

The ledger balance is authoritative — it is computed from settled platform-ledger entries, not from provider-reported figures.

List Transactions

const history = await client.customer.wallet.listTransactions(
  customerId,
  walletId,
  { page: 1, limit: 20, type: "credit" }
);
 
for (const txn of history.data) {
  console.log(txn.reference, txn.type, txn.amount, txn.status);
}

Responses are sanitized: stable references only, no internal IDs or raw provider payloads.

Deposit Fees

Each deposit carries a processing fee. Who pays depends on the account’s immutable depositFeeBearer snapshot:

If you sponsor fees but your balance is insufficient, the configured fallback applies:

• charge_customer (default) — the customer pays that fee
• create_merchant_receivable — the fee is deferred as your debt (within your exposure limit) and settled oldest-first when you fund your wallet
• hold_customer_deposit — the deposit is credited but unspendable until you fund the fee; after the hold window (1–168h) lapses, funds release to the customer minus the fee

Webhooks