Nova – Customer & Merchant Modules

Scope: turn the agent rail into a live ecosystem. Phase order: Customers → Merchants. Channels: Web (v1) → Android/iOS, USSD, SMS, Merchant Portal/App, APIs. Compliance: tiered KYC/AML, risk-based limits, STR/CTR, agent oversight.

A) Customer Module

A0. Objectives & Guardrails

TTV (Time-to-Value): < 5 min from sign-up to first cash-in (median).

Activation: ≥ 45% P2P send within 7 days; ≥ 70% balance lookup in first 48h.

Reliability: P95 < 3s per txn; success ≥ 99.7%.

Compliance: 100% KYC captured, 100% screened, STR SLA 100% within 24h.

Safety: fraud loss < 5 bps of GMV; successful reversals within window ≥ 85%.

A1. Personas & Jobs-To-Be-Done

Everyday Payer (un/underbanked): “Store value safely; send to family; cash-out close by.”

Side-Hustle Owner: “Collect payments, track income, withdraw reliably.”

Gig/Payroll Recipient: “Get paid instantly, spend or cash-out with predictability.”

A2. Onboarding Flows (Self-Serve, Agent-Assist, USSD)

Self-Serve (Web/App)

Enter phone → OTP.

Minimal profile (name, DoB) → create wallet (pending KYC).

KYC capture: ID front/back (or passport), selfie liveness.

Real-time screening & dedupe (NIN/passport + selfie match).

On “clear” → Tier 1 issued; set PIN (4–6 digits); consent receipts stored.

Post-onboarding coach-marks: how to cash-in, how to P2P, fees.

Agent-Assisted (at Outlet)

Agent scans ID + selfie; captures address; obtains consent.

System runs watchlist + dedupe.

OTP → set PIN.

Offer first cash-in; hand printed/SMS quick-start.

USSD Pre-Reg

*XXX# → 1) Register → capture basic fields → OTP → create wallet → prompt to finish KYC at agent or via web link.

A3. KYC/AML (Barbados-first, risk-based)

Tiers & Limits (illustrative; configure per policy)

Tier	Use Case	Max Balance	Single Txn	Daily Cap	Required Docs
T1	Entry, low-risk	BBD 1,000	500	1,000	ID + selfie, phone, minimal address
T2	Everyday	5,000	2,000	5,000	+ Proof of Address (≤ 3 mo)
T3	High-limit	Policy	Policy	Policy	+ Source of Funds/Wealth, EDD

Document Acceptance

ID types: National ID, Passport, (optionally DL).

PoA: Utility bill, bank statement, government letter (≤ 3 mo).

SoF: Payslip, employer letter, bank statement, sales records (micro-biz).

Controls & Evidence

Selfie liveness score threshold; OCR MRZ verification; duplicate ID lock.

Flag handling: PEP/sanctions hit → hard block + EDD queue; fuzzy match → manual review.

Re-KYC cadence: T1: 24 mo; T2/T3: 12 mo or on trigger (SIM swap, device change, risk spike).

Retention: KYC artifacts hashed + timestamped; WORM storage per policy.

A4. Funding & Usage Flows

Cash-In (Agent)

Input MSISDN + amount → name preview → (optional) customer OTP → agent PIN → dual SMS receipts; agent e-float −, customer +; commission accrual.

Cash-Out (Agent)

Customer requests in app/USSD → receives OTP/token → agent validates + checks ID → pays cash; receipts; agent e-float +.

P2P (Registered)

Pick contact or enter MSISDN → verified name preview → fee preview → PIN → instant post; reversal window opens (e.g., 5–15 min, configurable).

P2P (Unregistered / OTC)

Sender → enters recipient MSISDN → system issues withdrawal code; sender pays fee; recipient can redeem at agent with code + ID.

Essential UX

Fee calculator inline;

Insufficient funds → show “Top-Up at nearest Agent” (map/list);

Recent recipients, notes/memos, mini-statement (last 10).

A5. Safety, Fraud & Risk Rules

Device trust: attestation, jailbreak/root detection, device binding.

SIM-swap watch: compare SIM change date; velocity/cool-downs post swap.

Velocity rules: burst sends, new account high-value, off-hours cash-outs.

Geo/device anomalies: sudden location change, new device + high value.

Name-mismatch & typo sends: require manual confirm; show large name tile.

Social-engineering guard: proactive tips; “are you being asked to send to a stranger?” interstitials on risky patterns.

Holds & Reviews: auto-hold when composite risk score > threshold; human review SLA.

A6. Reversals, Disputes & CX

