# Velocity Pay — Product Specification

**Version:** 1.0.1  
**Last Updated:** January 2026  
**Product Owner:** Velocity Africa (Qantra)

---

## 1. Executive Summary

Velocity Pay is a multi-platform bill-payment application that enables individuals and businesses in Zimbabwe to pay utilities, purchase airtime, and send batch payments through a single, streamlined experience. The application supports EcoCash, Mastercard/Visa (MPGS), and wallet-based payment processors, and is available across Android, iOS, and the web.

Built with Flutter, Velocity Pay delivers a consistent, high-quality user experience on mobile devices and desktop browsers alike. It is designed from the ground up to support multi-workspace / multi-tenant scenarios, making it suitable for both individual consumers and organisations that manage multiple business entities.

---

## 2. Target Audience

| Segment | Description |
|---------|-------------|
| **Individual consumers** | Pay utility bills (ZESA electricity, water), purchase airtime (Econet, NetOne, Telecel), and top up mobile wallets. |
| **Small businesses** | Manage payments across a single workspace with history tracking and repeat transactions. |
| **Enterprises / NGOs** | Use batch payments via recipient **Groups** to disburse funds to many recipients at once (e.g. payroll, beneficiary disbursements). |
| **Developers / Integrators** | Organisations that need to embed payment functionality into their own systems can reference Velocity Pay's gateway integration patterns. |

---

## 3. Supported Platforms

| Platform | Status | Notes |
|----------|--------|-------|
| **Android** | GA | Native APK / App Bundle distribution via Google Play. |
| **iOS** | GA | Native IPA distribution via the App Store. |
| **Web** | GA | Progressive Web App (PWA) served via Nginx. Works on all modern browsers (Chrome, Firefox, Safari, Edge). |
| **Linux / macOS / Windows** | Beta | Desktop builds available for internal/admin use. |

---

## 4. Core Feature Set

### 4.1 Onboarding & Authentication

- **Phone number sign-in:** Users enter their mobile number, receive an OTP verification code, and authenticate.
- **Google Sign-In:** OAuth-based authentication for web users (desktop and mobile web).
- **Persisted sessions:** Tokens are stored securely on-device so users remain signed in across cold starts.
- **Splash animation:** A branded loading animation plays on cold start before the app routes to the appropriate screen.

### 4.2 Workspaces

- After authentication, users are presented with a workspace selector if they belong to multiple organisations.
- A workspace bundles a user's billing accounts, transaction history, and groups under one organisational context.
- Single-workspace users are auto-routed directly to the home screen.
- Guest (unauthenticated) users receive a transient workspace UUID so they can still make one-off payments.

### 4.3 Home Dashboard

- **Account balance widget:** Displays the current balance for the authenticated user's workspace. Includes a currency selector (USD, ZWG, etc.).
- **Bill provider directory:** A dynamic, API-driven grid of available billers (Econet, NetOne, ZESA, Telecel, etc.). Each card shows the provider's logo, name, and description.
- **Recent activity feed:** A chronological list of the user's most recent transactions with status chips (Success / Pending / Failed). Each transaction includes a **Repeat** action that pre-fills the payment flow with the same details.
- **Pull-to-refresh:** Manually reload balances, providers, and transactions.
- **Responsive layout:** On mobile the UI uses a full-bleed SliverAppBar and bottom NavigationBar; on tablets and desktop it uses a side NavigationRail.

### 4.4 Payment Flow

The payment flow is a multi-step wizard with the following stages:

| Step | Screen | Description |
|------|--------|-------------|
| 1 | **Home → Provider Select** | User taps a bill provider (e.g. Econet, ZESA). |
| 2 | **Recipients** | Choose a saved contact, enter a phone number manually, or pick from the device's native contacts. |
| 3 | **Product Selection** (conditional) | If the provider offers multiple products (e.g. airtime bundles, electricity tokens), the user picks the specific product and amount. |
| 4 | **Pay** | Enter payment amount (when not fixed by product), select the payment processor (EcoCash / MPGS / Wallet), enter the debit phone number, and optionally record the recipient's name and email for a receipt. |
| 5 | **Confirm** | Review all transaction details before submission. The user sees a line-item breakdown: amount, charge, gateway charge, tax, and total. |
| 6 | **Gateway** | The app opens the payment processor's checkout page (hosted WebView for Mastercard, or redirect for mobile wallets). The user completes payment authorisation. |
| 7 | **Polling** | The app polls the backend for the transaction result for up to 30 attempts (~90 seconds). Progress is indicated by a step counter and status text. |
| 8 | **Integration** | On success, the backend posts the payment to the billing provider (e.g. credits the electricity meter). A loading indicator shows this progress. |
| 9 | **Receipt** | A full transaction receipt is displayed with share capabilities (image export via `share_plus`). The receipt includes transaction ID, date, amount, charges, provider, and status. |

**Error handling at every step:** Network errors, failed payments, and integration failures are surfaced with human-readable messages and a **Retry** button. Users can cancel polling at any time.

### 4.5 Payment Processors

