Concepts
Wallet & ledger
How funds move when you top up, send, and cancel.
Your wallet is a prepaid balance that all rewards draw from. Under the hood
it's a double-entry ledger — every cent is accounted for by an immutable
transaction, which you can read via
GET /v1/wallet/transactions.
Available vs reserved
GET /v1/wallet returns two numbers:
availableCents— spendable balance.reservedCents— value held by rewards that are sent but not fully redeemed yet.
How money moves
| When | What happens |
|---|---|
| Top-up succeeds | availableCents increases (topup entry) |
| You send a reward | Face value moves from available to reserved (reward_hold) |
| A card is issued | The card's value leaves reserved (reward_capture) |
| You cancel / it expires | Un-redeemed value moves back to available (hold_release) |
Because funds are held at send time, a sent reward can never bounce: the recipient's value is guaranteed even if you spend your remaining balance later.
Insufficient funds
If a send would exceed availableCents, the API returns 402:
{ "error": "insufficient_funds", "message": "Wallet balance is too low for this reward" }Top up via POST /v1/topups and
retry. Bulk sends stop at the first insufficient-funds failure and mark the
remaining items as skipped.