Laravel Kopokopo Laravel Package

Product Decisions This Supports

• Build vs. buy for Kenyan payment rails: This package represents the "buy" side of the decision — it wraps the Kopokopo (M-Pesa aggregator) REST API behind Laravel-native config, facades, service classes, and webhook handling. It lets you validate "integrate Kopokopo" in days rather than scoping a from-scratch Safaricom Daraja integration.
• Market expansion sequencing: Unblocks Kenya-first roadmap items — customer-initiated collections (STK Push), Buy Goods/Till receiving, B2C disbursements and payouts, transaction status polling, and inbound-payment webhook subscriptions for reconciliation.
• Product surface area it enables: Checkout and wallet top-ups, subscription/recurring billing via M-Pesa, marketplace or merchant split payouts, settlement reconciliation dashboards, and refund flows.
• Architecture decision — wrapper vs. direct dependency: The package is small and opinionated. Decide whether to consume it directly or (recommended) hide it behind an internal PaymentGateway port so the vendor choice stays reversible and additional country PSPs can slot in later without touching product code.
• Operational model: Webhook-driven reconciliation is the core operating assumption. This drives decisions on idempotency keys, retry handling, ledger design, and finance ops runbooks — all of which must be scoped alongside the integration, not after.
• Risk posture for dependency management: Single-maintainer, community-supported package (4 stars, last release Jan 2023). That is a supportability decision to be managed (pin versions, negotiate fork rights, maintain contract tests) rather than a blocker for a time-boxed market test.
• Release 1.3.1 impact — none material: This is a patch bump (1.3.0 → 1.3.1) with no published changelog detail beyond the diff link. No new capabilities, no deprecations, no known breaking changes. Treat it as routine maintenance with a low-priority version bump — no roadmap consequence.

When to Consider This Package

Adopt when:

• You are on a supported Laravel version (the package targets Laravel 8; verify compatibility with 9/10/11 before committing) and your payment rail is specifically Kopokopo, not raw M-Pesa/Daraja.
• Kenya or East Africa is a target market and M-Pesa is the dominant rail your users actually pay with.
• You want a config-driven integration (sandbox vs. production credentials, .env support) without writing and maintaining an HTTP client, OAuth token refresh, and webhook plumbing yourself.
• Your team is small and a dedicated payments specialist isn't justified for a first launch.
• You are willing to wrap it — consuming it behind your own interface costs little and neutralizes most of the dependency risk.

Look elsewhere when:

• You need multi-country, multi-PSP orchestration. This is a single-vendor adapter; a payments orchestration layer or your own ports-and-adapters design is the better fit.
• You require a commercial SLA, vendor support contract, or security attestation. Community packages do not provide these.
• You are not on Laravel, or you need direct Safaricom Daraja access for margin or control reasons.
• Your compliance scope demands a reviewed, audited integration path — in which case use the package as a reference implementation and own the client.
• Maintenance signals look thin relative to your risk tolerance and forking is not an option (last release 2023, tiny star count, single maintainer).

Release-specific caution: 1.3.1 ships without release notes beyond an auto-generated diff link. Before promoting to production, have an engineer review the 1.3.0 → 1.3.1 commit diff and confirm no behavioral change in webhook or auth paths. Absence of notes is not evidence of absence of change. Also confirm the package's Laravel version constraints before assuming drop-in compatibility with recent framework releases.

How to Pitch It (Stakeholders)

To executives (one paragraph):

This is glue code, not a platform bet. It shortens Kenya payment integration from an estimated multi-week build to a few days of configuration and wiring, which lets us test the market cheaply. It is a single-vendor, single-maintainer dependency, so we contain that risk by routing it behind our own payments interface: if it stalls or we outgrow it, we swap the adapter without touching product code. Cost to try is low; cost to reverse is low. Recommend a time-boxed spike followed by a go/no-go.

To engineering:

Thin Laravel wrapper over the Kopokopo REST API — config-based credentials (.env only), auto-discovered service provider, facade access, and webhook endpoint handling. Do not let vendor types leak into domain code: define a PaymentGateway interface (collect, disburse, status, refund) and implement it with this package. Enforce webhook idempotency at the boundary with a processed-events table and unique index, treat reconciliation polling as a first-class path (not a fallback), and pin the version explicitly in composer.json. Note the tight operational constraints we'll have to build around: integer KES amounts only, strict 2547XXXXXXXX phone formatting, publicly reachable HTTPS callback URLs, and Africa/Nairobi timestamps that must be normalized to UTC at ingest. Keep a handful of captured sandbox payloads as fixtures — including a duplicate, an out-of-order event, and a failure event — and replay them in CI. Treat the latest release as 1.3.1, a patch — no breaking changes or deprecations indicated, but notes are empty, so review the diff before bumping and re-run contract tests after.

The ask: approve a short integration spike, a pinned dependency with a named owner, and a documented fallback plan (fork or replace the adapter).