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

# Laravel

> Accept mobile money payments in your Laravel application with the Simiz PHP package.

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

| Requirement   | Minimum version                              |
| ------------- | -------------------------------------------- |
| Laravel       | 10.0                                         |
| PHP           | 8.1                                          |
| Composer      | 2.x                                          |
| Simiz account | [Create one free](https://simiz.io/register) |

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

## Installation

<Steps>
  <Step title="Install the package">
    ```bash
    composer require simiz/laravel-payments
    ```
  </Step>

  <Step title="Publish the configuration">
    ```bash
    php artisan vendor:publish --tag=simiz-config
    ```

    This creates a `config/simiz.php` configuration file.
  </Step>

  <Step title="Set environment variables">
    Add the following to your `.env` file:

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

## Configuration

The published `config/simiz.php` file contains:

```php
return [
    'api_key' => env('SIMIZ_API_KEY'),
    'environment' => env('SIMIZ_ENVIRONMENT', 'sandbox'),
    'webhook_secret' => env('SIMIZ_WEBHOOK_SECRET'),
    'currency' => env('SIMIZ_CURRENCY', 'XAF'),
];
```

| Variable               | Description                                 |
| ---------------------- | ------------------------------------------- |
| `SIMIZ_API_KEY`        | Your API key (`smz_test_*` or `smz_live_*`) |
| `SIMIZ_ENVIRONMENT`    | `sandbox` or `production`                   |
| `SIMIZ_WEBHOOK_SECRET` | Webhook signing secret                      |
| `SIMIZ_CURRENCY`       | Default currency code (optional)            |

## Usage

### Creating a transaction

```php
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

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

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

### Processing refunds

```php
$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`:

```php
use Simiz\Http\Controllers\WebhookController;

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

### Create a webhook handler

```php
// 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`:

```php
protected $listen = [
    \Simiz\Events\WebhookReceived::class => [
        \App\Listeners\SimizWebhookHandler::class,
    ],
];
```

The webhook signature is automatically verified by the package middleware.

## 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 in your `.env` file:

```env
SIMIZ_API_KEY=smz_test_xxxxxxxxxxxx
SIMIZ_ENVIRONMENT=sandbox
```

The package 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 `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`
  </Tab>

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

    * Verify `SIMIZ_API_KEY` is set correctly in `.env`
    * Ensure you are using the correct key for the environment
    * Clear the config cache: `php artisan config:clear`
  </Tab>

  <Tab title="Package not found">
    **Solutions:**

    * Run `composer update` to resolve dependencies
    * Ensure PHP 8.1+ and Laravel 10+ are installed
    * Clear the autoload: `composer dump-autoload`
  </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>