Hipay Fullservice Sdk Php Laravel Package

Technical Evaluation

Architecture fit

HiPay Enterprise (Fullservice) is a full acquiring/payment-gateway integration: card payments, 3-D Secure step-up, captures/refunds, recurring and one-click tokenisation, and alternative/local payment methods. That makes this package an infrastructure dependency on the critical money path, not a utility library — it deserves the same treatment as a database driver, not a convenience import.

The SDK itself is a plain, framework-agnostic PHP library distributed over Composer. There is no Laravel service provider, facade, config file, publishable asset, or contract binding. Architecturally that is neutral-to-good: it can live cleanly behind an application-owned adapter and never leak HiPay types into controllers, models, or domain services. The cost is that every piece of Laravel glue — container binding, config, retries, logging, exception translation, HTTP test doubles — is code we own and must maintain.

Practical consequence: treat it as an anti-corruption layer candidate from day one. The SDK's surface is untyped (arrays/stdClass-style request and response payloads) and the client is instantiated directly, so it will not be swappable later unless we wrap it now.

Integration feasibility

Mechanically straightforward. composer require hipay/hipay-fullservice-sdk-php, a HiPayServiceProvider registering a singleton client built from config/services.php credentials, and a HiPayGateway class implementing an app-level PaymentGateway interface. No published config, no migrations, no middleware, no auto-discovery. A competent Laravel engineer can have sandbox order creation working in a day or two.

Three friction points matter for planning:

1. No PSR-18/PSR-7 or Guzzle underneath. The client performs its own transport calls. This means Http::fake(), Guzzle middleware, Laravel Telescope's HTTP watcher, and standard tracing/retry middleware will not see these calls. Test strategy has to be built at the adapter boundary (fake the PaymentGateway interface) plus a small number of sandbox contract tests. Budget for this explicitly; teams routinely under-scope it.
2. Signature/notification handling is security-critical and ours to implement. HiPay posts asynchronous notifications that must be authenticated and de-duplicated. Getting this wrong produces either silent revenue loss (unprocessed payments) or fraud exposure (forged notifications). Exclude the callback route from CSRF, make it unauthenticated but signature-verified, and make it idempotent.
3. Multi-step flows. 3-D Secure introduces a redirect-out / redirect-in cycle plus a hard requirement to handle the "user never came back" case by polling transaction status. This is state-machine work in our app, not something the SDK does for us.

Technical risk

• License: low. Apache-2.0 is permissive and commercially safe; no copyleft concerns for a closed-source SaaS.
• Supply chain / abandonment: moderate-to-high. 11 stars and zero dependents means effectively a single-maintainer, vendor-published artifact. The most recent tagged release is current, which indicates the vendor still ships, but the only source of fixes and security patches is HiPay. There is no community to catch regressions, no third-party audit trail, and issue triage will be slow.
• Semantic-versioning discipline is unverified. With an effectively captive consumer base, breaking changes in minor releases are plausible. Pin exact versions, commit the lockfile, and read changelogs on every bump.
• Typed-surface risk. Untyped payloads mean field renames or shape changes fail at runtime, not compile time. Guard with response validation at the adapter boundary and alert on parse failures.
• Test-environment drift. Sandbox and production behaviours diverge in payment gateways more than in typical APIs (payment-method availability, 3DS enforcement, risk rules). Sandbox-only confidence is a known trap.

Key questions

• Which PHP versions and extensions (notably ext-curl) does the current release declare, and does that match our target Laravel runtime?
• Does HiPay provide an official support contract/SLA, and is there a named escalation path for production payment incidents?
• What is the documented notification retry policy and timeout, and what does HiPay expect as the acknowledgement response?
• Is our intended flow SAQ A / A-EP (hosted fields or HiPay-hosted page) — i.e. does card data ever touch our servers? This determines PCI scope and is the single biggest cost driver.
• Which payment methods and countries are in scope for launch, and which of those require 3DS2 or additional KYC onboarding?
• Does the vendor publish a deprecation policy, or an upgrade guide for major versions?
• Are idempotency keys supported on order/transaction creation, and what is the deduplication window?

Integration Approach

Stack fit

Compatible with any modern Laravel release, subject to the declared PHP floor. Expect no dependency conflicts: the SDK is largely self-contained and pulls in little beyond cURL and JSON extensions. Register it as a singleton bound to an interface, configured through config/services.php reading from environment variables — never instantiate the SDK client inside a controller, job, or model.

Recommended shape:

• App\Contracts\PaymentGateway — our interface: createPayment, capture, refund, findTransaction.
• App\Payments\HiPay\HiPayGateway — the only class that imports SDK namespaces.
• App\Payments\HiPay\*Mapper — explicit request/response mapping, with validation and normalised DTOs.
• App\Payments\HiPay\HiPayNotificationVerifier — signature verification, isolated and independently unit-testable.
• Domain tables store gateway-agnostic records plus a provider discriminator and the gateway's own reference.

Migration path

If we already have a provider (Stripe, Adyen, Mollie), do not fork the payment code. Introduce the PaymentGateway interface first, wrap the incumbent behind it, ship that refactor with no behaviour change, then add HiPay as a second adapter. This is the difference between a one-week addition and a quarter-long untangling.

If this is greenfield, still define the interface — it costs an hour and buys optionality. Keep HiPay identifiers (order_id, transaction_reference, payment_method token) in a gateway_references JSON column or a dedicated table, and keep our own orders/payments schema free of vendor field names. Route selection per-currency or per-country then becomes configuration, not a rewrite.

Compatibility

