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

# Ruby on Rails

> Accept mobile money payments in your Rails application with the Simiz gem.

The Simiz Rails gem provides an idiomatic Ruby integration for mobile money payments. It includes a mountable engine for webhook handling, a gateway class for creating transactions, and Rails credentials support for secure key management.

## Prerequisites

| Requirement   | Minimum version                              |
| ------------- | -------------------------------------------- |
| Ruby on Rails | 7.0                                          |
| Ruby          | 3.1                                          |
| Simiz account | [Create one free](https://simiz.io/register) |

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

## Installation

<Steps>
  <Step title="Add the gem">
    Add to your `Gemfile`:

    ```ruby
    gem 'simiz_payments'
    ```

    Then run:

    ```bash
    bundle install
    ```
  </Step>

  <Step title="Run the generator">
    ```bash
    rails generate simiz:install
    ```

    This creates:

    * `config/initializers/simiz.rb` — configuration file
    * `db/migrate/*_create_simiz_transactions.rb` — migration for the transactions table
  </Step>

  <Step title="Run migrations">
    ```bash
    rails db:migrate
    ```
  </Step>

  <Step title="Mount the engine">
    Add to your `config/routes.rb`:

    ```ruby
    mount SimizPayments::Engine, at: '/simiz'
    ```

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

  <Step title="Configure credentials">
    Using Rails credentials:

    ```bash
    rails credentials:edit
    ```

    Add:

    ```yaml
    simiz:
      api_key: smz_test_xxxxxxxxxxxx
      environment: sandbox
      webhook_secret: whsec_xxxxxxxxxxxx
    ```

    Or use environment variables:

    ```bash
    export SIMIZ_API_KEY=smz_test_xxxxxxxxxxxx
    export SIMIZ_ENVIRONMENT=sandbox
    export SIMIZ_WEBHOOK_SECRET=whsec_xxxxxxxxxxxx
    ```
  </Step>
</Steps>

## Configuration

The initializer at `config/initializers/simiz.rb`:

```ruby
SimizPayments.configure do |config|
  config.api_key = Rails.application.credentials.dig(:simiz, :api_key) || ENV['SIMIZ_API_KEY']
  config.environment = Rails.application.credentials.dig(:simiz, :environment) || ENV.fetch('SIMIZ_ENVIRONMENT', 'sandbox')
  config.webhook_secret = Rails.application.credentials.dig(:simiz, :webhook_secret) || ENV['SIMIZ_WEBHOOK_SECRET']
  config.default_currency = 'XAF'
end
```

## Usage

### Creating a transaction

```ruby
gateway = SimizPayments::Gateway.new

transaction = gateway.create_transaction(
  amount: 5000,
  currency: 'XAF',
  phone_number: '237690000001',
  provider: 'orange_money',
  description: 'Order #1234',
  metadata: { order_id: 1234 }
)

redirect_to transaction['checkout_url']
```

### Checking transaction status

```ruby
transaction = gateway.get_transaction('txn_xxxxxxxxxxxx')

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

### Processing refunds

```ruby
refund = gateway.create_refund(
  'txn_xxxxxxxxxxxx',
  amount: 2500,
  reason: 'Customer request'
)
```

## Webhook handling

The engine handles webhook signature verification automatically. Subscribe to events using Active Support Notifications:

```ruby
# config/initializers/simiz_webhooks.rb
ActiveSupport::Notifications.subscribe('simiz.transaction.completed') do |event|
  payload = event.payload
  order = Order.find(payload['metadata']['order_id'])
  order.mark_as_paid!
end

ActiveSupport::Notifications.subscribe('simiz.transaction.failed') do |event|
  payload = event.payload
  order = Order.find(payload['metadata']['order_id'])
  order.mark_as_failed!
end

ActiveSupport::Notifications.subscribe('simiz.refund.completed') do |event|
  payload = event.payload
  # Handle refund
end
```

## 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 or Rails credentials:

```bash
export SIMIZ_API_KEY=smz_test_xxxxxxxxxxxx
export SIMIZ_ENVIRONMENT=sandbox
```

The gem 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 your webhook secret in credentials or environment variables
    * Ensure the engine is mounted and the webhook endpoint is accessible
    * Check that no Rack middleware is modifying the raw request body
  </Tab>

  <Tab title="Gem not loading">
    **Solutions:**

    * Run `bundle install` after adding the gem
    * Ensure Ruby 3.1+ and Rails 7.0+ are installed
    * Run `rails generate simiz:install` to create the initializer
  </Tab>

  <Tab title="API key errors">
    **Solutions:**

    * Verify the key in your Rails credentials 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>