Wallets — per-customer credit balances

Every Jaza customer owns a wallet for a given app and environment (sandbox or live). The wallet stores their current credit balance and updates as customers top up and spend.

​

One wallet per customer (per environment)

Create customers with @jazadev/node (createCustomer). You get an id with a cus_ prefix. Store that id on your user record and pass it to init, consume, and (if needed) getBalance. Sandbox and live are isolated — a cus_… from test keys does not exist under live keys. Remint when you go live; see Authentication.

​

How the app learns the balance

1. Host calls jaza.init({ customerId }) → snapshot includes wallet.balanceCredits
2. JazaProvider loads that session via getSession / authEndpoint
3. SDK refreshes via client wallet APIs while authenticated

You do not need a host getBalance route for the primary UI path.

​

Balance rules

• Non-negative balance.
• Atomic deductions on consume (race-safe).
• Top-ups and successful consumes reflect on subsequent reads and client refreshes.

​

How balances change

​

UI in your app

Use the official client SDKs:

• JazaBalance — shows credits from the session / client wallet (JazaBalanceWidget is a deprecated alias)
• JazaTopUpButton — opens MoMo checkout (session-minted top-up JWT)
• JazaLedger — credit movements
• JazaActionButton — gates taps by feature cost (never consumes)

​

Next steps

• Handshake · Ledger · Top-up · Consume credits