Reversal window (e.g., 10 min, funds untouched) → instant auto-reversal; else dispute case to CX.

Dispute types: wrong beneficiary, wrong amount, fraud, other.

Evidence: screenshots, message logs; agent outlet notes when relevant.

SLA: P50 < 30 min (simple), P90 < 24h (investigation).

Refund rails: to original wallet; notify both parties.

SMS Templates (samples)

P2P Sent: Nova: Sent BBD {amt} to {name}. Bal: {bal}. Txn:{id}. If error, reply REV {id} in 10 min.

P2P Received: Nova: Received BBD {amt} from {name}. Bal: {bal}. Txn:{id}.

Cash-Out Token: Nova: Withdrawal code {code} for BBD {amt}. Valid 15 min.

A7. Accessibility & USSD

USSD main: *XXX#

1 Send Money
2 Cash Out
3 Balance
4 Mini Statement
5 Upgrade KYC
0 Help

Short paths; confirm screens show recipient name + fee; PIN only at last step.

USSD errors mapped to human-readable codes; retry hints.

A8. Data Model & State Machines (delta)

Customer {id, msisdn, tier, risk_score, status(active|hold|closed), created_at}
Wallet {id, balance, available, holds[], currency, limits{single,daily,rolling}}
Txn {id, type(p2p|cashin|cashout|...), amount, fee, from_wallet, to_wallet, state(init|posted|reversed|held), created_at}
ReversalWindow {txn_id, expires_at, eligible}
Device {id, platform, attestation, first_seen, last_seen, compromised_flag}

Txn State: init → posted → (reversed|settled); holds release on post or expiry.

A9. API Surface

POST /v1/public/customers/signup → {phone} → OTP route.

POST /v1/customers/kyc → pre-signed URLs for ID/selfie; returns tier.

POST /v1/customers/pin → set/reset PIN (OTP proof).

POST /v1/customers/p2p → {to_msisdn, amount, memo}; idempotent.

POST /v1/customers/p2p/unregistered → issues OTC code.

GET /v1/customers/wallet → balance, recent.

GET /v1/customers/limits → per tier.

POST /v1/customers/reversals → {txn_id, reason} within window.

Webhooks (customer): txn.updated, kyc.status, reversal.updated.

A10. Metrics & Dashboards

Acquisition: sign-ups/day, channel mix.

Activation: first cash-in %, first P2P %, 7d retention.

Liquidity: agent coverage vs user heatmap; cash-out fail (% stockouts).

CX: NPS, disputes/1k txns, reversal success %, time to resolution.

Risk: alerts/1k txns, false-positive %, loss bps.

A11. QA & UAT (high-value scenarios)

KYC duplicate ID → block + EDD.

P2P to wrong MSISDN → reversal within window successful.

SIM swap detected → high-value send blocked until cooldown.

Offline USSD path (gateway delay) → graceful retry/backoff.

SMS delay path → receipts eventually consistent, no double-post (idempotency).

A12. Agile Plan (4 sprints to MVP)

S1: Sign-up/OTP/PIN, balance/mini-statement, observability.

S2: KYC capture + screen + dedupe; Tier-1; limits service.

S3: P2P (reg & OTC), reversal window, USSD send/cash-out token.

S4: KYC upgrade (PoA/SoF), disputes v1, fraud rules v1, accessibility polish.
Go-Live → Hardening → Scale.

B) MERCHANT MODULE — Deep Spec

B0. Objectives & Guardrails

Acceptance footprint: 2k–5k active merchant points in 6–12 months.

Payment UX: ≤ 10s from scan to confirmation (P95).

Settlement: D+1 bank payout accuracy = 100%; reconciliation breaks < 5 bps GMV.

Merchant NPS: ≥ +40; refund cycle P50 < 30 min (wallet-to-wallet).

B1. Merchant Taxonomy & Onboarding

Types

Nano/Micro: sole traders, market stalls, taxis (KYC ≈ individual + trade).

SME: shops, restaurants, services (biz license, tax ID, bank details).

Enterprise/Billers: utilities, telco, gov’t, chains (full corporate KYC, UBO).

Account Structure

Master Merchant → Branches → Tills (cashiers).

Roles: Owner/Admin, Manager, Cashier; RBAC by store/till.

KYC Pack (by type)

Type	Required Docs
Nano/Micro	Govt ID, (optional) trade license, selfie, PoA; bank/mobile account for settlement
SME	Cert. of Registration, Tax ID, director IDs, PoA (business), bank letter/void cheque
Enterprise/Biller	Cert. of Inc., Articles, Board Resolution, UBO/KYC for principals, tax/VAT, bank mandate

