EasySwitch is a unified Python SDK for Mobile Money integration across major aggregators in West Africa. It provides a single, consistent interface to simplify payment processing, reduce code duplication, and accelerate development.
Integrating different payment providers usually means learning different APIs, handling inconsistent error messages, and rewriting code to switch providers. EasySwitch was created to eliminate this complexity:
- 🚀 Accelerate your integrations
- 🔁 Switch providers without changing your code
- 🧱 Leverage a robust, type-safe, async-first architecture
- 🌍 Support local and international aggregators
- 🔌 Unified API for multiple payment gateways
- ⚙️ Supports configuration from
.env, JSON, YAML, or native Python dict - 🔐 Centralized management of API keys and credentials
- 📈 Fully customizable logging (file, console, rotating, compression)
- 🧩 Extensible via a plugin-like adapter registration system
- ✅ Strong Exception handling
- ✅ Asynchronous support for optimal performance
- ✅ Automatic Retry in case of network failures
You need to have at least 3.13 version of python to be able to continue.
# Uising pip
pip install easyswitch
# Or using uv
uv add easyswitchEasySwitch uses a centralized configuration object to define providers, credentials, default settings, and adapter mappings.
| Source | Description | Example |
|---|---|---|
| Environment Variables | Load configs from a .env file or System Environment |
see example |
| Native Python Dictionary | Direct configuration in your code | see exemple |
| JSON File | Load configs from a JSON file | see example |
| YAML File | Load configs from a YAML file | see example |
# This file is a sample. Copy it to .env and fill in the values.
# General configuration
EASYSWITCH_ENVIRONMENT=sandbox # or production
EASYSWITCH_TIMEOUT=30 # seconds
EASYSWITCH_DEBUG=true # Enable debug mode
# Logging configuration
# Note: Logging configuration is only used if EASYSWITCH_LOGGING is set to true
EASYSWITCH_LOGGING=true # Enable file logging
EASYSWITCH_LOG_LEVEL=info # debug, info, warning, error
EASYSWITCH_LOG_FILE=/var/log/easyswitch.log # Path to the log file
EASYSWITCH_CONSOLE_LOGGING=true # Enable console logging
EASYSWITCH_LOG_MAX_SIZE=10 # Maximum size of the log file in MB
EASYSWITCH_LOG_BACKUPS=5 # Number of backup log files to keep
EASYSWITCH_LOG_COMPRESS=true # Whether to compress old log files
EASYSWITCH_LOG_FORMAT=plain # Format of the log file (plain or json)
EASYSWITCH_LOG_ROTATE=true # Whether to rotate the log file
# Payment gateway configuration
EASYSWITCH_ENABLED_PROVIDERS=cinetpay,semoa # Comma-separated list of enabled payment providers
EASYSWITCH_DEFAULT_PROVIDER=cinetpay # Default payment provider
EASYSWITCH_CURRENCY=XOF # Default currency
# Providers configuration
# NOTE: these are standadized variables for all providers.
# CINETPAY
# Note: Only required if EASYSWITCH_ENABLED_PROVIDERS includes 'cinetpay'
# You don't need to fill in all of these variables. Only fill in the ones you need.
EASYSWITCH_CINETPAY_API_KEY=your_cinetpay_api_key
EASYSWITCH_CINETPAY_X_SECRET=your_cinetpay_secret_key
EASYSWITCH_CINETPAY_X_STIE_ID=your_cinetpay_site_id
EASYSWITCH_CINETPAY_CALLBACK_URL=your_cinetpay_callback_url
EASYSWITCH_CINETPAY_X_CHANNELS=ALL
EASYSWITCH_CINETPAY_X_LANG=fr
# SEMOA
# Note: Only required if EASYSWITCH_ENABLED_PROVIDERS includes 'semoa'
# You don't need to fill in all of these variables. Only fill in the ones you need.
EASYSWITCH_SEMOA_API_KEY=your_semoa_api_key
EASYSWITCH_SEMOA_X_CLIENT_ID=your_semoa_client_id
EASYSWITCH_SEMOA_X_CLIENT_SECRET=your_semoa_client_secret
EASYSWITCH_SEMOA_X_USERNAME=your_semoa_username
EASYSWITCH_SEMOA_X_PASSWORD=your_semoa_password
EASYSWITCH_SEMOA_X_CALLBACK_URL=your_semoa_callback_url # Optionalfrom easyswitch import (
EasySwitch, TransactionDetail, Provider,
TransactionStatus, Currency, TransactionType,
CustomerInfo
)
config = {
"debug": True,
"providers": {
Provider.CINETPAY: {
"api_key": "your_api_key",
"base_url": "https://api.exemple.com/v1", # Optional
"callback_url": "https://api.exemple.com/v1/callback",
"return_url": "https://api.exemple.com/v1/return",
"environment": "production", # Optional sandbox by default
"extra": {
"secret": "your_secret",
"site_id": "your_site_id",
"channels": "ALL", # More details on Cinetpay's documentation.
"lang": "fr" # More details on Cinetpay's documentation.
}
},
Provider.BIZAO: {
"api_key": "your_api_key",
"base_url": "https://api.exemple.com/v1", # Optional
"callback_url": "https://api.exemple.com/v1/callback",
"return_url": "https://api.exemple.com/v1/return",
"environment": "production", # Optional sandbox by default
"timeout":30,
"extra": {
# Dev Configs
"dev_client_id": "your_dev_client_id",
"dev_client_secret": "your_dev_client_secret",
"dev_token_url": "https://your_dev_token_url.com",
# Prod Configs
"prod_client_id": "your_prod_client_id",
"prod_client_secret": "your_prod_client_secret",
"prod_token_url": "https://your_dev_token_url.com",
# Global configs
"country-code": Countries.IVORY_COAST,
"mno-name": "orange",
"channel": "web",
"lang": "fr",
"cancel_url": "https/example.com/cancel"
}
},
}
}
client = EasySwitch.from_dict(config)client = EasySwitch.from_json("config.json")client = EasySwitch.from_yaml("config.yaml")Adapters are pluggable classes that implement the logic for each payment aggregator. They provide standardized methods (send_payment, check_status, refund, etc.).
from easyswitch import EasySwitch
# 1. From environment variables
client = EasySwitch.from_env()
# 2. From a JSON file
client = EasySwitch.from_json("config.json")
# 3. from a Python dict
config = {
"providers": {
Provider.CINETPAY: {
"api_key": "your_api_key",
"base_url": "https://api.exemple.com/v1", # Optional
"callback_url": "https://api.exemple.com/v1/callback",
"return_url": "https://api.exemple.com/v1/return",
"environment": "production" # Optional sandbox by default
"extra": {
"secret": "your_secret",
"site_id": "your_site_id",
"channels": "ALL" # More details on Cinetpay's documentation.
"lang": "fr" # More details on Cinetpay's documentation.
}
}
}
}
client = EasySwitch.from_dict(config)
# 4. Merging multiple sources
client = EasySwitch.from_multi_sources(
env_file=".env", # Main config
json_file="overrides.json" # Overrides
)
# 5. Direct usage with RootConfig
from easyswitch.conf.base import RootConfig
config = RootConfig(...)
client = EasySwitch.from_config(config)from easyswitch import (
EasySwitch, TransactionDetail, Provider,
TransactionStatus, Currency, TransactionType,
CustomerInfo
)
# Creating a Transaction
t = TransactionDetail(
transaction_id = 'xveahdk-82998n9f8uhgj',
provider = Provider.CINETPAY,
status = TransactionStatus.PENDING, # Default value
currency = Currency.XOF,
amount = 150,
transaction_type = TransactionType.PAYMENT, # Default value
reason = 'My First Transaction Test with EasySwitch\'s CinetPay client.',
reference = 'my_ref',
customer = CustomerInfo(
phone_number = '+22890000000',
first_name = 'Wil',
last_name = 'Eins',
address = '123 Rue képui, Lomé', # Optional
city = 'Lomé', # Optional
)
)# Initializing Payment
res = client.send_payment(t) # Will send payment request to CinetPay
print(res)
'''
PaymentResponse(
transaction_id = 'xveahdk-82998n9f8uhgj',
provider = 'cinetpay',
status = <TransactionStatus.PENDING: 'pending'>,
amount = 150, currency=<Currency.XOF: 'XOF'>,
created_at = datetime.datetime(2025, 5, 13, 16, 43, 19, 193307),
expires_at = None,
reference = 'my_ref',
payment_link = 'https://checkout.cinetpay.com/payment/d6a902e9b398bbbf6f600ca0ac9df8d86d865dd73157a0b2f7c67c877361b1f880d16ee44404e8a0744cf57ad85f89f56f06ae9037fb5d',
transaction_token = 'd6a902e9b398bbbf6f600ca0ac9df8d86d865dd73157a0b2f7c67c877361b1f880d16ee44404e8a0744cf57ad85f89f56f06ae9037fb5d',
customer = CustomerInfo(
phone_number = '+22890000000',
first_name = 'Wil',
last_name = 'Eins',
email = None,
address = '123 Rue képui, Lomé',
city = 'Lomé',
country = None,
postal_code = None,
zip_code = None,
state = None,
id = None
),
raw_response = {
'code': '201',
'message': 'CREATED',
'description': 'Transaction created with success',
'data': {
'payment_token': 'd6a902e9b398bbbf6f600ca0ac9df8d86d865dd73157a0b2f7c67c877361b1f880d16ee44404e8a0744cf57ad85f89f56f06ae9037fb5d',
'payment_url': 'https://checkout.cinetpay.com/payment/d6a902e9b398bbbf6f600ca0ac9df8d86d865dd73157a0b2f7c67c877361b1f880d16ee44404e8a0744cf57ad85f89f56f06ae9037fb5d'
},
'api_response_id': '1747154599.4854'
},
metadata = {}
)
'''res = client.check_status(
t.id, # Transaction ID
Provider.CINETPAY # Optional default to default provider
)# Validate a webhook
is_valid = client.validate_webhook(
provider = Provider.CINETPAY,
payload = request.body,
headers = request.headers
)
# Parse a Webhook
event = client.parse_webhook(
provider = Provider.CINETPAY,
payload = request.body,
headers = request.headers
)EasySwitch is still under heavy maintenance, we decided to ship it in this early stage so you can help us make it better.
Add Support for following Providers:
- Cinetpay
- Bizao
- Semoa
- PayGate
- Fedapay
- Kkiapay
- MTN
- Orange
- PayPlus
- QOSPAY
- Paydunya
MIT License.
For any question, please open a Github issue.
We welcome contributions from the community! Please see the CONTRIBUTING.md guide for more information.
🚀 Simplify your payment integrations with EasySwitch ! 🚀
Made with ❤️ By AllDotPy