Paynecta Laravel Sdk Laravel Package

Product Decisions This Supports

• Forced migration vs. rebuild (do not treat as discretionary). v1.x is not "deprecated," it is non-functional: paynecta.co.ke/api/v1 returns 404 and the X-API-Key/X-User-Email auth scheme no longer exists. Any roadmap item that assumes the current integration works needs to be re-baselined today, and any "keep 1.x alive with a patch" option should be struck from the decision log — there is nothing behind the old endpoints to patch.
• Closing a live fraud vector. Under 1.x, any actor who knew the webhook URL could POST a forged payment.completed and have an order marked paid and shipped — an unauthenticated route at a fixed default path, validating only field presence. Moving to HMAC-SHA256 over timestamp + raw body, constant-time comparison, and a five-minute replay window converts that from an open door to a verified channel. This is a security decision the PM should record and communicate, not just a library change.
• Fail-closed as an explicit product stance. With no signing secret configured, every delivery is refused. That is the right default for payments, but it turns configuration into a launch gate: a deploy without a secret silently takes money and hears nothing back. This belongs in the release checklist and the runbook, and it should drive how you sequence the rollout.
• Consent and consumer-initiated payment flow. Because no method accepts a caller-supplied mobile_number, the consumer enters and code-verifies their own number on Paynecta's hosted checkout. That removes server-side STK-style prompting from your design surface entirely — ~15,000 unwanted prompts and a flagged shortcode are the cost of the old model. Any product flow, retry logic, or "resend prompt" UX built on server-initiated prompts must be redesigned, and the new flow should be reflected in your checkout funnel metrics and support macros.
• Webhook registration as code, not dashboard copy. php artisan paynecta:register closes the "copy this address into the dashboard" step that people skip — the exact failure mode where an app takes payments and receives no confirmations. This removes a recurring class of production incident and makes the integration reproducible across staging, DR, and new environments.
• Build vs. buy. 16 endpoints — checkouts, transactions, tapflows, webhooks, integrations, banks, balance, whoami — covers collection, reconciliation, bank lookup, and account identity. Writing and maintaining that surface in-house, with signed webhooks and replay protection, is not a credible use of a small team's capacity. Buy.
• Scope discovery for roadmap. balance, banks, and integrations were not part of the 1.x mental model; they unlock payout and reconciliation features (treasury dashboards, settlement reporting, counterparty verification) that were previously assumed to need a separate vendor.

When to Consider This Package

Adopt when:

• You are on Laravel/PHP and already integrated with Paynecta — which, given 1.x is dead, means adopting v2.0.0 is the only path back to working payments.
• You need mobile money collection in the Kenyan market with a consumer-entered, code-verified MSISDN, and you are content to let Paynecta's hosted checkout own that consent step.
• You need reconciliation primitives (transactions, balance), bank/counterparty data (banks), or merchant identity (whoami) alongside collection.
• You want verified, replay-protected webhooks without building signing infrastructure yourself.

Look elsewhere or re-plan when:

• Your UX depends on server-initiated prompts to a number you supply. The package has deliberately removed that capability. If a flow — agent-assisted checkout, call-centre-initiated collection, bulk prompt campaigns — requires it, this is a product gap, not a technical one, and no version of this package will restore it.
• You need a PSP-abstraction layer. This is a single-provider client, not a payment orchestration layer. Multi-provider routing or failover needs an abstraction above it.
• You are not on PHP/Laravel, or you need capabilities beyond the 16 listed endpoints (card acquiring, subscriptions, multi-currency beyond Paynecta's own support).
• You were hoping for a low-risk incremental upgrade. There is no compatibility shim and no coexistence window. The README documents three diffs, which suggests a contained blast radius, but the cutover is a flag day — plan a maintenance window, not a canary.

How to Pitch It (Stakeholders)

To executives: Our payment integration is currently down, not merely outdated — the upstream API v1 called has been withdrawn entirely, which is why payments have stopped. v2.0.0 is the replacement, and it also closes a serious security hole: our old webhook endpoint accepted unauthenticated posts, so anyone who knew the URL could mark an order paid without paying. Deliveries are now cryptographically signed and time-limited. Separately, the old integration sent payment prompts to phone numbers we supplied — roughly 15,000 unwanted prompts, which got our shortcode flagged. The new flow has the customer enter and confirm their own number, which removes that compliance exposure entirely. This is a remediation with a security and regulatory upside, not a feature upgrade.

To engineering: Breaking change, no shim, no coexistence — cut over cleanly. The surface is small (three documented diffs in the README) and 1.x has nothing worth preserving. Two things to internalise: first, the package fails closed — with no signing secret configured, every webhook is refused, so secret provisioning must land before the first deploy that accepts traffic; second, register the endpoint via php artisan paynecta:register rather than by hand, which eliminates the skipped-dashboard-step failure mode that has bitten us before. Note that vendor/ is no longer committed — CI must run composer install. The webhook suite has eight tests, five of which fail against 1.x behaviour; that is deliberate regression evidence, and it should give us confidence the signature path is actually exercised rather than asserted. Sequence the work as: secret provisioning → endpoint registration → code cutover → verified end-to-end payment in staging → production.