Download the PHP package atannex/billing without Composer

atannex/billing

Payments for Laravel across Stripe, MTN Mobile Money, Orange Money, PayPal and Flutterwave, behind one API. It was built for Cameroon first (XAF, MTN and Orange numbers, mobile money that settles minutes later) and works the same for card payments anywhere.

What you get:

• One fluent API for five providers, plus your own drivers through Billing::extend(). Every provider is called with Laravel's HTTP client, so there are no vendor SDKs to install.
• Smart routing. Each payment goes to the first enabled gateway that takes its currency and method and serves the payer's phone operator. Cameroonian prefixes are built in (MTN 67x/650–654/680–684, Orange 69x/655–659/640/685–689) and configurable. Optional failover moves to the next gateway when one is down, but never once a charge may have started.
• A guarded state machine. pending → processing / requires_action → succeeded → partially_refunded → refunded. A stale webhook can't reopen a settled payment. A late provider success can still land after a local expiry, because the money really arrived.
• Amount verification. A "success" for a different amount or currency is not believed. The payment fails with amount_mismatch and AmountMismatch fires.
• Race-proof processing. Webhooks, the return page, polling and reconciliation all go through one processor that locks the row. Events fire exactly once, after the commit.
• Verified webhooks. Stripe HMAC signatures with a timestamp tolerance, PayPal's verification API, Flutterwave's secret hash, and Orange's per-payment notif_token. MTN callbacks are unsigned, so they only trigger a status check with MTN. Duplicate deliveries are recorded once and answered without being reprocessed.
• Automatic reconciliation for asynchronous payments. Open payments are re-checked on a back-off (10s, 20s, 30s, 1m … 1h) until they settle or expire, so a lost callback never strands a payment. A request that timed out on its way to MTN is looked up instead of being charged twice.
• Refunds, full or partial, with over-refund protection that counts refunds still in flight. MTN refunds go through its Disbursement product.
• Idempotency keys. A double click or a retried job returns the first payment instead of charging again.
• An audit ledger. Every transition, failover, mismatch and refund is recorded with its source and the provider's answer, with secrets redacted.
• Exact money. Integer minor units with ISO 4217 decimals. Money::of('19.99', 'USD') is exactly 1999, and XAF has no cents.
• A test fake. Billing::fake() scripts provider outcomes, keeps real routing, and gives you assertCharged(), settle() and friends.
• Tooling. billing:reconcile, billing:payment, billing:gateways, billing:prune, and billing:mtn-sandbox-user.

Install

The provider is auto-discovered. It registers its tables (billing_payments, billing_refunds, billing_payment_events, billing_webhook_calls), three routes and a scheduled billing:reconcile every minute. Make sure the scheduler runs (php artisan schedule:work locally, or cron in production).

Configure

Each gateway turns on when its credentials are present. php artisan billing:gateways shows what is enabled and in which routing order.

In the MTN sandbox, API users are created through the API rather than a dashboard:

The sandbox only accepts EUR, so currency_map sends XAF as EUR there and reads it back as XAF. The same mechanism maps XAF → OUV in the Orange sandbox.

Callback URLs to give each provider

Taking payments

Narrow the choice with ->method('card' | 'mobile_money' | 'wallet' | 'bank'), or force a gateway with ->via('stripe'). A forced gateway skips routing and failover. Billing::minor(1250, 'USD') takes cents.

What to do next depends on the status:

For the "approve the prompt on your phone" screen, poll the status route. It checks with the provider when the payment hasn't been updated for a few seconds, so the page learns the outcome even when the callback never arrives:

Hosted pages send the payer back to GET /billing/return/{reference}. Billing asks the provider for the status (it never trusts the query string), captures PayPal orders, then redirects to your returnTo() URL with ?payment=PAY-…&status=succeeded.

Models

Override billingName(), billingEmail() or billingPhone() on a Billable model when its attributes have other names. Payable and Billable both define payments(), so don't use both on one model.

Payment API

Refunds

Refunds lock the payment and count refunds still in flight, so two concurrent refunds can't exceed the amount paid. Providers that settle refunds later (MTN, sometimes Stripe and PayPal) are followed up by billing:reconcile and webhooks. Orange Money has no public refund API, so refund() throws UnsupportedCapability for it.

Events

All payment events fire once, after the database commit:

Routing

A gateway is eligible when it is enabled, its currencies include the payment's currency (or the list is empty), its methods include the requested method, and, if it lists operators, the payer's number belongs to one of them. Push gateways (MTN, Orange merchant) also need a phone number. Billing::router()->candidates('XAF', null, Msisdn::parse('699…')) shows the decision, and billing:gateways shows the table.

Phone numbers are normalized by Atannex\Billing\Support\Msisdn ("677 12 34 56", "+237677123456", "00237…" all become 237677123456). Operator prefixes and calling codes live in config/billing.php; adjust them when a regulator reassigns a range.

Reconciliation

Mobile money is asynchronous, and callbacks get lost or arrive late. Each open payment carries next_check_at and expires_at (from the gateway's expires_after). billing:reconcile runs every minute and checks due payments on the reconcile.backoff schedule, with the last check placed exactly at expiry. A payment still unanswered at expiry becomes expired. If the provider later reports success through a callback or a manual refresh, it moves to succeeded and the ledger records a late_success.

Set BILLING_QUEUE=payments to check payments through queued ReconcilePayment jobs instead of inline. Set reconcile.schedule to false if you schedule the command yourself.

Testing your app

For local development without credentials, enable the fake gateway ('enabled' => true, 'outcome' => 'requires_action'). Its redirect goes straight to the return page and the payment succeeds.

Writing a driver

Then add it under gateways with 'driver' => 'cinetpay'. Drivers only translate. send() applies the error policy (unreachable or 5xx → GatewayUnavailable, other failures → GatewayException with the provider's message), token() caches OAuth tokens, and the processor handles state, amounts, locking, the ledger and events. Return the provider's charged amount in Snapshot::$amount to get mismatch protection.

Commands

Notes

• Orange Money endpoints. Orange runs two APIs: Web Payment on api.orange.com, and the Cameroon merchant API, whose host and version path (/omcoreapis/1.0.2) depend on your contract. Every URL is in config, so check them against the documents Orange gives you.
• PayPal doesn't settle XAF, so it is limited to the currencies in its currencies list and routing never sends XAF there.
• Stripe and zero-decimal currencies. Amounts are sent in minor units, and XAF, XOF and JPY have none. Stripe treats a few currencies (HUF, TWD, UGX) specially; check its docs before charging in those.
• Unsigned callbacks are never trusted. MTN, Orange, PayPal and Flutterwave notifications trigger a status check with the provider. Only Stripe's signed events are applied as received.
• Routes (billing.webhook, billing.return, billing.status) can be renamed through routes.prefix or disabled with routes.enabled. If you disable them, register equivalents with the same names, because callback URLs are built from them.

Testing the package

License

MIT