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

# Magento 2

> Accept mobile money payments in your Magento 2 store with the Simiz payment module.

The Simiz Magento 2 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                              |
| ------------- | -------------------------------------------- |
| Magento       | 2.4                                          |
| 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">
    Run the following command in your Magento root directory:

    ```bash
    composer require simiz/magento-payment
    ```
  </Step>

  <Step title="Enable the module">
    ```bash
    bin/magento module:enable Simiz_Payment
    bin/magento setup:upgrade
    bin/magento setup:di:compile
    bin/magento cache:flush
    ```
  </Step>

  <Step title="Configure the module">
    1. Go to **Stores > Configuration > Sales > Payment Methods**
    2. Expand the **Simiz Payments** section
    3. Enter your API key and webhook secret
    4. Select your environment (Sandbox or Production)
    5. Save the configuration
    6. Flush the cache: `bin/magento cache:flush`
  </Step>
</Steps>

## Configuration

Navigate to **Stores > Configuration > Sales > Payment Methods > Simiz Payments**.

### General settings

| Setting         | Description                                                      |
| --------------- | ---------------------------------------------------------------- |
| **Enabled**     | Enable or disable Simiz as a payment method                      |
| **Title**       | Payment method name shown to customers (default: "Mobile Money") |
| **Description** | Description shown during checkout                                |
| **Sort Order**  | Display order among payment methods                              |

### API credentials

| Setting                 | Description                                   |
| ----------------------- | --------------------------------------------- |
| **Environment**         | Sandbox or Production                         |
| **Test API Key**        | Your sandbox key (`smz_test_xxxxxxxxxxxx`)    |
| **Test Webhook Secret** | Sandbox webhook signing secret                |
| **Live API Key**        | Your production key (`smz_live_xxxxxxxxxxxx`) |
| **Live Webhook Secret** | Production webhook signing secret             |

### Webhook URL

The module registers a webhook endpoint at:

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

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, creates an invoice, and updates the order status to **Processing**.
  </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 **Pending Payment** status   |
| `transaction.completed` | Order marked as **Processing**, invoice created |
| `transaction.failed`    | Order marked as **Cancelled**                   |
| `transaction.cancelled` | Order marked as **Cancelled**                   |
| `transaction.expired`   | Order marked as **Cancelled**                   |
| `refund.created`        | Refund initiated                                |
| `refund.completed`      | Credit memo created                             |
| `refund.failed`         | Comment added to order                          |

## Test mode

1. Go to **Stores > Configuration > Sales > Payment Methods > Simiz Payments**
2. Set the environment to **Sandbox**
3. Enter your sandbox API key (`smz_test_*`)
4. Save and flush the cache

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">
    **Symptoms:** Order stays in "Pending Payment" after the customer pays.

    **Solutions:**

    * Verify your webhook URL is correctly configured in the Simiz dashboard
    * Check that your webhook secret matches
    * Ensure your server allows incoming POST requests
    * Check Magento logs in `var/log/simiz.log`
  </Tab>

  <Tab title="Module not appearing at checkout">
    **Symptoms:** Simiz is not shown as a payment option.

    **Solutions:**

    * Confirm the module is enabled: `bin/magento module:status Simiz_Payment`
    * Verify the payment method is enabled in configuration
    * Check that your store currency is supported
    * Run `bin/magento setup:di:compile` and flush the cache
  </Tab>

  <Tab title="Composer installation fails">
    **Symptoms:** `composer require` fails with dependency errors.

    **Solutions:**

    * Ensure Magento 2.4+ and PHP 8.1+ are installed
    * Run `composer update` to resolve dependency conflicts
    * Check that your Composer authentication is configured
  </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>