The token wallet

The token wallet is a single per-parent balance, and it is your Premium switch: while the wallet holds tokens, every child in your family is on Premium automatically. There is nothing to subscribe or cancel — topping up turns Premium on, and it only turns off when the wallet actually runs out.

What you see

The wallet card on Family shows:

• Balance — current token count.
• Days of premium remaining — roughly balance ÷ number of children (children still inside their free trial aren't counted, since trial days are free). Tells you when you'll need to top up next.
• Currently funding — how many children the wallet is paying for right now.
• Top up button.

What your children see

Each claimed child sees a Family Tokens card on their own Profile: the wallet balance as a token count (never the KES value), who tops it up, and the recent top-ups. When a top-up is confirmed they get their own notification, and an Ask for a top-up button lets them ping you — at most once every 6 hours per child. The same Ask for a top-up action appears when they tap a locked Premium subject in the Library or CEA picker.

How tokens are spent

1. Every child past their free trial debits 1 token / day while the wallet has tokens.
2. The debit runs at midnight EAT via a scheduled job. Children still inside their 7-day trial are never charged.
3. If the wallet hits 0, Premium pauses for everyone — nothing is cancelled, it just freezes.
4. Topping up switches Premium back on immediately — locked subjects open the moment the M-Pesa payment confirms, and the daily debit resumes at the next midnight tick.

How tokens are earned

• M-Pesa top-up — the primary route. 1 token = KES 10.
• Promotional credits — occasional school partnerships or admin-granted credits.
• Refunds — if M-Pesa double-charges, tokens credit back automatically.

Common issues

• Top-up succeeded but wallet didn't update. M-Pesa callbacks can lag 30–60 seconds. Refresh after a minute; email us with the M-Pesa code if still missing.
• Days remaining feels wrong. It divides the balance across every child past their trial. When a child's trial ends they join the daily draw and the projection shortens on the next refresh.
• I only want to pay for one child. The wallet funds the whole family — while it has tokens, Premium is on for every child, so a multi-child family draws one token per child per day.