Process

Application (web/agent/field), docs upload.

Screening (PEP/sanctions), dedupe on entity name/reg.

Contract e-sign (MDR, refunds policy, surcharging terms).

Merchant ID + Till Numbers + QRs issued; sandbox access for API/webhook tests.

Training (POS/app, QR, refund, dispute handling).

B2. Acceptance Modes & UX

QR Static (v1)

Static QR with merchant/till ID; customer scans, enters amount; merchant sees in-app/USSD confirmation.

QR Dynamic (v2)

Merchant app generates amount-bound QR; customer scans; amount locked; reduces wrong-amount disputes.

Pay Merchant (manual ID)

For non-smartphone customers: enter Till Number via app/USSD; confirm merchant name; enter amount; PIN.

Payment Request / “Push-to-Pay”

Merchant enters customer MSISDN and amount; customer receives prompt (app/USSD/SMS) to approve; good for call-center, delivery.

Online Checkout

Redirect: merchant site → Nova pay page → user confirms → IPN/webhook.

Direct API (PCI-free wallet pay): backend-to-backend with customer auth (OTP/app confirmation).

Receipts

Merchant sees success screen + audible/visual cue; printable/Bluetooth printer optional.

Customer gets SMS/app push; includes merchant name, amount, TxnID.

B3. Pricing & Fees

Customer @ POS: free.

Merchant MDR: tiered by volume (e.g., 1.0%–1.8% with floors/caps).

Settlement to bank: free up to N per month, then small fee; instant payout premium (future).

Refunds: free within X days (wallet-to-wallet); MDR reversal policy defined.

B4. Settlement & Reconciliation

Ledgering: T-instant wallet credit to merchant; fees accrued off-ledger bucket.

Settlement run: D+1 net of MDR/adjustments → merchant bank via partner rails.

Reconciliation

T-level: txn.ledger == receipt == webhook (idempotent).

Batch-level: bank credits == Nova settlement file; variances auto-ticketed.

Reports: daily statement, fee breakdown, refunds, chargebacks, adjustments.

B5. Refunds & Disputes

Refund window (configurable): full/partial from merchant portal/app; only to original payer wallet.

Customer-initiated disputes: merchant notified; respond with notes/evidence.

Hierarchy: customer error (merchant-assisted refund) vs goods/service issue (merchant → resolution; Nova mediates if needed).

Chargebacks (if bank rails): adhere to bank timelines; mirror status to portal.

B6. Merchant Risk & Compliance

KYC/UBO verified; enhanced checks for high-risk MCCs.

Transaction monitoring: high refund rates, collusion rings (same users, circular flows), pass-through behavior.

Surcharging & receipts: comply with consumer protection (display fees clearly).

Watchlist rescreen: nightly; STR on suspicious patterns.

Data protection: restrict cashier PII visibility; least-privilege.

B7. Merchant Portal & App

Dashboard

Today’s sales, yesterday vs 7-day avg, top hours, refund rate.

Payments

Receive QR, Payment Request, confirm incoming; cashier mode with PIN.

Tips (optional): add amount before confirm; dedicated accounting line.

Settlement

D+1 schedule, past settlements, export to CSV/QuickBooks.

Refunds

Lookup by TxnID/amount/date; full/partial; reason codes; audit trail.

Users & Tills

Invite users; assign till numbers; reset PINs; enable shift mode.

Reports

Sales by branch/cashier/MCC; fees; disputes; tax report.

B8. Merchant APIs & Webhooks

Checkout / Payments

POST /v1/merchant/payments/request → create Payment Request to MSISDN (push-to-pay).

POST /v1/merchant/payments/refund → {original_txn_id, amount, reason} (idempotent).

GET /v1/merchant/payments/{id} → status.

POST /v1/merchant/qrs → create static/dynamic QR (returns payload/PNG).

GET /v1/merchant/settlements?from=…&to=… → batch files, statuses.

GET /v1/merchant/reports/sales → filters (date, branch, till, MCC).

Webhooks (HMAC-signed, replay-protected)

payment.created / payment.approved / payment.failed

refund.created / refund.approved / refund.failed

settlement.created / settlement.settled

Signature: X-Nova-Signature: sha256=… over body + timestamp; 5-min skew window.

Security

OAuth2 client-credentials for server-to-server; JWT for portal/app; mTLS optional for enterprises.

Idempotency-Key on write ops; 429 with Retry-After on burst.

B9. USSD for Merchants (fallback)