• Config via services.php + .env; no vendor:publish step exists.
• No facade, no auto-discovery of anything useful — explicit binding in a service provider.
• Exclude the notification URI in VerifyCsrfToken (or bootstrap/app.php in Laravel 11+); the route must be outside auth middleware.
• Ensure the SDK's own logging does not bypass Laravel's logger or dump credentials; audit for stray error_log/var_dump calls in the vendor tree and consider a Monolog channel with redaction.
• If we run Octane, verify the SDK holds no request-scoped static state in its client — if it does, bind as scoped rather than singleton.

Sequencing

1. Spike (2–3 days). Sandbox credentials, create one order end-to-end with a test card, confirm the 3DS redirect round trip and inspect a real notification payload. De-risks everything downstream.
2. Foundation. Service provider, config, interface, adapter skeleton, DTO mapping, exception translation (HiPayException → our PaymentFailedException with a stable error code).
3. Read path first. Implement findTransaction and wire it to a sandbox call. Cheapest way to validate credentials, transport, auth, and error handling without touching money.
4. Authorisation + 3DS. Order creation, redirect/step-up handling, return-URL controller, state machine with explicit pending / authorised / failed / abandoned states.
5. Notifications. Signed webhook endpoint that verifies, persists idempotently (unique constraint on gateway transaction reference + status), acknowledges fast, and dispatches a queued job for fulfilment. Test with replayed and tampered payloads.
6. Capture, refund, partial refund. Implement behind a queue with retry and a manual reconciliation escape hatch.
7. Hardening. Timeouts, circuit breaker, reconciliation job against HiPay reporting, dashboards and alerts, runbook, and a PaymentGateway fake used by the broader test suite.

Each phase should be independently deployable behind a feature flag, with HiPay enabled only after the reconciliation job has run clean for a full settlement cycle.

Operational Impact

Maintenance

Ongoing maintenance is low-volume but high-consequence: mostly version bumps and payment-method onboarding. Because there is no community, each bump requires reading vendor release notes and re-running sandbox contract tests rather than trusting semver. Pin to an exact version, keep the lockfile committed, and subscribe to HiPay security advisories. Budget roughly 1–2 engineer-days per quarter for dependency hygiene, plus the PCI/3DS2 compliance treadmill, which is a recurring external deadline rather than a discretionary task.

The adapter boundary is the primary maintenance control: if the SDK must be replaced, only the adapter and its tests change. Enforce this with an architecture test (e.g. a Pest/PHPStan rule) that fails if SDK namespaces appear outside App\Payments\HiPay.

Support

Escalation runs entirely through the HiPay account relationship — support portal, account manager, or status page. There is no meaningful community, no Stack Overflow corpus, and no third-party integrators to lean on. This raises the value of internal documentation substantially: record the sandbox test cards, the payment-method matrix, the notification payload shapes, and the exact response body HiPay expects on acknowledgement. When a payment incident occurs at 2 a.m., the runbook is the support organisation.

Contractually, confirm the SLA and whether production incidents are covered by a paid tier before committing volume.

Scaling

The SDK is stateless and synchronous, so it scales horizontally without ceremony. The real constraint is worker occupancy: each gateway call blocks a PHP-FPM or queue worker for the full round trip. With a 30-second default timeout and a slow gateway, a traffic spike can saturate the pool and take down unrelated parts of the app.

Mitigations:

• Aggressive connect/read timeouts (well below PHP's max_execution_time), configured explicitly rather than defaulted.
• Isolate synchronous payment calls from the general web pool where possible; put capture, refund, and reconciliation entirely on queues with backoff.
• Cap concurrency against the gateway — HiPay will rate-limit or degrade, and unthrottled retries turn a blip into an outage.
• Notification endpoints must acknowledge in milliseconds and defer all work to a queue; slow webhooks cause gateway-side retries and duplicate work.

Failure modes

• Unknown-state timeouts. The request may have succeeded while our side timed out. Never treat a timeout as failure — mark pending and reconcile via findTransaction. Auto-retrying order creation without idempotency risks double-charging customers, which is a refund-and-reputation event.
• Duplicate notifications. Gateways retry. Enforce idempotency at the database level (unique index), not in application logic.
• Signature verification failures. Distinguish "forged/ malformed" (reject, alert) from "misconfigured passphrase" (every notification fails silently, orders never fulfilled). Alert on the absence of notifications, not just errors — a silent zero is the dangerous signal.
• Amount/currency precision. Floats in PHP plus gateway minor-unit expectations is a classic source of off-by-one-cent bugs and failed captures. Store integer minor units and convert only at the adapter edge.
• 3DS abandonment and return-URL loss. Users close the tab mid-challenge. Reconciliation must eventually settle these; otherwise orders sit pending forever.
• Sandbox/production config drift. Wrong endpoint or credentials in a deploy is a full payment outage. Fail fast on boot and add a post-deploy smoke check.
• Log leakage. Ensure no tokens, passphrases, or customer PII land in logs or error trackers; the SDK's own debug output is a candidate for redaction.

Ramp-up

Two engineers, roughly two to three sprints to a production-ready card flow with 3DS, notifications, and reconciliation — assuming the sandbox spike goes cleanly. Add one to two sprints if alternative payment methods, recurring/one-click, or partial refunds are in the launch scope, and more if PCI evidence (SAQ A-EP) is required.

Knowledge concentration is the main organisational risk: with no community and thin documentation, exactly two people will understand this integration. Force breadth via pairing on the notification handler and reconciliation job, write the runbook as you build rather than after, and rehearse the "gateway is down" and "notifications stopped" playbooks in staging before go-live.