Django - Simiz Docs

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

Requirement	Minimum version
Django	4.2
Python	3.10
Simiz account	Create one free

You need your Simiz API keys before configuring the package. Find them in Dashboard > Settings > API Keys.

Installation

Install the package

pip install simiz-django

Add to INSTALLED_APPS

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

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/.

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')

Run migrations

python manage.py migrate simiz_django

This creates the SimizTransaction model for tracking payment records.

Configuration

Setting	Description
`SIMIZ_API_KEY`	Your API key (`smz_test_` or `smz_live_`)
`SIMIZ_ENVIRONMENT`	`sandbox` or `production`
`SIMIZ_WEBHOOK_SECRET`	Webhook signing secret
`SIMIZ_CURRENCY`	Default 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

Method	Type	Status
Orange Money	Mobile Money	Available
MTN Mobile Money	Mobile Money	Available
Wave	Mobile Money	Coming Soon
Moov Money	Mobile Money	Coming Soon

Supported currencies

Currency	Code	Countries
Central African CFA Franc	XAF	Cameroon, Central African Republic, Chad, Congo, Equatorial Guinea, Gabon
West African CFA Franc	XOF	Benin, Burkina Faso, Ivory Coast, Guinea-Bissau, Mali, Niger, Senegal, Togo

Webhook events

Event	Description
`transaction.created`	Transaction initiated
`transaction.completed`	Payment successful
`transaction.failed`	Payment failed
`transaction.cancelled`	Cancelled by customer
`transaction.expired`	Payment window expired
`refund.created`	Refund initiated
`refund.completed`	Refund completed
`refund.failed`	Refund 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

Webhook signature invalid
Migration errors
API key errors

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

Solutions:

Ensure simiz_django is in INSTALLED_APPS
Run python manage.py makemigrations simiz_django if needed
Verify database connection settings

Solutions:

Verify SIMIZ_API_KEY is set in your settings or environment
Ensure you are using the correct key for the environment
Check that the key has not been revoked

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

Version	Date	Changes
`1.0.0`	2026-03-01	Initial release — mobile money payments, webhooks, sandbox

​Prerequisites

​Installation

​Configuration

​Usage

​Creating a transaction

​Checking transaction status

​Processing refunds

​Webhook handling

​SimizTransaction model

​Supported payment methods

​Supported currencies

​Webhook events

​Test mode

Full sandbox documentation

​Troubleshooting

​Next steps

Webhook Verification

API Reference

Sandbox Testing

Support

​Changelog

Prerequisites

Installation

Configuration

Usage

Creating a transaction

Checking transaction status

Processing refunds

Webhook handling

SimizTransaction model

Supported payment methods

Supported currencies

Webhook events

Test mode

Troubleshooting

Next steps

Changelog