Skip to content
Zirzir

What is Zirzir?

Zirzir is an open-source payment gateway orchestrator for Africa.

Not just an SDK. Not just a wrapper around gateway APIs. A full payment infrastructure — the kind that used to take a funded fintech company 18 months and a team of engineers to build. Open-sourced, self-hostable, and designed from the ground up for the African payment landscape.

🏛️ System Architecture

Section titled “🏛️ System Architecture”
graph TB
    subgraph Clients["Client Layer"]
        SDK[Unified SDKs<br/>TypeScript & Python]
        Checkout[<zirzir-checkout><br/>Web Component]
        Links[Hosted Payment Links<br/>/l/:id]
        CLI[Developer CLI<br/>zirzir charge / sub]
        MCP[AI Agents<br/>Cursor / Claude / Antigravity]
    end


    subgraph CoreEngine["⚡ Zirzir High-Performance Core (Rust Axum 0.7)"]
        Router[Smart Routing & Circuit Breakers]
        Idempotency[Double-Charge Idempotency Shield]
        Dunning[Subscriptions & Smart Dunning Loop]
        Ledger[(SQLite WAL Ledger & Postgres)]
        Metrics[Prometheus Exporter /metrics]
    end


    subgraph Rails["Payment Rails & Gateways"]
        Telebirr[📱 Telebirr<br/>RSA-2048 PKCS#1 v1.5]
        Chapa[💳 Chapa<br/>Multi-Bank Aggregator]
        Santim[💳 SantimPay<br/>Awash & Dashen Rails]
        Arif[💳 Arifpay<br/>Omnichannel Gateway]
        Mpesa[📱 Safaricom M-Pesa<br/>Daraja STK Push]
        CBE[🏛️ CBE Birr<br/>USSD *847# Intent]
    end


    Clients --> Router
    Router --> Idempotency
    Idempotency --> Dunning
    Dunning --> Ledger
    Router --> Metrics


    Idempotency --> Telebirr
    Idempotency --> Chapa
    Idempotency --> Santim
    Idempotency --> Arif
    Idempotency --> Mpesa
    Idempotency --> CBE


    style CoreEngine fill:#0f172a,stroke:#10b981,stroke-width:2px,color:#fff
    style Rails fill:#1e293b,stroke:#f59e0b,stroke-width:2px,color:#fff
    style Clients fill:#1e293b,stroke:#38bdf8,stroke-width:2px,color:#fff

The Problem

Section titled “The Problem”

Africa has a payment fragmentation problem unlike anywhere else in the world.

Each country has its own gateways. Each gateway has its own API, its own auth flow, its own webhook format, its own error codes, its own quirks. Integrating Telebirr in Ethiopia is a completely different experience from integrating M-Pesa in Kenya, which is completely different from integrating Paystack in Nigeria.

When you’re building a payment-enabled product in Africa, you don’t just need integration code. You need to:

  • Manage API credentials for each provider separately
  • Build your own webhook infrastructure (with retries, deduplication, HMAC signature verification)
  • Build your own transaction ledger and double-charge protection (Idempotency keys)
  • Build dashboards for your finance team to see real-time transactions
  • Handle circuit breakers and automatic failover when a mobile money network drops
  • Support offline customers with USSD dial intents

Every company building in African fintech solves these problems independently. Expensively. Repeatedly. That’s what Zirzir replaces.

What Zirzir Actually Is

Section titled “What Zirzir Actually Is”

Zirzir consists of three core components that work together:

1. Unified SDKs (Open Source)

Section titled “1. Unified SDKs (Open Source)”

A unified, provider-agnostic SDK available in TypeScript (@zirzir/sdk) and Python (zirzir). One interface for every supported gateway.

// Works seamlessly regardless of the underlying payment rail
const tx = await zirzir.charge({
  provider: 'telebirr',
  amount: 500,
  currency: 'ETB',
  phone: '0911223344',
  txRef: 'order_001',
}, { idempotencyKey: '7b9a-4f12-88ef' });

2. High-Performance Server Engine (Rust)

Section titled “2. High-Performance Server Engine (Rust)”

A lightweight, sub-millisecond Rust server (built with Axum 0.7 & SQLite WAL ledger) that acts as the operational backbone of your financial stack.

Core Capabilities:

  • Smart Routing & Circuit Breakers: Automatically detects degraded providers and reroutes payments to healthy fallback rails.
  • Double-Charge Protection: Idempotency key caching prevents double-billing on mobile network drops.
  • Subscriptions & Smart Dunning: Purpose-built recurring billing engine for African mobile wallets with automated renewal STK pushes.
  • Hosted Payment Links: Generate no-code shareable payment URLs (/l/:id) for WhatsApp, SMS, and invoices.
  • Full-Stack Bun & React Plugins: Extend gateways and dashboard views dynamically without recompiling the server.
  • Prometheus Telemetry: Native /metrics endpoint for Grafana monitoring.
  • AI Agent MCP Server: Built-in Model Context Protocol server (zirzir mcp) and dashboard Financial Copilot.

Get Started

Section titled “Get Started”