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

RequirementMinimum version
Ruby on Rails7.0
Ruby3.1
Simiz accountCreate one free
You need your Simiz API keys before configuring the gem. Find them in Dashboard > Settings > API Keys.

​
Installation

1

Add the gem

Add to your Gemfile:
gem 'simiz_payments'
Then run:
bundle install
2

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
3

Run migrations

rails db:migrate
4

Mount the engine

Add to your config/routes.rb:
mount SimizPayments::Engine, at: '/simiz'
This registers the webhook endpoint at /simiz/webhooks.
5

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

MethodTypeStatus
Orange MoneyMobile MoneyAvailable
MTN Mobile MoneyMobile MoneyAvailable
WaveMobile MoneyComing Soon
Moov MoneyMobile MoneyComing Soon
Airtel MoneyMobile MoneyComing Soon
M-PesaMobile MoneyComing Soon

​
Supported currencies

CurrencyCodeCountries
Central African CFA FrancXAFCameroon, Central African Republic, Chad, Congo, Equatorial Guinea, Gabon
West African CFA FrancXOFBenin, Burkina Faso, Ivory Coast, Guinea-Bissau, Mali, Niger, Senegal, Togo
Ghanaian CediGHSGhana
Nigerian NairaNGNNigeria
Kenyan ShillingKESKenya
Ugandan ShillingUGXUganda
Rwandan FrancRWFRwanda
Tanzanian ShillingTZSTanzania

​
Webhook events

EventDescription
transaction.createdTransaction initiated
transaction.processingBeing processed by the provider
transaction.completedPayment successful
transaction.failedPayment failed
transaction.cancelledCancelled by customer
transaction.expiredPayment window expired
refund.createdRefund initiated
refund.completedRefund completed
refund.failedRefund 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

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

​
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

VersionDateChanges
1.0.02026-03-01Initial release — mobile money payments, webhooks, sandbox