Wallets
A wallet is a prepaid balance belonging to one customer in one currency. Money goes in by top-up, refund or promotion, and comes out when an invoice draws on it.
Wallets exist because some businesses take the money first. Prepaid usage, account credit, gift balances and deposits all need somewhere to sit that is not an invoice. A customer can hold several wallets, one per currency.
Balance, held, available
Three numbers, and confusing them is the usual source of surprise.
Balance
What is actually in the wallet. It changes only when money moves: a credit, a debit, or an adjustment.
Held
Money reserved but not yet spent. A hold is placed when a charge is expected but not final, typically metered usage accumulating during a period.
A hold has an expiry. It is later captured, which turns it into a real debit, or released, which returns it to available.
Available
balance − held. This is the number that decides whether a charge succeeds, and
the one worth showing customers.
A hold is not a debit
Holds do not reduce the balance, only what is available. A wallet showing plenty
of balance can still refuse a charge because most of it is held. Capture and
release live on reservations: POST /v1/reservations/{id}/capture and
/release.
Set one up in the dashboard
-
Open the customer's Wallets tab
Wallets have no top-level page; they belong to a customer. Open the customer and choose Wallets.
-
Create or top up
A wallet needs only a currency. Top it up with the amount the customer has paid in.
-
Set the guard rails
Credit limit allows the balance to go negative up to a point. Low balance threshold triggers a notification. Auto-topup refills automatically. Max balance and max single credit cap what can be added at once.
These can be pre-set per customer so a wallet is provisioned correctly the first time.
Use one over the API
customer_id and currency are required to create. A hold requires amount,
reason and expires_at. Every amount is a string in major units.
Dashboard and API names
| In the dashboard | In the API |
|---|---|
| Balance | the wallet's balance |
| Held | the sum of open holds |
| Available | balance − held |
| Top up | POST /wallets/{id}/topup |
| Credit limit | credit_limit, major units |
| Low balance threshold | low_balance_threshold |
| Auto-topup | auto_topup_enabled with auto_topup_amount |
| capture / release a hold | POST /reservations/{id}/capture or /release |
Where wallets go next
- Invoices draw on them. A wallet-funded invoice settles from the balance rather than a gateway.
- Overpayments land here instead of becoming a negative invoice balance.
- Promotions that grant credit deposit into a wallet.
Next step
Continue to Credit notes for reducing what a customer owes rather than adding to what they have paid.
Reference
| Topic | When you need it |
|---|---|
| Payments | How money arrives in the first place |
| Credit notes | Reducing an invoice instead of crediting a wallet |
| Wallets API | Credit, debit, adjust, holds, settings and top-up |
| Reservations API | Capturing and releasing holds |