Ruby on Rails - Simiz Docs

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

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

Installation

Add the gem

Add to your Gemfile:

gem 'simiz_payments'

Then run:

bundle install

Run the generator

rails generate simiz:install

This creates:

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

Run migrations

rails db:migrate

Mount the engine

Add to your config/routes.rb:

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

This registers the webhook endpoint at /simiz/webhooks.

Configure credentials

Using Rails credentials:

rails credentials:edit

Add:

simiz:
  api_key: smz_test_xxxxxxxxxxxx
  environment: sandbox
  webhook_secret: whsec_xxxxxxxxxxxx

Or use environment variables:

export SIMIZ_API_KEY=smz_test_xxxxxxxxxxxx
export SIMIZ_ENVIRONMENT=sandbox
export SIMIZ_WEBHOOK_SECRET=whsec_xxxxxxxxxxxx

Configuration

The initializer at config/initializers/simiz.rb:

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

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

transaction = gateway.get_transaction('txn_xxxxxxxxxxxx')

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

Processing refunds

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:

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

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.

Full sandbox documentation

See all test numbers and scenarios in the Sandbox Testing guide.

Troubleshooting

Webhook signature invalid
Gem not loading
API key errors

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

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

Next steps

Webhook Verification

Learn about webhook configuration and signature verification.

API Reference

Explore the full Simiz API.

Sandbox Testing

Test all payment scenarios before going live.

Support

Need help? Contact our support team.

Changelog

Version history

Version	Date	Changes
`1.0.0`	2026-03-01	Initial release — mobile money payments, webhooks, sandbox

​Prerequisites

​Installation

​Configuration

​Usage

​Creating a transaction

​Checking transaction status

​Processing refunds

​Webhook handling

​Supported payment methods

​Supported currencies

​Webhook events

​Test mode

Full sandbox documentation

​Troubleshooting

​Next steps

Webhook Verification

API Reference

Sandbox Testing

Support

​Changelog

Prerequisites

Installation

Configuration

Usage

Creating a transaction

Checking transaction status

Processing refunds

Webhook handling

Supported payment methods

Supported currencies

Webhook events

Test mode

Troubleshooting

Next steps

Changelog