0. Positioning and non-negotiables

NahaTap is the software layer behind QR and NFC merchant identification and payment experiences. A licensed payment partner (Paystack or PayFast - OPEN) processes and holds all funds. NahaTap never holds customer money. It is not a bank, not a wallet, not a payment processor: it is the merchant's till, sales book, customer book and storefront in one.

• Mobile-first: every screen designed for a R1,500 Android phone on a 360px screen first; desktop is a stretched version, never the other way.
• Extremely simple: first-time smartphone business users. One main action per screen. Big tap targets (48px+). Plain words, no banking jargon.
• Low-data: system fonts only (no webfont downloads), pages under ~100 KB, images compressed, works on 2G/3G, offline-tolerant sales book (records locally, syncs when signal returns).
• ZAR everywhere: R formatting with 2 decimals, no other currency in v1.
• English first, isiZulu later: all copy externalised into a language file from day one so isiZulu is a translation job, not a rebuild.
• QR-first, NFC-ready: QR codes are free to print and work on every phone; NFC tags are a hardware upgrade on the same merchant identity URL. One identity system serves both.
• No customer app install: customers interact through the browser (payment page, storefront) and WhatsApp. Only merchants use the NahaTap app shell.
• Honest payment statuses: a payment is initiated, pending, paid, failed or reversed. A pending payment is NEVER shown as successful - the screen says "Waiting for payment" until the partner's webhook confirms.

1. User journey maps

Journey A - Merchant's first day (onboarding to first sale)

Time target: under 10 minutes from link to live QR. KYC review by the partner runs in the background; the merchant can trade immediately in "verification pending" mode with a payout hold, never a payment block.

Journey B - Daily trading rhythm (existing merchant)

Journey C - Repeat customer & loyalty

Journey D - Owner with staff and two stalls (later phase)

2. Merchant onboarding flow (screen by screen)

#	Screen	What happens	Why it exists / rules
1	Welcome	"Sell anything. Get paid on the spot." + Start button	No email, no password. Cellphone number is the account.
2	Cellphone + OTP	Enter number, receive 6-digit code by SMS (WhatsApp fallback)	SA merchants live on their numbers. OTP code never shown as "verified" until server confirms.
3	About your business	Business name, category (food, hair, clothes, airtime, other), area (Soweto township list)	3 fields max. Category drives the starter catalogue template.
4	Your money (partner KYC)	Legal name, ID number, bank account for payouts - handed to Paystack/PayFast subaccount flow	NahaTap never stores full ID or account numbers - tokenised by the partner. Clear line: "Your money goes straight from your customer to your bank. NahaTap never holds it."
5	Your QR is ready	Personal QR shown big; buttons: Download, Print help, Share on WhatsApp	The "magic moment". QR works even before KYC clears (payments held by partner, not blocked).
6	Add your first items	Template list by category (e.g. kotas: chips, russian, cheese) with editable prices, 3 items to start	A storefront with items converts; empty pages do not. Skip allowed.
7	Done - home dashboard	"You're open for business" + today counter at R0.00	End state is the daily dashboard, not a settings page.

3. Customer payment journey (no app, no signup)

Status	Shown to customer	Shown to merchant	Rule
initiated	Checkout opened	Nothing yet	No sale counted.
pending	Yellow "Waiting for payment - do not close"	Yellow "Payment pending" in sales book, not in totals	NEVER counted as money. Auto-expires after partner timeout.
paid	Green "Paid R55.00" + reference	Green, counted in today/week totals, SMS/WhatsApp ping	Only after signed webhook from partner.
failed	Red "Payment did not go through - try again"	Grey failed row (kept for honesty)	Never silently deleted.
reversed	"Refunded"	Red reversal row linked to original sale	Totals adjust; audit trail kept.

4. Every screen and its purpose

MVP = build first. LATER = roadmap. Each screen has ONE main job.

Module	Screen	Purpose (one job)	Phase
1. Registration & onboarding	Welcome	Start account with cellphone number	MVP
	OTP verify	Prove number ownership	MVP
	Business details	Name, category, area	MVP
	Payout setup (partner KYC)	Hand bank/ID details to payment partner	MVP
2. Merchant dashboard	Home (Today)	Today's money (card + cash), sales count, alerts	MVP
	Week/Month toggle	Same numbers, longer window	MVP
	Alerts strip	Pending payouts, stock lows, staff actions needing approval	LATER
3. QR/NFC identity	My QR	Show, download, print-help, share merchant code	MVP
	NFC tag manager	Link/relink NFC stand or band to the same identity URL, mark lost	LATER
