alphaolomi/laravel-azampay
A Laravel package for integrating AzamPay, Tanzania's payment gateway, into your PHP apps. It offers a clean, fluent API for mobile money and bank payments, checkout flows, callbacks, and transaction handling, making payment integration simple and fast.
Architecture fit: laravel-azampay is a thin Laravel service-provider wrapper around Azampay, a Tanzanian mobile-money payment aggregator (M-Pesa, Tigo Pesa, Airtel Money, Halopesa, etc.). Architecturally it is a conventional Laravel package: a service provider, a facade/config surface, and HTTP client calls to Azampay's REST API. It does not attempt to own payment state — it brokers checkout/collect/disburse calls. That means it fits cleanly as an adapter behind your own PaymentGateway interface rather than as a subsystem you architect around. For a Laravel monolith or modular Laravel app already using the framework's HTTP client and queue primitives, the fit is high; for a polyglot or event-driven service mesh it is a poor primary abstraction and should be isolated in a Laravel-side service.
Integration feasibility: Low-to-moderate effort. Expected surface is: install via Composer, publish config, set credentials (client_id, client_secret, app_name, environment sandbox/production), and call facade methods for checkout session creation, payment collection, and disbursement. Because the package is small, the real work is not the integration but the surrounding concerns: webhook/callback verification, reconciliation against Azampay's settlement reports, idempotency keys on every money-movement call, and mapping Azampay's transaction states onto your internal order state machine. The v0.2.0 → v1.0.0 jump is a semver-major signal; even though the published notes read as CI/dependency hygiene plus Laravel 11 support, the changelog does not enumerate breaking API changes, so the public method signatures must be diffed before adopting.
Technical risk: Several material risks. (1) Vendor maturity — a single-maintainer package (alphaolomi) with a v1.0.0 that is largely dependabot activity; bus factor and long-term maintenance are the dominant risks, not code quality. (2) Hidden breaking changes — a major version bump with only chore-level notes means either the bump is ceremonial (acknowledging stability) or breaking changes are undocumented; treat as unknown until diffed. (3) Regulatory/financial exposure — Azampay is a licensed aggregator; your compliance posture (PCI scope, data residency in Tanzania, TZ regulatory requirements) sits with Azampay's terms and your own contracts, not with this package. (4) Coverage of failure semantics — small packages typically do not model partial failures, timeouts on collection, or reversal flows; you must build those. (5) Test coverage — CI was just updated, which suggests tests exist but the release notes give no signal on coverage depth or integration tests against sandbox.
Key questions:
src/, config keys, and facade methods before upgrade.Stack fit: Requires PHP 8.x, Laravel 9/10/11 (Laravel 11 explicitly added in this release), and Composer. It rides on Laravel's HTTP client, so it inherits Guzzle, middleware, retry, and logging behavior — good for observability. It is not compatible with non-Laravel PHP apps without manual wiring, and it is not a fit for event-driven stacks (Node/Go/Python services) except as an isolated payment service.
Migration path: Because there is no prior assessment and no incumbent, this is a greenfield adoption rather than a migration. Recommended sequence: pin ^1.0.0 only after diffing the API against 0.2.0; integrate in sandbox first; build your own gateway interface around it so the package is swappable. If you were previously calling Azampay's REST API directly, the package is an incremental consolidation, not a rewrite — the wire protocol is unchanged, so you can run both paths in parallel behind a feature flag and compare results before cutting over.
Compatibility: Laravel 11 support is the headline functional change in this release and is genuinely useful if you are on or planning an L11 upgrade. Check transitive constraints: illuminate/support and guzzlehttp/guzzle version ranges will determine whether it coexists with your other payment/SDK packages. Verify PHP version floor against your fleet; if any app is still on PHP 8.0, confirm the package's minimum.
Sequencing:
AzampayGateway adapter implementing your internal payment interface; add idempotency, structured logging, and reconciliation job scaffolding.Do not plan a big-bang rollout for a payments dependency with a single-maintainer upstream.
Maintenance: Ongoing cost is low in code terms but non-zero in vigilance. Budget for: tracking upstream releases (the repo's activity is mostly dependabot, so meaningful releases may be sparse and then jump majors), monitoring Laravel/PHP version drift, and periodically re-verifying Azampay API behavior since the aggregator can change endpoints independently of the package. Because you will wrap it in your own adapter, expect the adapter — not the package — to be where most maintenance lands. A realistic estimate is a few engineer-days per quarter plus reactive work on upstream or aggregator changes.
Support: This is the weakest dimension. There is no commercial support, no SLA, and effectively a single maintainer. Treat the package as "community-supported, use at your own risk." Mitigations: fork it into your org (MIT/Apache-style licensing permitting), keep the fork buildable in CI, and ensure at least two engineers on your side can read and patch it. Establish a written escalation path that goes to Azampay's merchant support for payment issues and to your internal fork for code issues — never depend on the upstream maintainer for incident response.
Scaling: The package itself is not a scaling bottleneck — it is stateless HTTP calls. Scaling constraints will come from Azampay's rate limits, per-request latency, and settlement windows. Design for queue-based dispatch of collection and disbursement calls, bounded concurrency, exponential backoff with jitter on 5xx/timeouts, and idempotency so retries are safe. Watch connection pooling if you run high volume; Laravel's HTTP client handles this adequately but tune Guzzle options. Multi-tenant usage needs per-tenant credential resolution, which a global config may not provide out of the box — verify and, if absent, resolve credentials per-call in your adapter.
Failure modes: Enumerate and design for each: (a) network timeout on collect — the charge may have succeeded; never blind-retry without an idempotency key and a status query; (b) webhook never arrives — build a polling reconciliation job as the source of truth, treat webhooks as an optimization; (c) duplicate callbacks — dedupe on Azampay transaction ID; (d) partial failure on disbursement — model a pending/unknown state and resolve out-of-band; (e) credential expiry / rotation — support hot reload without redeploy; (f) package abandonment — covered by the fork strategy; (g) silent API drift at Azampay — contract tests in CI against sandbox, plus alerting on unexpected response shapes.
Ramp-up: A Laravel-proficient engineer can be productive in half a day on the package API; the real ramp is on Azampay's domain model and on your reconciliation/state-machine conventions, which is one to two weeks for a mid-level engineer to operate safely. Produce a short internal runbook covering: how to run in sandbox, how to read a failed transaction, how to reconcile a mismatch, and how to rotate credentials. Given the financial blast radius, gate production access behind a second reviewer for any change touching payment code.
How can I help you explore Laravel packages today?