Saferpay Laravel Package

Getting Started

Treat payment/saferpay as a legacy integration only. Before writing application code, inspect vendor/payment/saferpay: composer.json for PHP/Laravel constraints, README for credentials and endpoint names, src/ for the client/service classes, and any tests/ or examples/ for the intended flow.

Minimal setup:

1. Install with a pinned PHP/platform configuration if necessary: composer require payment/saferpay
2. Check whether the package ships a Laravel service provider or facade. If not, bind its client class yourself in AppServiceProvider.
3. Put credentials in config/services.php and .env, not in code. Expect Saferpay-style values such as customer ID, terminal ID, username/password, and sandbox/production base URL; use the exact names from the package README.
4. Start against the Saferpay test environment with a single payment flow: initialize a payment, redirect the customer, handle the return URL, authorize/capture, and persist the transaction reference and status.

The first useful use case is a one-off card payment in sandbox. Build a tiny route/controller that creates an order record, calls the package to initialize payment, redirects to the returned payment URL, then verifies the return and records the result. Do not start with refunds, stored cards, or partial captures.

Implementation Patterns

Wrap the package behind an application-owned gateway interface, for example App\Payments\SaferpayGateway. Controllers and jobs should depend on that interface, not on payment/saferpay classes directly. This keeps the archived dependency replaceable and makes testing possible.

Typical workflow:

1. Create a local payment/order record before calling Saferpay.
2. Generate your own idempotency/order reference and store it with the payment.
3. Initialize the transaction through the package and persist the Saferpay transaction ID/token immediately.
4. Redirect the customer to the payment page URL returned by Saferpay.
5. On return, reload the local payment by reference, verify amount/currency/order reference server-side, then authorize or capture according to the package flow.
6. Store the final status, raw response, and relevant transaction identifiers.
7. Run capture, refund, and reconciliation as separate operations with explicit state transitions such as initialized, authorized, captured, failed, refunded.

Laravel integration tips:

• Bind the gateway as a singleton in a service provider if the package client is stateless.
• Keep package configuration in config/services.php; avoid calling env() outside config files.
• Use a database transaction around local state changes, but never around the remote HTTP call.
• Put capture/refund calls in queued jobs with retries only where idempotency is guaranteed.
• For tests, implement a fake gateway and assert your application state machine. Add a small sandbox contract test for the real package, but do not run it in normal CI unless credentials are isolated.
• If the package exposes events or exceptions, normalize them into your own domain events/exceptions so the rest of the app stays independent.

Gotchas and Tips

• This package is archived and last released in 2016. Saferpay APIs, authentication, endpoints, and regulatory requirements have changed since then. Verify every endpoint and field against current Saferpay documentation before relying on it.
• Modern PHP/Laravel dependency conflicts are likely. Prefer isolating the package in a small service or forking it rather than forcing old dependencies into a current application.
• Do not assume the package supports current PSD2/SCA/3-D Secure requirements. Payment flows that worked in 2016 may fail or be non-compliant now.
• Check how the package reports errors. Old payment clients often return HTTP 200 with an error body, or throw generic exceptions. Log the full response and any request/transaction IDs, but redact credentials and card data.
• Verify return URLs and webhook/callback payloads server-side. Do not trust amount, currency, order reference, or success status from query parameters alone.
• Amounts are often in minor units. Confirm the expected currency exponent and whether the package or Saferpay expects cents.
• Avoid blind retries for initialize, capture, and refund calls unless you have an idempotency strategy. Duplicate captures/refunds are expensive to reconcile.
• Store Saferpay transaction IDs and your own order references. You will need both for support, reconciliation, and refunds.
• Test sandbox and production configuration separately. Clear Laravel config cache after changing credentials or endpoints.
• If the package hardcodes cURL options, endpoints, or XML/JSON shapes, use its client as a reference and implement a thin adapter around the HTTP calls rather than scattering workarounds.
• Keep the dependency behind your own interface. The best day-to-day leverage here is containment: use it only where necessary, and make replacing it with the official SDK or a maintained fork a small change.