4. Storefront & payment page (customer side)	Merchant page	Customer-facing page: items or amount, Pay button, WhatsApp order	MVP
	Checkout (partner hosted)	Card/EFT/Capitec Pay via partner's hosted page	MVP
	Payment result	Waiting / Paid / Failed with honest status	MVP
5. Catalogue	My items	List, add, edit price, hide sold-out	MVP
	Item photos	Compressed photo per item	LATER
6. Sales book	Sales list	Every sale: card (status-coloured) + manual cash, filterable	MVP
	Sale detail	One sale: items, status, reference, refund action	MVP
7. Customers	Customer list	Repeat customers with consent flag, visit count, last seen	MVP
	Customer profile	One customer's history + loyalty state + remove-my-data button (POPIA)	MVP
8. Loyalty	Rewards setup + customer view	"Buy 5 get 1 free" style rules; stamp progress	LATER
9. Inventory	Stock list	Quantity per item, -1 on each sale	LATER
	Low-stock alerts	"Only 3 bread left" nudges	LATER
10. WhatsApp engagement	Message builder	Send a special to opted-in customers via WhatsApp deep links	LATER
	Order-by-WhatsApp button	Customer page button prefilling an order message	MVP
11. Reports	Daily / weekly / monthly report	Money in, top items, card vs cash, export CSV/PDF	MVP (daily first)
12. Staff & branches	Staff list + invite	Add seller (phone invite), role: seller only	LATER
	Branches	Second stall: own QR, own book, rolled up to owner	LATER
13. Subscription & billing	My plan	Current fee model, what NahaTap took, invoices	MVP (read-only)
	Plan picker	% vs monthly choice	LATER OPEN
14. Support & settings	Help	FAQ + "WhatsApp us" + call-back request	MVP
	Settings	Language, PIN, payout account status, delete my account	MVP
15. NahaTap admin (internal)	Admin home	All merchants, GMV, active stands, issues	MVP
	Merchant detail	KYC state, sales, payout health, suspend	MVP
	Partner reconciliation	Partner payouts vs NahaTap ledger, mismatch queue	LATER

5. Navigation and information architecture

Merchant app shell: 5 bottom tabs. Thumb-reach, one hand, icons + words (never icons alone).

Tab	Contains	Main question it answers
1. Home	Today dashboard, alerts, daily report shortcut	"How is business today?"
2. Sell	Big "New sale" (my QR + record cash sale), my items	"How do I take money now?"
3. Money	Sales book, payout status, reports	"Where is my money?"
4. Customers	Customer book, loyalty, WhatsApp specials	"Who buys from me?"
5. More	My QR, staff, branches, plan, help, settings	"Everything else."

Customer side has no navigation - one page, one scroll: items → amount → pay → result. Fewer than 3 taps to payment.

Admin (internal) has a left rail: Merchants, Money (GMV + reconciliation), Devices (QR/NFC stands), Issues (support + suspensions), Settings.

6. Screen-by-screen wireframes (key screens)

Grayscale on purpose: layout before colour. Colour directions are in section 7.

NahaTap admin dashboard (desktop rail layout)

7. Visual design system + three directions

Shared rules whatever direction he picks: system fonts only (low-data), 48px minimum tap targets, money always in tabular figures, status colour + WORD (never colour alone), one primary button per screen, 4.5:1 contrast minimum, POPIA consent always an unticked box with plain words.

Three distinct directions - he picks ONE before implementation (reply PICK A, PICK B or PICK C):

Direction A - "Mzansi Trust"

Deep green + gold on warm off-white. Feels like a stokvel meeting a modern bank: warm, established, proudly South African. Rounded corners, soft shadows, friendly. Best fit if the brand should feel like community wealth and trust first.

Direction B - "Kasi Energy"

Charcoal + signal orange on white. Bold, loud, street-commerce energy - the spaza wall painted bright. Heavy condensed headings, sharp edges, high contrast. Best fit if the brand should feel young, fast and unmistakably Soweto.

Direction C - "Clean Ledger"

Navy + teal on white, ultra-minimal. The serious fintech: thin lines, big whitespace, bank-grade calm. Best fit if the brand should feel like infrastructure that banks and partners trust above all.

8. Database and entity architecture

Relational (Supabase Postgres free tier or Cloudflare D1 - both free). One row per fact, soft deletes, full audit on money events. NahaTap stores NO card, ID-document or bank-account data - partner tokens only.

