Paynecta Laravel Sdk Laravel Package

Technical Evaluation

Architecture fit. This is a Laravel-native package that assumes a server-side checkout-initiation flow plus an inbound webhook for state transitions. That maps cleanly onto a standard order lifecycle (create checkout → redirect customer → receive payment.completed → transition order → fulfil). Two architectural properties are worth calling out positively: the hosted-checkout model removes our systems from the card/MSISDN entry path entirely, and the package now owns webhook registration (php artisan paynecta:register), which means the callback configuration becomes a deployable, reviewable artifact instead of a dashboard step a human forgets.

Integration feasibility. The surface is genuinely complete relative to what a payments integration needs: checkouts, transactions, webhooks, integrations, banks, balance, whoami, plus tapflows. balance and whoami are operationally valuable — they give us a health-check and a reconciliation anchor without a custom endpoint. The blocker is that v2.0.0 is not an upgrade, it is a replacement: the 1.x base URL returns 404 and the X-API-Key / X-User-Email auth scheme is gone. There is no shim, and the release notes are explicit that no shim is possible. Any estimate framed as "bump the dependency" is wrong by an order of magnitude.

Technical risk.

• Fail-closed webhooks are the top risk. With no signing secret configured, every delivery is refused. That is the correct security default, but it converts a config omission into silent, total loss of payment confirmation — orders stay pending, nothing ships, and the failure is invisible unless we alert on "webhook received with no processing outcome." This must be a monitored condition, not a log line.
• Raw-body signature verification is fragile in Laravel. HMAC must be computed over the exact raw body. Anything that touches the request body before verification — middleware, request logging, an API gateway that re-serializes JSON — breaks it. Middleware ordering and route-level CSRF exclusion need explicit design, not discovery in staging.
• Replay window vs. queueing. Five minutes is checked against the timestamp. If we enqueue webhook processing and verify inside the job, queue latency alone can push valid deliveries outside the window. Verification must happen synchronously at the edge, before dispatch.
• Vendor maturity. 1.x shipped an unauthenticated webhook that trusted field presence, and a prompt API that took a caller-supplied number and generated ~15,000 unwanted prompts, getting the shortcode flagged. Both are serious. The remediation looks competent — constant-time compare, explicit time bound, tests written to fail against 1.x — but this is a vendor that has demonstrated one critical auth bypass in production.
• Test coverage. Eight tests across sixteen endpoints is thin. The HMAC path is covered; the money-moving paths (checkout creation, transaction state, idempotency) are not demonstrated.

Key questions.

1. Is webhook processing idempotent on duplicate payment.completed deliveries, and what is the recommended dedupe key?
2. Does checkouts accept a client-supplied idempotency key?
3. Is paynecta:register idempotent, and what credential scope does it require? Can it run against staging and production independently?
4. Which PHP and Laravel versions are supported, and what are the composer.json constraints?
5. Are the eight tests runnable against a sandbox, and is there a sandbox environment at all?
6. What is the secret rotation procedure, and does it support overlapping secrets during rotation?
7. Is there an SLA and an escalation contact? What happens to our integration if the shortcode is flagged again?
8. Does the package expose typed exceptions, or do we need to classify failures ourselves?

Integration Approach

Stack fit. Native Laravel package with an Artisan command and a config surface — low friction for our application. The main fit question is asynchronous behaviour: gateway calls appear synchronous, so checkout initiation sits in the request path and inherits gateway latency. We should confirm timeout configuration and wrap initiation so a slow gateway degrades to a retryable error rather than a hung request.

Migration path. There is no incremental path, so the honest framing is re-implementation with a forced deadline. Concretely:

• Immediate, independent of the upgrade: retire the 1.x webhook route. Even if we build nothing else this sprint, an unauthenticated endpoint that marks orders paid must not remain reachable. Return 410 or delete the route entirely.
• Map the three README diffs to our code: auth/credentials, endpoint base and payload shape, webhook verification. Everything else in our adapter is new.
• Data migration: 1.x stored caller-supplied mobile_number. That field is now meaningless — the customer enters their own number on Paynecta's page. Drop it from our schema or mark it legacy; do not attempt to map it forward.
• Rebuild the confirmation path as a signature-verifying, queue-dispatching handler with an explicit order state machine and duplicate guard.

Compatibility. No shim means old and new cannot coexist in one deployment. That collides badly with rolling or blue-green deploys: for the duration of the rollout, new instances will reject deliveries if the secret isn't present, and old instances will happily accept forged ones. Per-environment, all-at-once cutover with the secret pre-provisioned is the only safe shape.

Sequencing.

1. Fraud audit first. Reconcile historical orders marked paid against the Paynecta ledger. The 1.x webhook was publicly forgeable; assume the window was open and prove it wasn't exploited rather than assume it wasn't.
2. Disable the 1.x webhook route in all environments.
3. Provision v2 credentials and signing secret into every environment, including local and CI.
4. Build the adapter and the webhook handler; write contract tests for checkout creation and duplicate delivery.
5. Run against sandbox; verify signature rejection on tampered body, stale timestamp, and missing secret.
6. php artisan paynecta:register in staging, then production, as a reviewed deploy step.
7. Parallel run: take live webhooks while reconciling against transactions daily.
8. Decommission 1.x config, keys, and the stored mobile_number column.

Operational Impact

Maintenance. Expect vendor-driven breaking releases. Pin the version, watch the repository, and budget an annual review. Removing vendor/ from the repository is correct and improves us — provided nobody has patched vendored files locally. That check is worth doing before the upgrade, because any local patch is now invisible and lost. CI must run composer install from composer.json on every build; confirm it does.

Support. This is a small vendor with one demonstrated critical security defect and one operational incident that got a shortcode flagged. We should not assume responsive support. Mitigations: keep the reconciliation job as a standing safety net so we detect divergence without vendor help, and maintain an abstraction boundary in our code so replacing the gateway is a bounded piece of work rather than a rewrite.

Scaling. The synchronous checkout call is the scaling constraint, not the webhook path. Webhooks are cheap once verification happens at the edge and processing is queued. Watch for duplicate and out-of-order deliveries under retry; the order state machine must treat transitions as idempotent and refuse backwards moves.

Failure modes to instrument explicitly.

The register-not-run failure deserves emphasis: it is exactly the mistake this release was designed to prevent, and the reconciliation job is the only thing that will catch it.

Ramp-up. A mid-level Laravel developer should reach a working integration in roughly one sprint using the README diffs and the endpoint list. Add a second sprint for the parts the package does not cover — order state machine, idempotency, reconciliation, alerting, and the fraud audit — and treat those as mandatory, not stretch. Time the cutover against a low-traffic window, because a failed webhook cutover is measured in unshipped orders.