Operations
Read a balance, credit, debit, transfer between wallets, and pay out to an external account. All amounts in kobo.
Move value
Every move is idempotent on reference — the key you reconcile on and the
anchor a refund credits back against. Amounts are kobo (integer minor units).
Some verbs are provider-capability-gated; an unapproved provider declares the
capability false and the core fails closed rather than attempting a move the
provider would reject.
Balance
GET /wallet/customer?customerId={walletId}
Returns the wallet's available and booked balance in kobo.
Credit
POST /wallet/credit — fund a wallet (where the provider supports
merchant-initiated credit; some providers fund only by the customer transferring
IN to the account number).
| Field | Type | Required | Description |
|---|---|---|---|
walletId | string | yes | The wallet handle from create. |
reference | string | yes | Idempotent reference for this move. |
amountKobo | number | yes | Amount in kobo. |
currency | string | yes | e.g. NGN. |
narration | string | no | Statement narration where supported. |
Debit
POST /wallet/debit — spend from a wallet. Approval-gated: a provider must
approve the merchant to debit customer wallets; until then the capability is
false and a debit fails closed. Same body as credit.
Transfer (wallet → wallet)
POST /transfer/wallet — move value between two wallets on the same provider
(the peer-transfer / card-issuance primitive). Same move body, addressing a
destination wallet on the provider.
External send (payout)
POST /transfer/bank/customer — send value OUT of a wallet to a named external
bank account (crosses to the banking rails). Extends the move body with:
| Field | Type | Required | Description |
|---|---|---|---|
destinationAccountNumber | string | yes | The external account to pay. |
destinationBankCode | string | yes | NIP/sort code of the destination bank. |
destinationAccountName | string | no | For the provider's name-check where required. |
Requery
GET /transaction/batch/{reference} — ask "what happened to reference X?" when a
move's outcome is unknown. The only way an uncertain move becomes knowledge rather
than a manual reconciliation.