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

# WooCommerce

> Accept mobile money payments in your WooCommerce store with the Simiz plugin.

The Simiz WooCommerce plugin 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

Before installing, make sure your environment meets these requirements:

| Requirement   | Minimum version                              |
| ------------- | -------------------------------------------- |
| WordPress     | 6.0                                          |
| WooCommerce   | 7.0                                          |
| PHP           | 8.1                                          |
| Simiz account | [Create one free](https://simiz.io/register) |

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

## Installation

<Steps>
  <Step title="Download the plugin">
    Download the Simiz for WooCommerce plugin from [WordPress.org](https://wordpress.org/plugins/simiz-woocommerce/) or directly from your [Simiz dashboard](https://dashboard.simiz.io/plugins).

    You'll receive a `.zip` file named `simiz-woocommerce.zip`.
  </Step>

  <Step title="Upload and activate">
    1. Go to your WordPress admin panel
    2. Navigate to **Plugins → Add New → Upload Plugin**
    3. Select the `simiz-woocommerce.zip` file and click **Install Now**
    4. Click **Activate Plugin**

    <Tip>
      You can also install via FTP by uploading the extracted `simiz-woocommerce` folder to `/wp-content/plugins/`.
    </Tip>
  </Step>

  <Step title="Configure the plugin">
    1. Go to **WooCommerce → Settings → Payments**
    2. Find **Simiz Payments** and click **Manage**
    3. Enter your API key and webhook secret
    4. Save your settings

    The plugin is now ready to accept payments.
  </Step>
</Steps>

## Configuration

Navigate to **WooCommerce → Settings → Payments → Simiz Payments** to access all settings.

### General settings

| Setting            | Description                                                      |
| ------------------ | ---------------------------------------------------------------- |
| **Enable/Disable** | Toggle Simiz as a payment method at checkout                     |
| **Title**          | Payment method name shown to customers (default: "Mobile Money") |
| **Description**    | Description shown during checkout                                |

### API credentials

The plugin uses separate credentials for test and live environments:

| Setting                 | Description                                   |
| ----------------------- | --------------------------------------------- |
| **Test Mode**           | Toggle between sandbox and 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             |

<Warning>
  **Never share your API keys publicly.** Store them securely and never commit them to version control.
</Warning>

### Webhook URL

The plugin automatically registers a webhook endpoint at:

```
https://your-store.com/?wc-api=simiz_webhook
```

Copy this URL into your Simiz dashboard under **Settings → Webhooks** to receive payment notifications.

## Payment flow

Here's how a payment works end-to-end:

<Steps>
  <Step title="Customer checks out">
    The customer selects **Mobile Money** as the payment method and chooses their mobile money provider (Orange Money, MTN MoMo, etc.).
  </Step>

  <Step title="Payment is initiated">
    The plugin sends a request to the Simiz API to create a transaction. The customer is redirected to the Simiz checkout page or receives a mobile money prompt on their phone.
  </Step>

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

  <Step title="Webhook confirms the order">
    Simiz sends a `transaction.completed` webhook to your store. The plugin verifies the signature, updates the order status to **Processing**, and sends the confirmation email to the customer.
  </Step>
</Steps>

## Supported payment methods

The plugin exposes the Simiz API Mobile Money methods across the **CEMAC** and **UEMOA** zones
(14 countries). Corridors are **being activated** (Coming soon): live coverage is at
[/coverage](https://simiz.io/coverage) and actual availability per account is in the dashboard.

<CardGroup cols={2}>
  <Card title="Orange Money" icon="mobile">
    `ORANGE_MONEY`
  </Card>

  <Card title="MTN Mobile Money" icon="mobile">
    `MTN_MOMO`
  </Card>
</CardGroup>

<Info>
  More payment methods are added as licensed partners are activated.
</Info>

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

The plugin handles webhook events automatically. When Simiz sends a notification, the plugin:

1. **Verifies the HMAC-SHA256 signature** using your webhook secret
2. **Parses the event** to determine the transaction status
3. **Updates the WooCommerce order** accordingly

### Webhook events

| Event                   | Order action                   |
| ----------------------- | ------------------------------ |
| `transaction.completed` | Order marked as **Processing** |
| `transaction.failed`    | Order marked as **Failed**     |
| `transaction.cancelled` | Order marked as **Cancelled**  |
| `transaction.expired`   | Order marked as **Failed**     |
| `refund.completed`      | Refund recorded on the order   |

<Tip>
  You can test webhook delivery from your Simiz dashboard under **Settings → Webhooks → Send Test Event**.
</Tip>

## Test mode

The plugin supports full sandbox testing so you can verify your integration before going live.

### Switching modes

1. Go to **WooCommerce → Settings → Payments → Simiz Payments**
2. Check or uncheck the **Test Mode** checkbox
3. Save changes

When test mode is enabled, the plugin uses your sandbox API key and no real money is charged.

### Sandbox test numbers

Use these numbers to simulate different payment outcomes:

| Number         | Operator     | Result               |
| -------------- | ------------ | -------------------- |
| `237690000001` | Orange Money | Success              |
| `237670000001` | MTN MoMo     | Success              |
| `237690000002` | Orange Money | Insufficient balance |
| `237690000003` | Orange Money | Timeout              |

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

## Refunds

The plugin supports full and partial refunds from the WooCommerce admin:

1. Open the order in **WooCommerce → Orders**
2. Click **Refund**
3. Enter the refund amount (full or partial)
4. Click **Refund via Simiz**

The refund is processed through the Simiz API and the order is updated automatically.

## WooCommerce Blocks compatibility

The plugin is compatible with the WooCommerce Blocks checkout. No additional configuration is needed — the Simiz payment method appears automatically in both the classic and block-based checkout.

## Troubleshooting

<Tabs>
  <Tab title="Payment not completing">
    **Symptoms:** Order stays in "Pending" status after the customer pays.

    **Solutions:**

    * Verify your webhook URL is correctly configured in the Simiz dashboard
    * Check that your webhook secret matches between WooCommerce and Simiz
    * Ensure your server allows incoming POST requests to the webhook endpoint
    * Check your WordPress error log at `wp-content/debug.log`
  </Tab>

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

    **Solutions:**

    * Confirm the plugin is activated in **Plugins**
    * Verify the gateway is enabled in **WooCommerce → Settings → Payments**
    * Check that your store currency matches a [supported currency](#supported-currencies)
    * Ensure WooCommerce is up to date (>= 7.0)
  </Tab>

  <Tab title="Invalid signature errors">
    **Symptoms:** Webhooks return 401 errors in the Simiz dashboard.

    **Solutions:**

    * Regenerate your webhook secret in the Simiz dashboard
    * Update the new secret in your WooCommerce plugin settings
    * Ensure no caching plugin or CDN is modifying webhook request headers
  </Tab>

  <Tab title="API key errors">
    **Symptoms:** "Invalid API key" error when creating a payment.

    **Solutions:**

    * Verify you are using the correct key for the current mode (test key for sandbox, live key for production)
    * Check that your API key has not been revoked in the Simiz dashboard
    * Make sure there are no extra spaces in the key field
  </Tab>
</Tabs>

## FAQ

<Tabs>
  <Tab title="Do I need a Simiz account?">
    Yes. You need a [Simiz account](https://simiz.io/register) to get your API keys. Creating an account is free.
  </Tab>

  <Tab title="Is KYB required?">
    KYB (Know Your Business) verification is required only for production/live payments. You can test freely in sandbox mode without KYB.
  </Tab>

  <Tab title="Which checkout modes are supported?">
    The plugin supports three checkout modes:

    * **Redirect** — Customer is redirected to the Simiz checkout page
    * **Embedded** — Checkout form embedded in your store
    * **Popup** — Checkout opens in a modal window
  </Tab>

  <Tab title="Can I accept multiple currencies?">
    Yes. The plugin supports all [Simiz currencies](#supported-currencies). Your store's base currency must be one of the supported currencies.
  </Tab>

  <Tab title="How are transaction fees calculated?">
    Transaction fees depend on your Simiz plan. Check your [pricing page](https://simiz.io/pricing) or dashboard for details. No fees apply in sandbox mode.
  </Tab>
</Tabs>

## Next steps

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

  <Card title="Webhook Verification" icon="shield-check" href="/en/core-concepts/webhooks/signature-verification">
    Learn about webhook signature verification.
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference">
    Explore the full Simiz API.
  </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 — Orange Money, MTN MoMo, webhooks, sandbox |
</Accordion>