Nova Agent#

Scope: Everything an Agent (shop owner) needs to onboard customers, handle cash-in/out, manage float, earn commissions, and stay compliant with KYC/AML. Designed for Barbados first, expandable across the Caribbean. Delivery channels:

Web (v1) → Android/iOS apps, USSD, POS, APIs.

Web: https://agents.caricash.com/
APIs: https://api.caricash.com/api/v1/agents

0) Document Control#

1) Purpose & Outcomes#

2) Personas & Roles#

3) Requirements (High-level)#

3.1 Functional#

3.2 Non-Functional#

3.3 Compliance (Barbados-first)#

3.4 Dependencies#

4) Epics → User Stories (with Acceptance)#

Format: Story / Acceptance (Gherkin) / Edge cases

Epic A: Agent Identity & Device Security#

Epic B: Customer Onboarding & KYC#

Epic C: Cash-In & Cash-Out#

Epic D: Float & Liquidity#

Epic E: Commissions#

Epic F: Disputes & Reversals#

Epic G: Training & Certification#

Epic H: Compliance Tools#

Epic I: Reports & EoD#

Epic J: Offline & USSD#

5) Processes (step-by-step)#

5.1 Agent Onboarding (by Field Officer)#

5.2 Customer Registration (at Agent)#

5.3 Cash-In#

5.4 Cash-Out#

5.5 Float Top-Up / Redemption#

5.6 End-of-Day (EoD)#

6) Data Model (simplified)#

7) API Contracts#

All requests carry X-Agent-Id, X-Device-Id, mTLS; OAuth2 client creds + agent JWT; use Idempotency-Key.

Auth#

POST /agent/auth/login
{ "username": "...", "password": "...", "otp": "123456", "device_info": {...} }
→ { "token": "jwt", "agent": {...}, "rBAC": [...] }

Customer KYC#

POST /kyc/customers
{ "msisdn":"1246...", "id_type":"NID", "id_front":"s3://...", "id_back":"...", "selfie":"...", "address":{...}, "consent":true }
→ { "customer_id":"...", "wallet_id":"...", "tier":"T1", "status":"active" }

Cash-In#

POST /txns/cashin
{ "customer_msisdn":"1246...", "amount": 50.00, "confirm_via":"otp", "idempotency_key":"..." }
→ { "txn_id":"...", "state":"posted", "receipts":{ "agent":"...","customer":"..." } }

Cash-Out#

POST /txns/cashout
{ "customer_msisdn":"1246...", "amount": 80.00, "customer_otp":"948201", "idempotency_key":"..." }
→ { "txn_id":"...", "state":"posted" }

Float Top-Up#

POST /float/topup
{ "source":"super_agent", "amount":1000.00 }
→ { "instruction_id":"...", "status":"pending_settlement" }

Commissions#

GET /agents/{id}/commissions?period=2025-08
→ { "total": 243.50, "lines":[{ "txn_id":"...", "amount":0.40, "type":"cashin"}] }

Dispute#

POST /disputes
{ "txn_id":"...", "type":"wrong_beneficiary", "notes":"...", "evidence":["s3://..."] }
→ { "case_id":"...", "status":"open" }

8) Security & Risk Controls#

9) Operations & Support#

10) UX Modules (MVP → v2)#

11) USSD Menus (Fallback)#

*XXX#  (Agent)
1 Cash-In
2 Cash-Out
3 Float
4 End-of-Day
5 Help

#1 Cash-In
  Enter Customer Number:
  Enter Amount:
  Confirm [CustomerName] 50.00? (1)Yes (2)No
  Enter Agent PIN:
  Success: TxnID 7F2A • Bal +50.00

12) KPIs & Analytics#

13) Agile Delivery Plan#

13.1 Definition of Ready (DoR)#

13.2 Definition of Done (DoD)#

13.3 Release Slices (example)#

13.4 RACI (excerpt)#

13.5 Risks & Mitigations#

14) Checklists#

14.1 Agent Go-Live Kit#

14.2 Daily Open/Close#

14.3 Security#

15) Tariffs & Commissions (example – to be finalized)#

16) Content & Training (in-app microcourses)#

17) Glossary#

Appendix A — Field Texts & Receipts (samples)#

Nova: You received BBD 50.00 from AGENT 1024. Bal: 212.40. Txn: 7F2A.

Nova: Cash-out BBD 80.00 for 1246xxxxxxx. Your e-float +80.00. Txn: 91BD.

Appendix B — Limits (illustrative; configurable)#

Appendix C — QA Scenarios (smoke)#

What we’ll need from Engineering to start#