Copy page

When it goes sideways

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: cash_balance, the customer's own money (top-ups, payments, refunds). It changes only when money moves: a credit, a debit, an adjustment, a captured hold or an invoice settled from it.

Held

held_balance: 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

cash_balance − held_balance. This is the number that decides whether a charge succeeds, and the one worth showing customers.

Price-reduction credit is not balance

Goodwill, welcome credit and make-goods are granted as discount lots (discount_lots), not cash. They are not money the customer owns: no debit, hold or settlement spends them. Each invoice drafted for the customer draws the live lots in its currency before tax, and names each lot's reason on the discount it gives.

Set one up in the dashboard

Over the API, this is POST /v1/wallets; see Use one over the API.

Use one over the API

customer_id and currency are required to create. Every amount is a {value, currency} object, the value a string in major units and the currency the wallet's own.

A credit requires amount and source: PAYMENT, REFUND, PROMOTION, INVOICE, CHARGE, FEE, MANUAL or TRANSFER. A repeated source and reference is treated as a replay. PROMOTION grants price-reduction credit rather than cash: it needs grant_kind: "PRICE_REDUCTION" and a reason (printed as the discount reason on every invoice it reduces), and may lapse at expires_at.

A hold requires amount, reason and expires_at; the wallet releases it automatically at expires_at if it has not been captured. Only cash less existing holds can fund a hold.

Dashboard and API names

In the dashboard	In the API
Balance	cash_balance
Held	held_balance, the sum of open holds
Available	cash_balance − held_balance
Top up	POST /wallets/{id}/topup
Credit limit	credit_limit, a {value, currency} object
Low balance threshold	low_balance_threshold
Auto-topup	auto_topup_enabled with auto_topup_amount
capture / release a hold	POST /reservations/{id}/capture or POST /reservations/{id}/release

Where wallets go next

1. Invoices draw on them. A wallet-funded invoice settles from the balance rather than a gateway.
2. Corrections land here. When a credit note gives back money the customer had already paid, it goes to their wallet in the invoice's currency and is spent on their next invoice.
3. Goodwill credit is granted as price-reduction lots on the wallet.

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