Accepting mobile money in Laravel

Install

Laravel is served by the PHP client. There is no Laravel-specific package, and this page does not pretend otherwise: what is below is that client, used the way Laravel is written.

composer require ultraner/sdk

The snippets below are checked in CI against the API's own schemas. This client is not yet driven end to end against the sandbox the way the Node one is.

The Laravel trap

Add the webhook path to the CSRF exception list, and use `$request->getContent()` for the raw body. `$request->all()` has already parsed it.

Taking a payment

Two things this shows that are easy to get wrong anywhere. The amount is in whole units for most African currencies, so 5000 TZS is five thousand shillings and not fifty. And provideris the network's provider code, not its brand name: Mixx by Yas is still Tigo on the wire.

<?php
// app/Http/Controllers/PaymentController.php
use Ultraner\Ultraner;
use Illuminate\Support\Str;

$ultraner = new Ultraner(env('ULTRANER_API_KEY'));

public function pay(Request $request)
{
    $payment = $ultraner->payments->createMnoCharge([
        'amount'         => 5000,          // whole shillings, TZS has no minor unit
        'currency'       => 'TZS',
        'provider'       => 'Vodacom',     // provider code, not brand name
        'account_number' => $request->input('phone'),
    ], ['idempotency_key' => (string) Str::uuid()]);

    // Accepted, not paid. Wait for the webhook.
    return response()->json([
        'reference' => $payment->reference,
        'status'    => $payment->status,
    ]);
}

The response means the request was accepted, not that money moved. A mobile-money charge sends a prompt to the payer's handset and they may take a minute, or never answer. Which is why the next section is not optional.

Receiving the result

The webhook is how you learn a payment succeeded. Verify the signature over the raw bytes before trusting anything in the payload, acknowledge quickly, and do the work afterwards: a slow handler gets retried, and retries mean you will see the same event twice.

<?php
// Exempt the route from CSRF first: a third party cannot hold your token.
// bootstrap/app.php  ->  $middleware->validateCsrfTokens(except: ['webhooks/ultraner']);

public function handle(Request $request)
{
    $raw       = $request->getContent();   // the bytes, not ->all()
    $signature = $request->header('X-Ultraner-Signature', '');

    $expected = hash_hmac('sha256', $raw, env('ULTRANER_WEBHOOK_SECRET'));

    // hash_equals, not ===, so timing does not leak the signature.
    if (! hash_equals($expected, $signature)) {
        return response()->noContent(400);
    }

    $event = json_decode($raw, true);
    HandleUltranerEvent::dispatch($event);  // queue it, acknowledge now
    return response()->noContent(200);
}