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

# Drupal Commerce

> Accept mobile money payments in your Drupal Commerce store with the Simiz payment gateway.

The Simiz Drupal Commerce module lets you accept mobile money payments directly in your online store. Customers pay via Orange Money, MTN MoMo, and other mobile wallets — with automatic order updates through webhooks.

## Prerequisites

| Requirement   | Minimum version                              |
| ------------- | -------------------------------------------- |
| Drupal        | 9.0                                          |
| Commerce      | 2.0                                          |
| PHP           | 8.1                                          |
| Composer      | 2.x                                          |
| Simiz account | [Create one free](https://simiz.io/register) |

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

## Installation

<Steps>
  <Step title="Install via Composer">
    ```bash
    composer require simiz/drupal-payment
    ```
  </Step>

  <Step title="Enable the module">
    ```bash
    drush en simiz_payment -y
    drush cr
    ```

    Or enable it through the admin UI at **Extend** and check **Simiz Payment**.
  </Step>

  <Step title="Configure the payment gateway">
    1. Go to **Commerce > Configuration > Payment gateways**
    2. Click **Add payment gateway**
    3. Select **Simiz Payments** as the plugin
    4. Enter your API key and webhook secret
    5. Select the mode (Test or Live)
    6. Save
  </Step>
</Steps>

## Configuration

### Payment gateway settings

| Setting            | Description                                                      |
| ------------------ | ---------------------------------------------------------------- |
| **Display name**   | Payment method name shown to customers (default: "Mobile Money") |
| **Mode**           | Test (Sandbox) or Live (Production)                              |
| **API Key**        | Your Simiz API key for the selected mode                         |
| **Webhook Secret** | Webhook signing secret from the Simiz dashboard                  |

### Webhook URL

The module registers a webhook endpoint at:

```
https://your-store.com/simiz/webhook
```

Copy this URL into your Simiz dashboard under **Settings > Webhooks**.

## Payment flow

<Steps>
  <Step title="Customer checks out">
    The customer selects **Mobile Money** at checkout and chooses their provider.
  </Step>

  <Step title="Payment is initiated">
    The module creates a transaction via the Simiz API. The customer is redirected to the Simiz checkout page.
  </Step>

  <Step title="Customer confirms payment">
    The customer confirms the payment by entering their mobile money PIN.
  </Step>

  <Step title="Webhook confirms the order">
    Simiz sends a `transaction.completed` webhook. The module verifies the signature and completes the order.
  </Step>
</Steps>

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

## Webhooks

| Event                   | Order action                        |
| ----------------------- | ----------------------------------- |
| `transaction.created`   | Order created with **Draft** status |
| `transaction.completed` | Order marked as **Completed**       |
| `transaction.failed`    | Order marked as **Cancelled**       |
| `transaction.cancelled` | Order marked as **Cancelled**       |
| `transaction.expired`   | Order marked as **Cancelled**       |
| `refund.created`        | Refund initiated                    |
| `refund.completed`      | Refund recorded on the order        |
| `refund.failed`         | Log entry created                   |

## Test mode

1. Go to **Commerce > Configuration > Payment gateways**
2. Edit your Simiz gateway and set the mode to **Test**
3. Enter your sandbox API key (`smz_test_*`)
4. Save

The module 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="Payment not completing">
    **Solutions:**

    * Verify your webhook URL in the Simiz dashboard
    * Check that your webhook secret matches
    * Ensure your server allows incoming POST requests
    * Check Drupal logs at **Reports > Recent log messages**
  </Tab>

  <Tab title="Module not appearing">
    **Solutions:**

    * Confirm Commerce module is installed and enabled
    * Run `drush cr` to clear caches
    * Ensure Drupal 9+ and Commerce 2+ are installed
  </Tab>

  <Tab title="Composer installation fails">
    **Solutions:**

    * Ensure PHP 8.1+ is installed
    * Run `composer update` to resolve dependency conflicts
    * Check that Drupal Commerce is already installed
  </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>