Guide

Wallet

The prepaid ORN API wallet: funding packages, minimum funding, how debits and reversals work, and what happens when the balance runs out.

How the wallet works

API usage is paid from a prepaid wallet held in naira (₦) and debited in kobo. When a call passes authentication, authorization, rate limiting and the free allowance check, the wallet is debited atomically as part of serving the call — the debit and the usage record carry the same request id, so every charge traces to exactly one API call.

Charges are recorded with the classification API_USAGE and the operation name (capability.operation).
Server-side failures are reversed automatically with the classification REVERSAL (see Pricing).
The wallet, its ledger and funding are managed in the Developer Console (Developer → API → Wallet).

Funding packages

Package	Amount
Starter	₦15,000
Builder	₦30,000
Growth	₦75,000
Scale	₦150,000
Business	₦400,000
Enterprise	₦1,000,000

The minimum funding amount is ₦15,000. Funding is paid through Paystack from the Developer Console: you are redirected to Paystack’s secure checkout, and payments are reconciled to your wallet automatically — including by Paystack’s webhook when direct verification is not possible — so a retried payment credits your wallet exactly once.

When the balance runs out

If the balance cannot cover an operation’s price, the call is refused with 402 INSUFFICIENT_API_WALLET and details.required_amount_kobo names the exact price needed. Nothing is partially charged and the operation does not run. Free-allowance calls are unaffected — the allowance is consumed before the wallet is consulted.

{
  "code": "INSUFFICIENT_API_WALLET",
  "error": "Insufficient API wallet balance for this operation.",
  "details": { "required_amount_kobo": 25000 },
  "request_id": "…"
}

A suspended wallet keeps its recorded balance but refuses both debits and credits until it is restored by ORN — a protection against tampering, with any affected period flagged for manual reconciliation.