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
Picks $50 or $100 on the town page, types a school code if they have
one, pays by card (Stripe).
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.
At any shop on the list: shows the card, staff take $5 or $10 off
the bill. The balance on the pass drops.
Can send the whole card to someone else (the same "send to a friend"
as vouchers today).
Valid 3 years. At $0 the card leaves the wallet's main list.
Shop
Joins the scheme (same sign-up as the bingo board). Nothing to
pay.
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.
Is paid weekly for what was taken off, less the scheme's share
(default: shop gets 80%).
Organiser (Tappl or a school)
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).
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:
Buy: $50 / $100, school code
SCHOOL.
Wallet card: the Google pass (balance, shops used,
the tile picture) and the Apple pass (balance, strip, link to the
list).
Shop scanner: pick which shop you are, scan, take
$5 or $10, see the cap stop the 5th visit, Undo.
Shops: the list, with dots for the visits used at
each shop.
Money: the settings (cap, shop share, school
share), what is owed, and a 300-buyer simulation that
compares the money's spread with the cap against no cap.
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
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.
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.
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.
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.
The name on the card and the page. The demo says
"Christchurch voucher card". Pick the real words.
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.