The Simiz Laravel package provides a clean, idiomatic way to integrate mobile money payments into your Laravel application. Use the Simiz facade to create transactions, handle webhooks, and manage refunds.

Prerequisites

RequirementMinimum version
Laravel10.0
PHP8.1
Composer2.x
Simiz accountCreate one free
You need your Simiz API keys before configuring the package. Find them in Dashboard > Settings > API Keys.

Installation

1

Install the package

composer require simiz/laravel-payments
2

Publish the configuration

php artisan vendor:publish --tag=simiz-config
This creates a config/simiz.php configuration file.
3

Set environment variables

Add the following to your .env file:
SIMIZ_API_KEY=smz_test_xxxxxxxxxxxx
SIMIZ_ENVIRONMENT=sandbox
SIMIZ_WEBHOOK_SECRET=whsec_xxxxxxxxxxxx

Configuration

The published config/simiz.php file contains:
return [
    'api_key' => env('SIMIZ_API_KEY'),
    'environment' => env('SIMIZ_ENVIRONMENT', 'sandbox'),
    'webhook_secret' => env('SIMIZ_WEBHOOK_SECRET'),
    'currency' => env('SIMIZ_CURRENCY', 'XAF'),
];
VariableDescription
SIMIZ_API_KEYYour API key (smz_test_* or smz_live_*)
SIMIZ_ENVIRONMENTsandbox or production
SIMIZ_WEBHOOK_SECRETWebhook signing secret
SIMIZ_CURRENCYDefault currency code (optional)

Usage

Creating a transaction

use Simiz\Facades\Simiz;

$transaction = Simiz::createTransaction([
    'amount' => 5000,
    'currency' => 'XAF',
    'phone_number' => '237690000001',
    'provider' => 'orange_money',
    'description' => 'Order #1234',
    'callback_url' => route('payment.callback'),
    'metadata' => [
        'order_id' => 1234,
    ],
]);

// Redirect to checkout
return redirect($transaction->checkout_url);

Checking transaction status

$transaction = Simiz::getTransaction('txn_xxxxxxxxxxxx');

if ($transaction->status === 'completed') {
    // Payment successful
}

Processing refunds

$refund = Simiz::createRefund('txn_xxxxxxxxxxxx', [
    'amount' => 2500, // Partial refund
    'reason' => 'Customer request',
]);

Webhook handling

Register the webhook route

Add the webhook route in routes/web.php:
use Simiz\Http\Controllers\WebhookController;

Route::post('/simiz/webhook', WebhookController::class)
    ->name('simiz.webhook');

Create a webhook handler

// app/Listeners/SimizWebhookHandler.php
namespace App\Listeners;

use Simiz\Events\WebhookReceived;

class SimizWebhookHandler
{
    public function handle(WebhookReceived $event): void
    {
        match ($event->type) {
            'transaction.completed' => $this->handleCompleted($event->payload),
            'transaction.failed' => $this->handleFailed($event->payload),
            'refund.completed' => $this->handleRefund($event->payload),
            default => null,
        };
    }
}
Register the listener in EventServiceProvider:
protected $listen = [
    \Simiz\Events\WebhookReceived::class => [
        \App\Listeners\SimizWebhookHandler::class,
    ],
];
The webhook signature is automatically verified by the package middleware.

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 in your .env file:
SIMIZ_API_KEY=smz_test_xxxxxxxxxxxx
SIMIZ_ENVIRONMENT=sandbox
The package 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 SIMIZ_WEBHOOK_SECRET in your .env file
  • Ensure no middleware is modifying the raw request body before verification
  • Exclude the webhook route from CSRF protection in VerifyCsrfToken

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