Billing Laravel Package

Technical Evaluation

Architecture fit. atannex/billing is a framework-native Laravel package (service provider, config, migrations, model traits, facade, artisan commands, fake), so it slots into the conventions a Laravel team already follows rather than introducing a parallel abstraction. It targets PHP 8.2+ / Laravel 11–12, which matches a modern Laravel baseline but excludes L10 and older PHP — verified against our stack before scoping. The notable design decision is the aggregation layer: five providers (Stripe Checkout/PaymentIntents, MTN MoMo Request-to-Pay + Disbursement, Orange Money Web Payment + Cameroon USSD push, PayPal Orders v2, Flutterwave) behind one fluent API. That is real leverage for a multi-corridor product, but it also means our architecture inherits five upstream API contracts and their deprecation cycles through a single unproven dependency.

Integration feasibility. Low-to-moderate effort for a Laravel codebase. The Billable/Payable traits imply schema migrations we must own and run; the guarded state machine plus amount verification and an audit ledger are the features that make this credible for money movement rather than a thin SDK wrapper. Billing::fake() is the single most valuable item for delivery planning — it lets feature work proceed without sandbox credentials from MTN/Orange, which are historically the long pole. Idempotency keys, webhook verification/dedup, and automatic reconciliation of async payments directly reduce the two failure classes that usually generate finance escalations (double capture, silent orphaned payments).

Technical risk. This is a v1.0.0 from a small vendor with no prior assessment, no release history, and no evidence of production usage in the provided data — treat maturity, maintainer continuity, and security posture as unvalidated. Specific risks: (1) Failover is a double-charge surface — if an async MTN request times out and failover fires, the state machine and idempotency layer must provably prevent a second debit; this needs adversarial testing, not docs review. (2) Mobile money is not card payments — Request-to-Pay and Disbursement refunds have different finality, no true auth/capture, and operator-side outage behavior that failover cannot mask. (3) Cameroon-prefix routing is hardcoded domain logic — useful today, an obstacle if we expand to other markets, and a correctness risk if prefix tables drift. (4) Five payment surfaces expand PCI and compliance scope; hosted flows (Checkout, PayPal, Orange Web Payment) keep us nearer SAQ A, but any direct card handling or MTN USSD push changes the answer. (5) Bus-factor one — no fallback maintainer, and forking is expensive given the surface area.

Key questions for the maintainer. Production references and payment volume processed; test suite coverage and whether gateway HTTP is contract-tested or mocked only; failover semantics and the exact guard against duplicate capture; supported/locked provider API versions and the deprecation policy; refund behavior when the operator's disbursement fails mid-flight; MTN/Orange sandbox access terms and whether mtn-sandbox-user is officially sanctioned; security disclosure process; versioning/BC policy post-1.0; currency and market expansion path beyond XAF/XOF.

Integration Approach

Stack fit. Assumes Laravel 11/12 with queue workers, scheduler, and outbound HTTPS. Requires per-gateway credentials in env, a webhook route exposed publicly with per-provider signature secrets, and database tables for payments, ledger, and idempotency. No external service to run — good for ops simplicity, but it means reconciliation and pruning are our responsibility via the provided commands.

Migration path. Greenfield or new payment corridors are the clean case. For an existing billing implementation, do not cut over in place: run this package alongside the current provider integration behind a routing flag, per corridor, so the audit ledger can be compared against the incumbent before trust is transferred. The Billable/Payable traits and their migrations need review against existing user/order schema to avoid column and relationship conflicts.

Compatibility. Confirm PHP/Laravel versions in CI, verify the package's migration publishing doesn't collide with existing tables, and check that Billing::fake() covers the code paths we actually exercise (routing, failover, refunds) rather than only the happy path. Pin the version explicitly; at v1.0.0 a minor bump may carry behavior changes.

Sequencing. (1) Spike: install, publish config/migrations, run Billing::fake() scenarios for routing, failover, refund, and webhook dedup — this is cheap and answers the highest-risk questions. (2) Obtain one sandbox (Stripe/PayPal are fastest) and validate the end-to-end state machine, ledger, and JSON status polling. (3) Add an African corridor with real sandbox credentials; run reconcile against deliberately failed webhooks. (4) Canary one low-value corridor with a refund/dispute runbook rehearsed in advance. (5) Expand corridors only after reconciliation is provably clean for a defined period.

Operational Impact

Maintenance. We inherit five provider API surfaces. Budget ongoing effort for provider deprecations (PayPal and Stripe both version aggressively) and for package upgrades; at v1.0.0 expect breaking changes. Forking is our contingency if the vendor stalls — assess the codebase's readability now, while it's cheap, rather than at incident time.

Support. New on-call surface: stuck state-machine transitions, unmatched webhooks, failed refunds, and operator-side outages. reconcile must run on a schedule (not ad hoc), prune on a retention policy aligned to finance/audit requirements, and the JSON status route gives support a clean polling handle. Mobile money disputes are operator-mediated and slow; a documented escalation path per operator is a launch prerequisite, not a follow-up.

Scaling. Horizontal scaling is straightforward — state lives in the database, not memory. Watch three things: webhook endpoint throughput and dedup table growth, idempotency-key storage and TTL, and ledger volume. Reconciliation is the likely bottleneck during provider incidents, when backlogs spike.

Failure modes. Silent double-charge via failover (highest severity, lowest likelihood if guards hold); payment succeeded at provider but webhook lost, leaving the app state stale until reconcile runs (mitigated but not eliminated — reconcile frequency sets the exposure window); operator partial failure on disbursement refunds; credential or webhook-secret rotation breaking one corridor quietly; provider API deprecation breaking a flow at an unpredictable time.

Ramp-up. Engineers familiar with Laravel will be productive quickly on the fluent API; the real learning cost is the payment domain — state machine semantics, async finality, and refund asymmetry between cards and mobile money. Plan for a written internal runbook and one engineer designated as owner of this integration. Given v1.0.0, gate production use on a completed spike and a clean sandbox reconciliation cycle, and treat this as a pilot with a defined exit criterion rather than a settled platform decision.