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

# Shopify

> Accept mobile money payments in your Shopify store with the Simiz payment app.

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

## Prerequisites

| Requirement   | Details                                      |
| ------------- | -------------------------------------------- |
| Shopify store | Any Shopify plan                             |
| Node.js       | >= 18 (for custom app development)           |
| Simiz account | [Create one free](https://simiz.io/register) |

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

## Installation

<Steps>
  <Step title="Install from Shopify App Store">
    1. Visit the [Simiz Payments app](https://apps.shopify.com/simiz-payments) on the Shopify App Store
    2. Click **Add app**
    3. Review the required permissions and click **Install app**
  </Step>

  <Step title="Connect your Simiz account">
    1. After installation, you will be redirected to the Simiz configuration page
    2. Enter your Simiz API key (`smz_test_*` for sandbox, `smz_live_*` for production)
    3. Enter your webhook secret
    4. Click **Save**
  </Step>

  <Step title="Activate the payment method">
    1. Go to **Settings > Payments** in your Shopify admin
    2. Find **Simiz Payments** under Additional payment methods
    3. Click **Activate**

    The app is now ready to accept payments at checkout.
  </Step>
</Steps>

## Configuration

### App settings

Access settings from **Apps > Simiz Payments** in your Shopify admin.

| Setting                  | Description                                                   |
| ------------------------ | ------------------------------------------------------------- |
| **Environment**          | Toggle between Sandbox and Production                         |
| **API Key**              | Your Simiz API key for the selected environment               |
| **Webhook Secret**       | Webhook signing secret from the Simiz dashboard               |
| **Payment method title** | Name shown to customers at checkout (default: "Mobile Money") |
| **Checkout mode**        | Redirect or Embedded checkout                                 |

### Checkout extension

The app integrates with Shopify's checkout extensibility framework. It adds a payment option that appears alongside other payment methods during checkout.

No additional theme modifications are required. The payment method renders automatically in both classic and checkout extensibility themes.

## Payment flow

<Steps>
  <Step title="Customer checks out">
    The customer selects **Mobile Money** as the payment method during Shopify checkout.
  </Step>

  <Step title="Payment is initiated">
    The app creates a transaction via the Simiz API. The customer is redirected to the Simiz checkout page to enter their phone number and select their provider.
  </Step>

  <Step title="Customer confirms payment">
    The customer receives a prompt on their phone and confirms the payment with their mobile money PIN.
  </Step>

  <Step title="Order is confirmed">
    Simiz sends a `transaction.completed` webhook. The app verifies the signature, marks the Shopify order as **Paid**, and the customer sees the order confirmation page.
  </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

The app handles webhook events automatically:

| Event                   | Order action                                  |
| ----------------------- | --------------------------------------------- |
| `transaction.created`   | Order created with **Payment pending** status |
| `transaction.completed` | Order marked as **Paid**                      |
| `transaction.failed`    | Order marked as **Failed**                    |
| `transaction.cancelled` | Order marked as **Cancelled**                 |
| `transaction.expired`   | Order marked as **Failed**                    |
| `refund.created`        | Refund initiated                              |
| `refund.completed`      | Refund recorded on the order                  |
| `refund.failed`         | Note added to the order                       |

<Tip>
  Webhook URLs are automatically configured during app installation. No manual setup is required.
</Tip>

## Test mode

1. Open the Simiz app in your Shopify admin
2. Set the environment to **Sandbox**
3. Enter your sandbox API key (`smz_test_*`)
4. Save changes

The app 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 "Payment pending" after the customer pays.

    **Solutions:**

    * Verify the app is properly connected to your Simiz account
    * Check that your webhook secret is correct
    * Review webhook delivery logs in the Simiz dashboard
  </Tab>

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

    **Solutions:**

    * Confirm the payment method is activated in **Settings > Payments**
    * Check that your store currency matches a supported currency
    * Ensure the app is installed and not in a suspended state
  </Tab>

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

    **Solutions:**

    * Verify you are using the correct key for the current mode
    * Check that your API key has not been revoked
    * Make sure there are no extra spaces in the key field
  </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>