EasySwitch SDK Documentation¶

Unified Python SDK for Mobile Money & Payment Gateways across Africa

What is EasySwitch?¶

EasySwitch is a unified Python SDK that standardises 8+ payment providers behind a single, clean interface. Instead of learning and maintaining separate integrations for each provider, you write your payment logic once and switch providers with a single configuration change.

from easyswitch import EasySwitch, Provider

# One client, any provider
client = EasySwitch.from_env()

# Same method works for every provider
response = client.send_payment(transaction)

Quick Start¶

from easyswitch import (
    EasySwitch, TransactionDetail, Currency,
    TransactionType, CustomerInfo, Provider,
)

# 1. Initialise from environment variables
client = EasySwitch.from_env()

# 2. Create a transaction
order = TransactionDetail(
    transaction_id="order-001",
    provider=Provider.CINETPAY,
    amount=1500.00,
    currency=Currency.XOF,
    customer=CustomerInfo(
        phone_number="+22890123456",
        first_name="John",
        last_name="Doe",
    ),
    reason="Test payment via EasySwitch",
)

# 3. Send payment
response = client.send_payment(order)

# 4. Check result
print(f"Status: {response.status}")
print(f"Payment link: {response.payment_link}")

Provider Ecosystem¶

CinetPay

Checkout page, cards & Mobile Money
West Africa (UEMOA)

→ Guide
PayGate

Direct API + Payment links
Togo (FLOOZ, TMONEY)

→ Guide
FedaPay

Cards & Mobile Money
8+ African countries

→ Guide
Paystack

Cards, USSD, Bank Transfer
Nigeria, Ghana

→ Guide
MTN MoMo

USSD push (async)
17 African countries

→ Guide
Airtel Money

USSD push (async)
15+ African countries

→ Guide
Semoa

API payments
West Africa

→ Guide
Bizao

Web, USSD, TPE channels
West & Central Africa

→ Guide

→ Compare all providers

Core Concepts¶

Unified Transaction Model¶

Every provider accepts and returns the same data types:

Concept	EasySwitch Type	Description
Transaction	`TransactionDetail`	What you send to request a payment
Payment Result	`PaymentResponse`	What you get back after sending
Status Check	`TransactionStatusResponse`	Status & amount after verification
Webhook Event	`WebhookEvent`	Normalised event from provider callbacks
Customer	`CustomerInfo`	Customer details (name, phone, email)

Configuration Sources¶

# Dict (inline)
client = EasySwitch.from_dict({...})

# Environment / .env
client = EasySwitch.from_env()

# JSON file
client = EasySwitch.from_json("config.json")

# YAML file
client = EasySwitch.from_yaml("config.yaml")

# Multi-source (with overrides)
client = EasySwitch.from_multi_sources(
    env_file=".env",
    json_file="overrides.json",
)

Common Operations¶

Method	Purpose	Works With
`send_payment(tx)`	Initiate a payment	All providers
`check_status(id)`	Check transaction status	All providers
`get_transaction_detail(id)`	Full transaction details	Paystack, FedaPay, MTN, Airtel
`refund(id, amount)`	Full or partial refund	Paystack, MTN, Airtel
`validate_webhook(payload, headers)`	Verify webhook signature	Most providers
`parse_webhook(payload, headers)`	Parse webhook into WebhookEvent	Most providers

Next Steps¶

Step	Resource
Install the SDK	Installation Guide
Configure providers	Configuration Guide
Pick a provider	Provider Feature Matrix
Read provider guides	CinetPay · PayGate · FedaPay · Paystack · MTN · Airtel · Semoa · Bizao
API reference	Shared Types · Config Types · Exceptions
Contribute	Contributing Guide