Skip to main content

Payment Architecture

Related docs: Checkout Flow · Order Lifecycle.md · Security Compliance

1. Overview​

Pakashop uses a dual-provider, orchestrated payment architecture:

ProviderRole
PawaPayPrimary mobile money: MTN, Airtel, Zamtel deposits, vendor payouts, refunds
FlutterwaveCard payments (Visa/Mastercard) via hosted page; mobile money failover
MockAdapterLocal development / integration tests (PAYMENT_PROVIDER=MOCK)

All provider interactions are hidden behind a unified internal API surface:

App code
  └── PaymentService (facade)
        └── PaymentOrchestrator (routing + failover)
              ├── PawaPayAdapter
              ├── FlutterwaveAdapter
              └── MockAdapter

2. Payment Flow Diagrams​

2.1 Mobile Money (PawaPay — Happy Path)​

2.2 Card Payment (Flutterwave — SAQ A)​

2.3 Mobile Money Failover (PawaPay → Flutterwave)​

3. Provider Details​

3.1 PawaPay​

PawaPay acts as the primary mobile money aggregator for Zambian networks (MTN, Airtel, Zamtel). It handles real-time USSD push notifications for customer deposits and orchestrates high-volume disbursements for vendor payouts.

  • Security: Webhooks are validated via HMAC-SHA256 signatures to ensure authenticity.

3.2 Flutterwave​

Flutterwave provides a PCI-DSS SAQ A compliant card payment experience through a hosted checkout page. It also serves as a resilient failover for mobile money operations.

  • Security: Webhooks are verified using a unique secret hash shared between the gateway and the backend.

4. Webhook Processing and Idempotency​

To ensure reliability and prevent duplicate processing, the platform implements a strict idempotency layer for all incoming gateway events.

4.1 Event Deduplication​

Every incoming webhook is logged in a centralized events table. If a notification with a previously processed gateway reference arrives, it is fanned out and ignored by the business logic, protecting the order state from race conditions.

4.2 Processing Steps​

  1. Verification: Gateway signatures are validated before any data is parsed.
  2. Persistence: The raw event is logged for audit purposes.
  3. State Transition: Payment and Order records are updated in a single transaction.
  4. Settlement: Financial positions are calculated for each order item, separating vendor earnings from platform fees.
  5. Auditing: The transaction is logged using a privacy-aware utility that scrubs sensitive user details.

5. Delayed Settlement Model​

Pakashop utilizes a non-custodial settlement model to minimize financial risk and regulatory overhead.

  • Provider Holding: Customer funds are held in the provider's licensed ecosystem (PawaPay/Flutterwave) until delivery is confirmed.
  • Orchestrated Release: Payouts are triggered only after an administrative or automated delivery confirmation transitions funds from a HELD to a RELEASABLE state.

6. Request Idempotency​

To prevent accidental double-charging during poor network conditions, payment initiation requests generate a unique key based on the order and timing metadata. Duplicate requests within a 24-hour window return the existing transaction state rather than creating a new charge.

8. Local Development​

For development and automated testing, a mock provider is used to simulate the full payment lifecycle (USSD prompts, successful/failed webhooks) without requiring live network connectivity or incurring transaction fees.