The Simiz Django package provides a batteries-included way to integrate mobile money payments into your Django application. It includes models for tracking transactions, URL routing for webhooks, and a clean Python API for creating payments.

Prerequisites

RequirementMinimum version
Django4.2
Python3.10
Simiz accountCreate one free
You need your Simiz API keys before configuring the package. Find them in Dashboard > Settings > API Keys.

Installation

1

Install the package

pip install simiz-django
2

Add to INSTALLED_APPS

# settings.py
INSTALLED_APPS = [
    # ...
    'simiz_django',
]
3

Include URLs

# urls.py
from django.urls import path, include

urlpatterns = [
    # ...
    path('simiz/', include('simiz_django.urls')),
]
This registers the webhook endpoint at /simiz/webhook/.
4

Configure settings

Add the following to your Django settings:
# settings.py
SIMIZ_API_KEY = os.environ.get('SIMIZ_API_KEY')
SIMIZ_ENVIRONMENT = os.environ.get('SIMIZ_ENVIRONMENT', 'sandbox')
SIMIZ_WEBHOOK_SECRET = os.environ.get('SIMIZ_WEBHOOK_SECRET')
5

Run migrations

python manage.py migrate simiz_django
This creates the SimizTransaction model for tracking payment records.

Configuration

SettingDescription
SIMIZ_API_KEYYour API key (smz_test_* or smz_live_*)
SIMIZ_ENVIRONMENTsandbox or production
SIMIZ_WEBHOOK_SECRETWebhook signing secret
SIMIZ_CURRENCYDefault currency code (optional, default: XAF)

Usage

Creating a transaction

from simiz_django.client import SimizClient

client = SimizClient()

transaction = client.create_transaction(
    amount=5000,
    currency='XAF',
    phone_number='237690000001',
    provider='orange_money',
    description='Order #1234',
    metadata={'order_id': 1234},
)

# Redirect to checkout
return redirect(transaction['checkout_url'])

Checking transaction status

transaction = client.get_transaction('txn_xxxxxxxxxxxx')

if transaction['status'] == 'completed':
    # Payment successful
    pass

Processing refunds

refund = client.create_refund(
    transaction_id='txn_xxxxxxxxxxxx',
    amount=2500,
    reason='Customer request',
)

Webhook handling

The package automatically handles webhook signature verification. Create a signal receiver to process events:
# signals.py
from django.dispatch import receiver
from simiz_django.signals import webhook_received

@receiver(webhook_received)
def handle_simiz_webhook(sender, event, payload, **kwargs):
    if event == 'transaction.completed':
        order_id = payload['metadata']['order_id']
        # Mark order as paid

    elif event == 'transaction.failed':
        # Handle failure

    elif event == 'refund.completed':
        # Handle refund

SimizTransaction model

The package includes a SimizTransaction model that automatically records all transactions:
from simiz_django.models import SimizTransaction

# Query transactions
completed = SimizTransaction.objects.filter(status='completed')
recent = SimizTransaction.objects.order_by('-created_at')[:10]

Supported payment methods

MethodTypeStatus
Orange MoneyMobile MoneyAvailable
MTN Mobile MoneyMobile MoneyAvailable
WaveMobile MoneyComing Soon
Moov MoneyMobile MoneyComing Soon
Airtel MoneyMobile MoneyComing Soon
M-PesaMobile MoneyComing Soon

Supported currencies

CurrencyCodeCountries
Central African CFA FrancXAFCameroon, Central African Republic, Chad, Congo, Equatorial Guinea, Gabon
West African CFA FrancXOFBenin, Burkina Faso, Ivory Coast, Guinea-Bissau, Mali, Niger, Senegal, Togo
Ghanaian CediGHSGhana
Nigerian NairaNGNNigeria
Kenyan ShillingKESKenya
Ugandan ShillingUGXUganda
Rwandan FrancRWFRwanda
Tanzanian ShillingTZSTanzania

Webhook events

EventDescription
transaction.createdTransaction initiated
transaction.processingBeing processed by the provider
transaction.completedPayment successful
transaction.failedPayment failed
transaction.cancelledCancelled by customer
transaction.expiredPayment window expired
refund.createdRefund initiated
refund.completedRefund completed
refund.failedRefund failed

Test mode

Set the following environment variables:
export SIMIZ_API_KEY=smz_test_xxxxxxxxxxxx
export SIMIZ_ENVIRONMENT=sandbox
The package connects to sandbox.api.simiz.io and no real money is charged.

Full sandbox documentation

See all test numbers and scenarios in the Sandbox Testing guide.

Troubleshooting

Solutions:
  • Verify SIMIZ_WEBHOOK_SECRET in your settings
  • Ensure the webhook URL is /simiz/webhook/ (with trailing slash)
  • Add the webhook endpoint to CSRF_EXEMPT_URLS or use the @csrf_exempt decorator

Next steps

Webhook Verification

Learn about webhook configuration and signature verification.

API Reference

Explore the full Simiz API.

Sandbox Testing

Test all payment scenarios before going live.

Support

Need help? Contact our support team.

Changelog

Version history

VersionDateChanges
1.0.02026-03-01Initial release — mobile money payments, webhooks, sandbox