Paynecta Laravel Sdk Laravel Package

Getting Started

Treat v2.0.0 as a new integration, not an upgrade. Version 1.x is not merely deprecated — the API host it called returns 404 and the header-based auth it used no longer exists, so any 1.x code path is dead on arrival. If payments "just stopped," that is the whole explanation.

Order of work:

1. Read the three diffs in the README before touching code. They correspond to the three real changes: new authentication, no caller-supplied phone number, and verified webhooks. Everything else is additive.
2. composer require the new major, publish the config, and set credentials plus the webhook signing secret. The secret is not optional — without it every delivery is refused, which is the correct default but an easy thing to misdiagnose as "webhooks are broken."
3. Run php artisan paynecta:register. This registers the webhook endpoint from the application rather than from the dashboard, which removes the step people skip and the resulting failure mode (taking payments, hearing nothing back). It needs a publicly reachable URL, so plan for a tunnel locally.
4. Smoke-test with the read-only surface before moving money: whoami then balance. Both are side-effect free and confirm auth, base URL, and credentials in one call.

First real use case: create a checkout, redirect the customer to Paynecta's hosted page, let them enter and code-confirm their own number there, and let the webhook mark the order paid. That redirect-shaped flow is the intended path now.

Implementation Patterns

Authentication is configuration, not code. Credentials live in config/env and are applied by the client. Nothing in your application should be assembling auth headers per request. Consequence: everything must survive php artisan config:cache, so no env() calls outside config files, and per-environment credentials must be genuinely per-environment.

Hosted checkout, not prompt-push. The absence of any phone-number parameter is the defining design change. Your checkout no longer collects an MSISDN and fires a prompt; you hand off to Paynecta's page and the customer confirms their own number with a code. Design the UI for a customer leaving your app: persist the pending order and checkout reference before redirecting, and make the return path (and the "user closed the tab" path) resolve to a status page rather than a dead end. Delete any phone-number field from your forms — it has nowhere to go and collecting it invites the exact abuse that got the shortcode flagged.

Webhook route → verify → 200 → queue. Keep the HTTP handler to three things: verify the signature over the raw body, persist or dispatch the event, return 200 immediately. Business logic (marking orders paid, fulfilment, emails) belongs in a queued job keyed on an idempotency key — the transaction or event id — because deliveries retry.

Reconcile, don't trust the webhook alone. Add a scheduled job that polls transactions for checkouts still pending after N minutes. This is now straightforward because the transaction endpoints exist as a real resource; it also covers rejected-as-stale deliveries and your own downtime.

Wrap the client. Put the package behind a small service of your own (Payments::startCheckout($order)) so domain code never imports vendor classes directly. This pays off at the next major, which — as demonstrated — will not be shimmed.

Use the ops endpoints. banks, balance, integrations, and whoami are not payment-path calls; they are the makings of an admin status panel and a low-balance alert. balance on a schedule is the cheapest insurance in the package.

Registration belongs in the pipeline. Run paynecta:register as a deploy step per environment, with separate secrets for staging and production, so a rotated or newly provisioned environment cannot silently end up unregistered.

Gotchas and Tips

Fail-closed is the right default and a terrible debugging experience. With no signing secret, every delivery is refused and your application sees nothing at all — no error, no order. Log verification failures with enough context to distinguish "no secret configured" from "bad signature" from "stale timestamp," and alert on any nonzero rate.

Verify the raw bytes. Compute the HMAC over $request->getContent() and the timestamp header, not over a decoded-and-re-encoded array. Any middleware that mutates or consumes the body, or a habit of json_decode/json_encode before verification, will produce a correct-looking implementation that never validates.

The five-minute window is tighter than it looks. Container clock drift, a host without NTP, and — importantly — retries that replay the original timestamp will all read as expired. Do not treat a stale-but-well-formed delivery as an attack; treat it as a reconciliation trigger.

Use hash_equals. Never compare signatures with == or ===. And keep the secret and the computed digest out of your logs; signature debugging output is a credential leak waiting for a log aggregator.

Signature verification does not prevent replay. Within the five-minute window a captured delivery is still valid. Enforce idempotency on event or transaction id at the persistence layer.

Audit your 1.x history. Previously, anyone who knew the webhook URL could POST a payment.completed to a fixed, unauthenticated route and have an order marked paid and shipped. Query orders marked paid before the upgrade and reconcile each against transactions in the API. Where there is no matching transaction, you have a fraud or test-data problem, not a bug. If you ever shipped 1.x with caller-supplied numbers, review outbound-prompt logs for the same period.

Mind where the webhook route lives. It must be outside auth, but it also must not sit in a group that applies session or CSRF middleware — a 419 on a POST from Paynecta looks exactly like a signature failure and you will lose an afternoon to it.

vendor/ is gone from the repo. Anything that copied a committed vendor/ tree, or patched a file inside it, breaks. Run composer install in every environment and stop treating the package as editable — extend via the container binding and config, not by editing vendor files.

No shim means delete, don't adapt. Grep for the old client class and the X-API-Key / X-User-Email headers and remove them. A compatibility layer is dead code against withdrawn endpoints.

Local testing is fiddly by design. You need a public HTTPS URL for registration and a hand-rolled signer for manual curl work; build that signer once as a test helper. The package's eight webhook tests — five of which fail against 1.x behaviour — are a good template for your own verification test, and writing that test first is the fastest way to confirm your secret is actually wired up.

Overall: the security posture is now defensible where it previously was not, and the register command plus full endpoint coverage make it a viable day-to-day dependency rather than a liability. The cost is a hard cutover with no gradual path; budget for a clean re-integration, not a version bump.