| Processor | Label | Description |
|-----------|-------|-------------|
| **EcoCash** | `ECOCASH` | Zimbabwe's mobile money wallet. Authorisation via USSD push or in-app prompt. |
| **Mastercard Payment Gateway Services** | `MPGS` | Card payments (Visa, Mastercard). Hosted checkout page in a WebView. |
| **Wallet** | `WALLET` | In-app wallet balance (available only to authenticated users with a funded workspace wallet). |

### 4.6 Transaction History

- Full, searchable history of all past transactions for the current workspace.
- Each transaction item displays: provider icon, provider name, amount, date (relative time), and a coloured status chip.
- **Repeat transaction:** One-tap repeat that pre-fills the payment flow with the same provider, product, amount, and payment processor.
- **Receipt view:** Tap any historical transaction to view its full receipt.

### 4.7 Groups & Batch Payments

Groups allow users to organise recipients and send batch payments efficiently.

- **Group creation:**
  - **Manual form:** Enter a group name, description, and add recipients one at a time.
  - **CSV file import:** Upload a CSV file containing recipient names, phone numbers, amounts, and email addresses. A sample CSV template is provided.
- **Group management:** View all groups, search by name, select multiple groups for bulk deletion.
- **Batch creation:** Within a group, create a payment batch that processes all recipients. Each batch is a discrete payment run with its own status.
- **Batch detail:** View the status of each item (recipient) in a batch. Individual batch items can be inspected for success/failure details.

### 4.8 Users & Permissions

- Authenticated workspace admins can view and manage the list of users associated with their workspace (accessible from the **More** menu).
- User listing is available at `/users` and is protected behind an auth guard.

### 4.9 Uptime & Service Status

- A real-time service status dashboard showing the operational state of every integrated bill provider and payment processor.
- Each service displays:
  - Service name and icon (EcoCash, Econet, ZESA, etc.)
  - Up/Down status indicator (green/red chip)
  - Last-checked timestamp (relative time)
- Summary bar shows total counts of Up vs Down services.
- Data is fetched on-screen load and supports pull-to-refresh.

### 4.10 Profile & Account Management

- **Profile:** View account details (accessible from `/profile`).
- **Change Workspace:** Switch to a different workspace without logging out.
- **Logout:** Clears local session and returns to the landing screen.
- **Account Deletion:** GDPR/Play Store compliant account deletion request flow at `/delete-account`.

### 4.11 Contact & Support

- Dedicated contact screen accessible from the **More** menu.
- Footer links in the web navigation rail provide quick access to About, FAQs, Privacy Policy, and Terms of Service on the Velocity Africa website.

---

## 5. Architecture & Technology

| Layer | Technology |
|-------|-----------|
| **Framework** | Flutter (Dart 3.9+) |
| **State Management** | Provider + ChangeNotifier (with Freezed immutable models) |
| **Routing** | GoRouter (declarative, path-based, with auth guards) |
| **HTTP Client** | Dio |
| **Code Generation** | Freezed + json_serializable + build_runner |
| **Local Storage** | SharedPreferences (token, workspace ID, user preferences) |
| **Backend** | Velocity Pay API (`payapi.velocityafrica.net/api`) |
| **Auth** | OAuth 2.0 (Google) + Phone OTP |
| **Payment Gateway** | Mastercard MPGS (hosted checkout via WebView + JavaScript) |
| **Push Notifications** | Firebase Cloud Messaging |
| **Analytics** | Firebase |
| **Deployment** | Docker + Nginx (web), Google Play (Android), App Store (iOS) |

---

## 6. Environment Configuration

Velocity Pay supports compile-time environment switching via `--dart-define` flags:

| Flag | Values | Description |
|------|--------|-------------|
| `APP_ENV` | `test`, `live` | Selects the runtime environment. Defaults to `test`. |
| `BASE_URL` | Any URL | Overrides the backend API base URL. |
| `CLIENTID` | String | Google OAuth web client ID. |
| `SIMULATE_PAYMENT_SUCCESS` | `true`, `false` | When `true`, the gateway flow returns a simulated success (development only). |
| `GATEWAY_SCRIPT_URL` | URL | Mastercard checkout JavaScript bundle URL. |

**Pre-release checklist:**
- `assets/.env.live` points to the live API.
- `SIMULATE_PAYMENT_SUCCESS` is set to `false`.
- `GATEWAY_SCRIPT_URL` uses the production Mastercard script.

---

## 7. Navigation Structure

### Authenticated Shell (with nav bar / nav rail)

```
/home                         → Home dashboard (providers + recent activity)
/groups                       → Group listing
/groups/create                → Create group (manual form)
/groups/create-from-file      → Create group (CSV upload)
/groups/:groupId              → Group detail
/groups/:groupId/batches/create → Create batch for group
/groups/batches/:batchId      → Batch detail
/history                      → Full transaction history
/more                         → More menu (workspace switch, users, uptime, contact, logout)
/users                        → User management
/uptime                       → Service uptime status
/profile                      → User profile
/contact                      → Contact support
/workspace                    → Workspace selector
```

