Skip to main content
This page explains the concepts. To turn it on step by step, follow the wallets setup guide.

​
How wallet balance works

A wallet holds prepaid balance for one customer in one currency, in minor units (paise/cents). It is the first thing an invoice consumes: at generation time the payment order is always wallet → adjustment credit notes → payment gateway so prepaid customers burn their balance before a card or mandate is ever touched. Every movement is an append-only transaction with the balance after it, and posts balanced double-entry ledger legs (top-ups: DR Cash / CR Customer Credit; drains: DR Customer Credit / CR Customer AR). Typical uses: AI/API products selling prepaid usage credit, annual prepayment with monthly burn-down, and promotional credits with an expiry.

​
Create a wallet

One wallet per customer+currency (409 on duplicates). GET /v1/customers/{id}/wallets lists a customer’s wallets.

​
Top up

  • manual records money you already received (bank transfer, offline payment) — it books DR Cash / CR Customer Credit.
  • promotional grants credit with no money movement (books a Credits & Adjustments expense) and may carry "expires_at". Expired residue is written off automatically by the billing-cycle sweep with an expiry transaction.
Drains consume residues oldest-expiring first, so dated promotional credit is always spent before it can lapse.

​
Auto-recharge

When the balance falls below the threshold, the billing-cycle sweep charges the customer’s saved payment method for the recharge amount. No saved method (or a decline) notifies the customer and retries on later sweeps. Send both fields as null to disable.

​
How draining works

Nothing to configure: when any invoice is generated (scheduler renewal, mandate debit path via credit preview, subscription creation), the wallet in the invoice currency drains up to the amount owed. If the wallet covers the whole invoice it is created paid; a partial drain lowers amount_due and the rest follows the normal collection path.
GST note: wallet top-ups are recorded as received advances with no tax on the top-up receipt — tax is charged on the consumption invoice as usual. Review this treatment with your CA if you rely on advance-tax provisions.

​
Next steps

Set up wallets

Create and fund your first wallet

Wallets API

The full endpoint reference