Entity	Key fields	Relationships / rules
merchants	id, phone (unique, OTP-verified), business_name, category, area, language, kyc_status, partner_subaccount_id, created_at	Has many branches, staff, products, sales, customers. kyc_status: pending / verified / rejected.
branches	id, merchant_id, name, address, is_main	Each branch gets its own QR identity and sales book.
staff	id, merchant_id, phone, name, role (owner/seller), active	Sellers record sales; never see payout or plan screens.
devices	id, merchant_id, branch_id, type (qr/nfc), public_code (unique URL slug), status (active/lost/replaced)	The QR/NFC identity. Public URL = /m/{public_code}. Relinking never changes sales history.
products	id, merchant_id, name, price_cents, photo_url, stock_qty, hidden	Catalogue + inventory in one; stock_qty nullable (most informal traders won't track stock at first).
sales	id, merchant_id, branch_id, staff_id, channel (card/cash), status (initiated/pending/paid/failed/reversed), total_cents, partner_ref, created_at, paid_at	Totals count paid only. partner_ref links to the partner webhook event.
sale_items	id, sale_id, product_id, qty, unit_price_cents	Line items; cash sales can be amount-only.
customers	id, merchant_id, phone, name, consent_whatsapp (bool + timestamp), visits, last_seen_at, deleted_at	POPIA: created ONLY with consent tick; deletion request sets deleted_at and purges contact data in 30 days.
loyalty_rules / loyalty_stamps	rule: id, merchant_id, buy_n, reward_text, active. stamps: id, rule_id, customer_id, count, redeemed_at	Simple "buy N get reward" engine.
payment_events	id, sale_id, partner, event_type, payload_hash, received_at	Immutable webhook audit log - the source of truth for statuses.
payouts	id, merchant_id, partner, amount_cents, status, paid_at	Mirror of partner payouts for the Money tab.
subscriptions	id, merchant_id, model (percent/subscription), rate_bps, active_from	OPEN fee model stored per merchant so the decision can change later without rebuild.
support_tickets	id, merchant_id, type, body, status, created_at	Includes POPIA deletion requests with SLA clock.
admin_users	id, email, role	NahaTap internal team only; every admin action logged.

9. Payment partner integration journey

• Split at source (Paystack Transaction Splits / PayFast Split Payments) means NahaTap's commission never passes through merchant money and vice versa. OPEN which partner goes first - partner replies pending.
• Webhooks, not polling: statuses change only on signed webhook events stored in payment_events. A customer screenshot of "payment sent" never marks a sale paid.
• Reconciliation job (later): nightly compare of partner settlement report vs sales/payouts tables; mismatches go to the admin queue.
• Refunds: merchant taps Refund on a paid sale → partner API → reversed status. Cash refunds happen outside the system and are marked manually.
• Regulatory posture: funds flow customer → licensed partner → merchant bank. NahaTap is software; the partner carries PASA/SARB obligations (TPPP registration sits with the partner's sponsoring bank).

10. Dashboards summary

Dashboard	Audience	Top 3 things it shows
Merchant home	Trader	Today R, sales count, payout on its way
Merchant reports	Trader	Card vs cash, top items, best day
NahaTap admin	NahaLabs	GMV, active merchants, KYC/payout issues

11. MVP versus future roadmap

Phase	Scope	Why this cut
MVP (build first)	Onboarding + OTP, partner KYC handoff, My QR, customer payment page with honest statuses, catalogue (text items), sales book (card + cash), customer book with consent, order-by-WhatsApp button, daily report + CSV, plan (read-only), help/settings, admin home + merchant detail	Proves the loop: sign up → get QR → get paid → see your money. 5-vendor Soweto pilot runs on this alone.
Phase 2	Loyalty engine, WhatsApp specials builder, week/month reports, NFC tag manager (hardware order), stock tracking + alerts	Adds retention and the NFC hardware story once the loop is proven.
Phase 3	Staff + branches, plan picker / subscriptions, reconciliation console, isiZulu, item photos, Lesotho rails (MoPay / M-Pesa / EcoCash)	Scales beyond owner-operated single stalls and beyond Gauteng.

12. Decisions he must make (OPEN)

Choice	Options	Default if he says nothing
Visual direction	PICK A Mzansi Trust / PICK B Kasi Energy / PICK C Clean Ledger	No default - he must pick before implementation.
Platform fee	5% vs 3% per sale	5% (his earlier call)
Fee model	Percent only vs percent + R49/month	Percent only
First payment partner	Paystack vs PayFast	Paystack (replies may change this)
Domain	nahatap.co.za ~R119/yr vs stay on pages.dev	Register at Go

Design v1, 8 Nov 2026. Planning only - no code was written, pushed or sent for this deliverable. Existing nahatap.pages.dev remains a prototype demo.