*XXX# (Merchant)
1 Receive Payment (Enter amount -> show code)
2 Payment Request (Enter MSISDN -> amount)
3 Today’s Sales
4 Refund (TxnID -> amount -> reason)
0 Help

Compact confirmations; SMS echoes all actions.

B10. Data Model (merchant-side)

Merchant {id, legal_name, trade_name, kyc_level, mcc, settlement_bank, mdr, status}
Branch {id, merchant_id, name, address, manager_id}
Till {id, branch_id, code, cashier_id, status}
Payment

{id, merchant_id, till_id, amount, fee, payer_wallet, state(init|approved|failed|refunded), method(qr|push|id), created_at}

Refund {id, payment_id, amount, reason, state, created_at}
SettlementBatch {id, date, total_gross, total_fees, total_net, bank_ref, state}

B11. Ops, SLAs & Monitoring

Uptime: 99.9% monthly; Status Page updates < 10 min on incidents.

Settlement SLA: D+1 complete by 10:00 local; variance report by 12:00.

Webhook SLA: 99% delivered < 60s; retry backoff (1m, 5m, 15m, 1h, 6h, 24h).

Support: merchant hotline, dedicated queue for billers; P1 response < 15 min.

Observability: txn success/fail by mode, webhook DLQ, settlement breaks, refund latency.

B12. Analytics & Growth

Adoption: active merchants (7/30d), by vertical and parish.

Usage: txns/merchant/day, AOV, QR vs push share.

Health: refund rate, dispute rate, MDR revenue, net rev after fees.

Programs: fee holidays for verticals, QR starter kits, cashier incentives.

B13. QA, UAT & Negatives

Duplicate merchant registration → merge/suppress duplicate.

Refund > original amount → blocked; correct error.

Missing webhook ack → retries capped; manual re-send tool.

Offline QR (no data) → deferred confirm via SMS; portal marks as “pending.”

B14. Agile Plan (3 sprints to initial C2B)

S1: Merchant KYC + master/branch/till; receive by Till ID; portal basics.

S2: QR static/dynamic, cashier app mode, Payment Request, receipts.

S3: Refunds, webhooks + signing, D+1 settlement job, reports v1.
Go-Live (C2B/QR) → Hardening → Enterprise/billers integration → Online checkout.

C) Diagram & Asset TODOs

Customer Sign-Up & KYC (swimlane: Customer, Agent, KYC Service, Risk).

Cash-In / Cash-Out (sequence: Agent ↔ Ledger ↔ SMS).

P2P + Reversal Window (state machine).

Merchant Acceptance Matrix (QR static/dynamic, push-to-pay, USSD, online).

Settlement & Reconciliation (D+1 batch flow, variance handling).

Refunds Lifecycle (merchant/app → ledger → payer).

Webhook Security (timestamp, HMAC, retries) infographic.

D) Deliverables

Customer & Merchant user stories (above) with acceptance criteria.

Limits/pricing tables (ready to copy into config).

API shapes to append to your existing OpenAPI.

Ops playbooks (SLA, incident, settlement).

QA matrices for UAT.

Customer & Merchant Scope

Nova – Customer & Merchant Modules#

A) Customer Module#

A0. Objectives & Guardrails#

A1. Personas & Jobs-To-Be-Done#

A2. Onboarding Flows (Self-Serve, Agent-Assist, USSD)#

A3. KYC/AML (Barbados-first, risk-based)#

A4. Funding & Usage Flows#

A5. Safety, Fraud & Risk Rules#

A6. Reversals, Disputes & CX#

A7. Accessibility & USSD#

A8. Data Model & State Machines (delta)#

A9. API Surface#

A10. Metrics & Dashboards#

A11. QA & UAT (high-value scenarios)#

A12. Agile Plan (4 sprints to MVP)#

B) MERCHANT MODULE — Deep Spec#

B0. Objectives & Guardrails#

B1. Merchant Taxonomy & Onboarding#

B2. Acceptance Modes & UX#

B3. Pricing & Fees#

B4. Settlement & Reconciliation#

B5. Refunds & Disputes#

B6. Merchant Risk & Compliance#

B7. Merchant Portal & App#

B8. Merchant APIs & Webhooks#

B9. USSD for Merchants (fallback)#

B10. Data Model (merchant-side)#

B11. Ops, SLAs & Monitoring#

B12. Analytics & Growth#

B13. QA, UAT & Negatives#

B14. Agile Plan (3 sprints to initial C2B)#

C) Diagram & Asset TODOs#

D) Deliverables#