Payments Service

A multi-provider payments service supporting M-Pesa, Stripe, and PayPal. Merchants interact via a REST API, authenticated with scoped API keys. Payment events are delivered to merchant webhook URLs with HMAC signatures and automatic retries.

Architecture

flowchart TB
    Client["Merchant Client"]
    API["REST API<br/>(FastAPI)"]
    Auth["Auth Middleware<br/>API Key + Scopes + Rate Limit"]
    Service["Payment Service<br/>Idempotency + Routing"]

    subgraph Providers
        Stripe["Stripe<br/>Cards / 3DS"]
        MPesa["M-Pesa<br/>STK Push"]
        PayPal["PayPal<br/>Orders API"]
    end

    subgraph Webhooks
        Inbound["Inbound Handler<br/>Signature Verify + Dedup"]
        Outbox["Outbox Table<br/>(Postgres)"]
        Worker["ARQ Worker<br/>Dispatch + Retry"]
    end

    MerchantURL["Merchant Webhook URL"]
    DB[(PostgreSQL)]
    Redis[(Redis)]

    Client -->|"X-API-Key"| API
    API --> Auth
    Auth --> Service
    Service --> Stripe
    Service --> MPesa
    Service --> PayPal

    Stripe -->|callback| Inbound
    MPesa -->|callback| Inbound
    PayPal -->|callback| Inbound

    Inbound -->|"single DB tx"| DB
    Inbound --> Outbox
    Outbox --> Worker
    Worker -->|"HMAC signed"| MerchantURL

    Auth --> Redis
    Inbound --> Redis

Key Features

Feature	Description
Multi-provider	Stripe, M-Pesa, PayPal through a unified API
Per-merchant credentials	Each merchant configures their own provider keys, encrypted at rest
Scoped API keys	Fine-grained permissions per key
Idempotency	Duplicate payment prevention via Idempotency-Key header
Webhook delivery	HMAC-signed, retried with exponential backoff
Audit logging	Every auth event persisted for compliance
Saved cards	Stripe recurring payments with tokenized card storage
M-Pesa reconciliation	Auto-sync missed callbacks via Pull Transactions API
Transaction history	List and filter transactions by status, provider, currency, amount, date range

Tech Stack

Concern	Choice
Language	Python 3.12+
Framework	FastAPI
ORM	SQLAlchemy 2.0 (async)
Database	PostgreSQL 16
Cache / Queue	Redis 7
Worker	ARQ (async Redis queue)
HTTP Client	httpx + tenacity (retry)
Encryption	Fernet (AES-256)
Docs	Scalar (OpenAPI)