> ## Documentation Index
> Fetch the complete documentation index at: /llms.txt
> Use this file to discover all available pages before exploring further.

# Django

> Accept mobile money payments in your Django application with the Simiz Python package.

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](https://simiz.io/register) |

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

## Installation

<Steps>
  <Step title="Install the package">
    ```bash
    pip install simiz-django
    ```
  </Step>

  <Step title="Add to INSTALLED_APPS">
    ```python
    # settings.py
    INSTALLED_APPS = [
        # ...
        'simiz_django',
    ]
    ```
  </Step>

  <Step title="Include URLs">
    ```python
    # urls.py
    from django.urls import path, include

    urlpatterns = [
        # ...
        path('simiz/', include('simiz_django.urls')),
    ]
    ```

    This registers the webhook endpoint at `/simiz/webhook/`.
  </Step>

  <Step title="Configure settings">
    Add the following to your Django settings:

    ```python
    # 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')
    ```
  </Step>

  <Step title="Run migrations">
    ```bash
    python manage.py migrate simiz_django
    ```

    This creates the `SimizTransaction` model for tracking payment records.
  </Step>
</Steps>

## 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

```python
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

```python
transaction = client.get_transaction('txn_xxxxxxxxxxxx')

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

### Processing refunds

```python
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:

```python
# 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:

```python
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:

```bash
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.

<Card title="Full sandbox documentation" icon="flask" href="/en/guides/sandbox-testing">
  See all test numbers and scenarios in the Sandbox Testing guide.
</Card>

## Troubleshooting

<Tabs>
  <Tab title="Webhook signature invalid">
    **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
  </Tab>

  <Tab title="Migration errors">
    **Solutions:**

    * Ensure `simiz_django` is in `INSTALLED_APPS`
    * Run `python manage.py makemigrations simiz_django` if needed
    * Verify database connection settings
  </Tab>

  <Tab title="API key errors">
    **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
  </Tab>
</Tabs>

## Next steps

<CardGroup cols={2}>
  <Card title="Webhook Verification" icon="shield-check" href="/en/core-concepts/webhooks/overview">
    Learn about webhook configuration and signature verification.
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference">
    Explore the full Simiz API.
  </Card>

  <Card title="Sandbox Testing" icon="flask" href="/en/guides/sandbox-testing">
    Test all payment scenarios before going live.
  </Card>

  <Card title="Support" icon="headset" href="https://support.simiz.io">
    Need help? Contact our support team.
  </Card>
</CardGroup>

## Changelog

<Accordion title="Version history" defaultOpen>
  | Version | Date       | Changes                                                    |
  | ------- | ---------- | ---------------------------------------------------------- |
  | `1.0.0` | 2026-03-01 | Initial release — mobile money payments, webhooks, sandbox |
</Accordion>