### Payment Flow (no nav in shell — full-screen wizard)

```
/recipients                   → Recipient selection
/make-payment                 → Payment form (amount, processor)
/confirm                      → Transaction confirmation
/gateway                      → Payment gateway (native WebView)
/gateway-web                  → Payment gateway (web)
/gateway-redirect             → Gateway redirect handler
/poll                         → Transaction status polling
/poll/:id                     → Poll for specific transaction
/integration                  → Post-payment billing integration
/receipt                      → Transaction receipt
/receipt/:transactionId       → Receipt for specific transaction
```

### Onboarding (full-screen, no shell)

```
/onboarding/landing           → Welcome landing page
/onboarding/phone             → Phone number entry
/onboarding/verify             → OTP verification
/onboarding/login             → Sign-in (Google OAuth for web)
/onboarding/complete          → Onboarding complete / redirect
```

### Public

```
/splash                       → Animated splash screen
/delete-account               → GDPR account deletion request
```

---

## 8. Key User Journeys

### 8.1 First-Time User — Pay Airtime

1. Opens app → splash animation plays.
2. (Guest) Assigned a transient workspace → lands on Home.
3. Taps **Econet** from the provider grid.
4. Enters recipient's Econet phone number.
5. Selects an airtime bundle product (e.g. $5 Airtime).
6. Chooses **EcoCash** as the payment processor.
7. Enters their own EcoCash number (the debit phone).
8. Reviews the confirmation screen: amount, charges, total.
9. Confirms → Gateway opens → approves the EcoCash prompt.
10. App polls for status → "Success".
11. Billing integration updates the airtime → Receipt displayed.
12. Taps **Share** to send receipt via WhatsApp.

### 8.2 Returning User — Repeat Transaction

1. Opens app → session is persisted → lands on Home.
2. Scrolls to **Recent Activity**.
3. Finds a past Econet airtime transaction, taps **Repeat**.
4. All fields are pre-filled → confirms without re-entering data.
5. Completes the gateway flow → Receipt shown.

### 8.3 Business User — Batch Payment

1. Signs in with Google → selects their organisation workspace.
2. Navigates to **Groups** via the nav bar.
3. Taps **+** → **Create from File** → uploads a CSV of 50 recipients.
4. Opens the group → taps **Create Batch**.
5. Reviews the batch summary (50 items, total amount).
6. Confirms → batch is submitted → each item processed individually.
7. Monitors batch progress on the batch detail screen.
8. All successes / failures are visible per item.

---

## 9. Responsive Design & Accessibility

- **Mobile (< 768px):** Bottom NavigationBar, single-column layout, SliverAppBar with the Velocity logo.
- **Tablet / Desktop (≥ 768px):** Side NavigationRail (256px wide, always visible), constrained content width (600px max), footer links with About/FAQs/Privacy/Terms.
- All interactive elements meet minimum touch target sizes (48×48dp).
- Skeleton loading placeholders are used during data fetches to reduce perceived latency.

---

## 10. Security & Compliance

- All API communication is over HTTPS.
- Auth tokens are persisted in platform-secure local storage.
- The Google OAuth client ID is a public value — no secrets are embedded in client bundles.
- Payment gateway integration uses Mastercard's hosted checkout; Velocity Pay never handles raw card numbers.
- GDPR compliance: Users can request account deletion via a dedicated in-app flow.
- Environment configuration uses compile-time flags rather than runtime `.env` files, preventing secrets from leaking into web bundles.

---

## 11. Upcoming / Roadmap

| Feature | Status | Target |
|---------|--------|--------|
| Push notifications for transaction status | Planned | Q2 2026 |
| Dark mode support | Planned | Q2 2026 |
| Multi-currency wallet top-up | Planned | Q3 2026 |
| Desktop app distribution (App Store / Microsoft Store) | Planned | Q3 2026 |
| Offline transaction queuing | Under Review | TBD |
| ZWL (ZiG) full currency support | In Progress | Q2 2026 |

---

## 12. Glossary

| Term | Definition |
|------|-----------|
| **Bill Provider** | A utility company or service provider whose bills can be paid via Velocity Pay (e.g. ZESA, Econet). |
| **Payment Processor** | The financial rail used to move funds (EcoCash mobile money, Mastercard/Visa card, in-app Wallet). |
| **Workspace** | An organisational context that groups billing accounts, transaction history, and recipient groups. |
| **Group** | A collection of recipients for batch payment processing. |
| **Batch** | A discrete payment run executed against a group of recipients. |
| **Gateway** | The Mastercard-hosted payment checkout page where card details are entered. |
| **Polling** | The process of repeatedly checking the backend for a transaction's final status after gateway authorisation. |
| **Integration** | The backend step that posts a confirmed payment to the bill provider's system (e.g. crediting a meter). |
| **MPGS** | Mastercard Payment Gateway Services — the card payment processor. |

---

*For technical setup instructions, environment configuration, and build commands, refer to the project's [README.md](../README.md).*