The town voucher card: design note (17 Nov 2026)

Glenn's idea, 16 Nov. Prototype: https://tappl-ideas.pages.dev/town-card/. Code: branch tappl-ideas-2026-11-17, folder scripts/lead_magnet_bot/tappl_ideas/.

The idea in one paragraph

Today's pack makes the buyer choose five shops. The town card does not. The buyer puts $50 or $100 of credit on one card in Google or Apple Wallet and spends it at any shop in the scheme, $5 or $10 at a time. A cap per shop (Glenn's example: at most 4 visits) spreads the money across town. Shops are paid for what is spent with them. A school or club that sells cards through its code keeps a share of each card.

How it works

Buyer

  1. Picks $50 or $100 on the town page, types a school code if they have one, pays by card (Stripe).
  2. The card lands in the wallet: balance, "shops used 0 of 21", barcode. Google shows every shop as a picture tile and ticks the ones used. Apple shows the balance and a strip, and links to the shop list in the web app.
  3. At any shop on the list: shows the card, staff take $5 or $10 off the bill. The balance on the pass drops.
  4. Can send the whole card to someone else (the same "send to a friend" as vouchers today).
  5. Valid 3 years. At $0 the card leaves the wallet's main list.

Shop

  1. Joins the scheme (same sign-up as the bingo board). Nothing to pay.
  2. Scans the customer with the scanner it already has. The scanner shows "Christchurch voucher card: $60 left, 1 of 4 visits used here" and two buttons: $5 off, $10 off. A button greys out with the reason when a rule stops it (cap reached, not enough left). Undo works for 15 minutes.
  3. Is paid weekly for what was taken off, less the scheme's share (default: shop gets 80%).

Organiser (Tappl or a school)

  1. A school gets a code and a link, as with bingo fundraisers today. Every card sold with the code pays the school its share (default 15% of the card).
  2. One money screen: cards sold, spent at shops, money held (sold, not yet spent), owed to each shop, owed to each school.

What the demo shows

Five tabs on one page, all in the browser, demo shops only:

Reused vs new

Part Reused from today New
Spend at the counter The balance-voucher flow (20 Oct): staff take an amount off, the rest stays, 15-minute Undo (_voucher_spend.js) The card belongs to a scheme, not one shop; the per-shop cap; fixed $5 / $10 buttons
Scanner scan.html already lists a customer's vouchers and shows "take off" buttons One more block for a town card
Wallet pass Voucher pass code (_voucher_wallet.js), which already shows "$X left" and expires at $0; barcode = the person's Tappl QR A scheme class (Tappl colours), the tile picture, "shops used"
School share ol_bingo_fundraisers code + link, as a pack carries its club today A card carries the fundraiser id and its share
Payment The Stripe webhook's idempotent mint (as ol_voucher_sales) The charge is on Tappl's account, not the shop's (see open decision 4)
Data — 5 tables + one spend function: town_card_schema.DRAFT.sql (not applied; tested on a throwaway local database)
Rules — town_card_engine.js: every rule in one file, used by the demo and meant for the live scanner; node tests pass

Open decisions for Glenn

  1. What the cap counts. As built (your example): at most 4 visits per shop, $5 or $10 each. That lets $40 go to one shop, so a $100 card can be spent at just 3 shops. The other setting in the demo, at most $20 per shop, makes a $100 card reach at least 5 shops and a $50 card at least 3. In the demo's 300-buyer run (a made-up crowd where most people have a usual place), the top 3 shops take 68% of the money with no cap, 57% with 4 visits, 49% with $20 per shop; the quietest shop gets $70, $100 and $130. My pick: $20 per shop. Both are one setting.
  2. Who funds the school's share and Tappl's fee. As built: the shop is paid 80% of what is spent with it; the school keeps 15% of each card sold with its code; Tappl keeps the rest (5% on a school card, 20% on a plain card) and pays the card fees from it. The other way: shops are paid 100% and the buyer pays $55 for $50 of credit. My pick: the 80% shop rate. It is still far cheaper for a shop than the pack, where it gives its $5 voucher in goods for no cash.
  3. Unspent money. Money stays on cards until spent; some cards are never finished. Who keeps what is left at expiry: Tappl, the schools, or split across the shops? The demo shows how much is held.
  4. How shops are paid. One payment covers many shops, so today's set-up (the buyer pays the shop's own Stripe directly) cannot be used. Stripe's "separate charges and transfers" lets Tappl take the payment and later send each shop its share. Stripe lists NZ as supported, but transfers must stay in the same region, and Stripe recommends this charge type only where the platform covers the shops' negative balances. Our shops have Standard accounts, so this needs a check in Stripe test mode first. The fallback is a weekly bank payment by hand.
  5. The name on the card and the page. The demo says "Christchurch voucher card". Pick the real words.
  6. Worth a thought: a card spendable at many shops is a stored-value product, which NZ AML rules may treat differently from one shop's voucher.

Next step if you say go

Apply the migration, build the scanner block and the pass (both reuse code that is live today), run a Stripe test-mode purchase and transfer, then a private round with demo shops on your phone.