Download the PHP package maestrodimateo/simple-mobile-money without Composer

Simple Mobile Money

One simple, unified Laravel API to collect and disburse mobile money payments in Gabon — through E-Billing, SingPay and PViT (Airtel Money & Moov Money).

You write the same code for every provider. The package hides each API's base URL, auth scheme, payload format and webhook shape behind neutral DTOs, a single facade, and Laravel events.

Nouveau sur le mobile money ? Lis le Guide du débutant — une explication pas à pas (en français) du fonctionnement du package et de chaque agrégateur.

Table of contents

How it works

A mobile money collection is asynchronous: pay() only starts it. The real outcome (success / failure) arrives later through a webhook, which the package turns into a Laravel event.

Two flows

Full lifecycle

Key idea: never mark an order as paid from the pay() response. Fulfil it only when you receive the PaymentSucceeded event.

Requirements

• PHP 8.3+
• Laravel 12.x / 13.x

Installation

Publish the config and run the migration:

The transactions table is registered automatically.

Provider setup

Pick your default provider, then fill in credentials for the ones you use.

E-Billing (Digitech)

Credentials come from your merchant profile (LAB or PROD).

E-Billing requires payer_email and payer_name — set payerEmail and payerName on the PaymentRequest.

E-Billing is callback-only: no status endpoint, so status() throws (supportsStatusQuery() === false).

Payout credentials (SHAP API)

Payout uses separate OAuth2 credentials:

PAYIN OAuth2 (AWS Cognito)

E-Billing is migrating PAYIN from HTTP Basic to AWS Cognito OAuth2 (production cutover 2026-08-31). The driver supports both — it stays on Basic until you flip the toggle.

SingPay

Credentials come from SingPay Workspace (client.singpay.ga).

For the ext (hosted page) flow:

PViT (mypvit / BakoAI, API v2)

Credentials come from your PViT merchant space. Auth is the X-Secret header.

Note: Some provider details are not publicly documented (PViT's Airtel v2 operator code, E-Billing operator machine codes). They are configurable in config/mobile-money.php (providers.*.operators) — confirm them with each provider.

Quickstart

Three steps: initiate → webhook → fulfil.

Step 1 — Start the payment

$response->status is PENDING — do not treat it as paid yet.

Step 2 — Register the webhook URL

The package exposes POST /mobile-money/webhook/{provider} automatically. Register the matching public URL in each provider's dashboard:

Step 3 — Fulfil the order on success

Register it in your EventServiceProvider (or with an attribute listener). A PaymentFailed event is dispatched for failed / cancelled / expired payments.

Payout (cash-out)

Send money out to a beneficiary (refund, cashback, withdrawal).

Provider support

Usage

Balance & status

Payout events

PayoutInitiated → PayoutSucceeded / PayoutFailed (fired immediately since the payout is synchronous). Payouts are stored in the same table with type = payout.

API reference

Facade — MobileMoney

Gateway methods

status() throws if supportsStatusQuery() is false (E-Billing).

PaymentRequest

What you build and pass to pay().

PaymentResponse

Returned by pay().

PaymentStatus (enum)

PENDING · SUCCESS · FAILED · CANCELLED · EXPIRED · AMBIGUOUS · UNKNOWN

Operator (enum)

Operator::AIRTEL · Operator::MOOV

CallbackResult

Carried by webhook events.

Events

transaction is the stored Transaction model (or null if persistence is off).

Transaction model

Stored in mobile_money_transactions.

provider · type · reference · provider_reference · status · amount · currency · msisdn · operator · description · metadata · raw

Exceptions

Both extend MobileMoneyException.

Webhooks

Testing locally: expose your app with a tunnel (e.g. php artisan expose or ngrok) and register the public tunnel URL in the provider dashboards.

Security model

None of the three aggregators sign their webhooks. The callback body is treated as an untrusted hint. On every webhook the package:

1. IP allowlist — optionally restricts callbacks to known IPs (webhooks.allowed_ips). Configure TrustedProxies so request()->ip() is the real client IP behind a load balancer.

2. Reference matching — matches the callback to a stored transaction and rejects any webhook pointing to a different provider transaction than the one on record.

3. Status re-verification — re-verifies the status against the provider API using the stored provider reference, never the one in the webhook body (webhooks.verify_status, on by default). For SingPay's ext flow, the re-verified provider transaction must also match the merchant reference.

4. Fail-closed — returns HTTP 4xx when it cannot re-verify or the status is uncertain (UNKNOWN / AMBIGUOUS). Never moves a transaction out of a terminal state. For E-Billing (callback-only), a matching amount is mandatory.

5. Replay-safe — dispatches terminal events only on the transition into the final state. A replayed webhook cannot re-trigger fulfilment.

6. Rate-limited — by default (webhooks.middleware), since each call triggers a synchronous outbound verification.

Keep persistence enabled (store.enabled) in production. With storage off, the package can only do a best-effort check — your app must validate the reference ↔ provider-reference mapping itself.

Configuration

config/mobile-money.php

Testing

Package tests

Faking in your app

MobileMoney::fake() swaps the manager for a test double — no HTTP, no raw payloads to stub.

Stub responses

Assertions

Testing a declined payment

The fake covers pay() / payout() only. It does not persist transactions or dispatch events (those are webhook-driven). To test that path, Http::fake() the provider and POST the webhook route.

Recipes & FAQ

Custom Transaction model Point store.model at your own model (extend the package's Transaction).

Go stateless Set store.enabled=false. Persist what you need from the events yourself. Read the security note first.

Idempotent fulfilment The same webhook can arrive more than once. Guard your listener: if ($order->isPaid()) return;

Poll status Call MobileMoney::driver('pvit')->status($providerReference) where $providerReference is from PaymentResponse->providerReference or the stored transaction. Not available for E-Billing (supportsStatusQuery() === false).

Test with HTTP fakes

Roadmap

• Direct Airtel Money / Moov Money integrations (operator contracts required).

License

MIT.