C4 System Context Diagram¶

Field	Value
Status	Draft
Owner	Architecture
Last Updated	2026-04-03
Applies To	Entire Simpaisa Platform

1. Overview¶

This document presents the C4 Level 1 — System Context view of the Simpaisa payment gateway. It shows the platform's relationship with all external actors, regulatory bodies, and channel partners across Pakistan, Bangladesh, Nepal, Iraq and Egypt.

Simpaisa processes 270M+ transactions annually with $1B+ in total payment volume across Pay-Ins, Pay-Outs, Remittances and Cards.

2. System Context Diagram¶

graph TB
    subgraph "Actors"
        Merchant["🏪 Merchants<br/>(API integration, Portal)"]
        Consumer["👤 Consumers<br/>(End users via merchant apps)"]
    end

    subgraph "Regulators"
        SBP["🏛 State Bank of Pakistan<br/>(SBP)"]
        BB["🏛 Bangladesh Bank<br/>(BB)"]
        NRB["🏛 Nepal Rastra Bank<br/>(NRB)"]
        CBI["🏛 Central Bank of Iraq<br/>(CBI)"]
    end

    SIMPAISA["🔷 Simpaisa Platform<br/>Payment Gateway<br/>270M+ txns · $1B+ volume<br/>Pay-Ins · Pay-Outs · Remittances · Cards"]

    Merchant -- "REST API / Webhooks" --> SIMPAISA
    Consumer -- "Redirect / OTP flows" --> SIMPAISA

    SIMPAISA -. "Compliance reporting" .-> SBP
    SIMPAISA -. "Compliance reporting" .-> BB
    SIMPAISA -. "Compliance reporting" .-> NRB
    SIMPAISA -. "Compliance reporting" .-> CBI

    subgraph "Pakistan — Mobile Wallets"
        EP["Easypaisa"]
        JC["JazzCash"]
        HBL["HBL Konnect"]
        Alfa["Alfa (Bank Alfalah)"]
        Zindagi["JSBL Zindagi"]
    end

    subgraph "Pakistan — DCB"
        Telenor["Telenor DCB"]
        Zong["Zong DCB"]
        Ufone["Ufone DCB"]
    end

    subgraph "Pakistan — Banking Rails"
        OneLink["1Link"]
        RAAST["RAAST (Instant Payments)"]
    end

    subgraph "Bangladesh — Channels"
        bKash["bKash"]
        BRAC["BRAC Bank"]
        Faysal["Faysal Bank"]
        PayMob["PayMob"]
        Prime["Prime Bank"]
        Agrani["Agrani Bank"]
        AamarPay["AamarPay"]
    end

    subgraph "Card Networks"
        Visa["Visa"]
        MC["Mastercard"]
    end

    SIMPAISA --> EP
    SIMPAISA --> JC
    SIMPAISA --> HBL
    SIMPAISA --> Alfa
    SIMPAISA --> Zindagi

    SIMPAISA --> Telenor
    SIMPAISA --> Zong
    SIMPAISA --> Ufone

    SIMPAISA --> OneLink
    SIMPAISA --> RAAST

    SIMPAISA --> bKash
    SIMPAISA --> BRAC
    SIMPAISA --> Faysal
    SIMPAISA --> PayMob
    SIMPAISA --> Prime
    SIMPAISA --> Agrani
    SIMPAISA --> AamarPay

    SIMPAISA --> Visa
    SIMPAISA --> MC

3. Actor Descriptions¶

3.1 Merchants¶

Merchants integrate with Simpaisa via REST APIs to accept payments (Pay-Ins), disburse funds (Pay-Outs), and process remittances. They manage their integration through the Merchant Portal.

Integration: REST API with HMAC-signed requests.
Notifications: Asynchronous webhooks for transaction status updates.
Portal: Self-service dashboard for API keys, transaction monitoring, and reports.

3.2 Consumers¶

End users who interact with Simpaisa indirectly through merchant applications. They authorise payments via OTP, wallet PIN, or card credentials.

3.3 Regulators¶

Each market regulator requires different compliance obligations:

Regulator	Market	Key Requirements
SBP	Pakistan	PSO/PSP licence, transaction reporting, AML/CFT
BB	Bangladesh	MFS regulations, cross-border reporting
NRB	Nepal	Remittance corridor licensing, KYC standards
CBI	Iraq	E-payment regulations, sanctions screening

4. External System Descriptions¶

4.1 Pakistan — Mobile Wallets¶

Channel	Integration Type	Protocols
Easypaisa	Pay-In, Pay-Out	REST API
JazzCash	Pay-In, Pay-Out	REST API
HBL Konnect	Pay-In, Pay-Out	REST API
Alfa	Pay-In	REST API
JSBL Zindagi	Pay-In	REST API

4.2 Pakistan — Direct Carrier Billing¶

Channel	Integration Type	Protocols
Telenor	Pay-In (DCB)	SOAP/XML
Zong	Pay-In (DCB)	REST API
Ufone	Pay-In (DCB)	SOAP/XML

4.3 Pakistan — Banking Rails¶

Channel	Integration Type	Protocols
1Link	Pay-Out (bank transfers)	ISO 8583
RAAST	Pay-Out (instant payments)	ISO 20022

4.4 Bangladesh — Channels¶

Channel	Integration Type	Protocols
bKash	Pay-In, Pay-Out	REST API
BRAC Bank	Pay-Out	REST API
Faysal	Pay-Out	REST API
PayMob	Pay-In	REST API
Prime	Pay-Out	REST API
Agrani	Pay-Out	REST API
AamarPay	Pay-In	REST API

4.5 Card Networks¶

Network	Integration Type	Protocols
Visa	Authorisation, capture, void, refund	ISO 8583, VTS API
Mastercard	Authorisation, capture, void, refund	ISO 8583, MDES

5. Relationship Summary¶

From	To	Relationship
Merchant	Simpaisa	REST API calls, webhook callbacks
Consumer	Simpaisa	OTP/redirect authorisation flows
Simpaisa	Wallet channels	Charge, disburse, status enquiry
Simpaisa	DCB channels	Subscribe, charge, unsubscribe
Simpaisa	Banking rails	Fund transfer, status enquiry
Simpaisa	Card networks	Auth, capture, void, refund, 3DS
Simpaisa	Regulators	Compliance reporting, audit trails

6. Architectural Decision Records¶

Changes to system boundaries require an ADR in /Standards/ADR/.