Hipay Fullservice Sdk Php Laravel Package

Getting Started

hipay/hipay-fullservice-sdk-php is a plain PHP SDK, not a Laravel package. There is no service provider auto-discovery, facade, config file, migration, or artisan command. Treat it as a low-level transport client that you isolate behind a Laravel service.

Minimal setup:

• composer require hipay/hipay-fullservice-sdk-php
• Add config/hipay.php with username, password, endpoint, notification_url, and sandbox/production flags. Read these through config(), not env(), so config caching works.
• Create an adapter such as App\Services\HiPay\HiPayGateway and bind it in a service provider.
• Do not inject the raw SDK client into controllers or Eloquent models.

Where to look first:

• README.md, docs/, and examples/ for the exact request/response shape of your installed version.
• src/HiPay/Fullservice/Gateway/Client/Client.php — the main API client.
• Gateway/Request/Order/OrderRequest.php — the order/payment request DTO.
• Enum/Transaction/TransactionStatus.php — status constants you will map into your own state machine.
• SecureVault/ — card tokenization if you need returning-customer payments.

A good first use case is the Hosted Payment Page:

1. Create a local payments row with a UUID, amount, currency, and pending status.
2. Build an SDK OrderRequest, setting orderid to your local UUID, amount in minor units, currency, description, customer data, and return/notification URLs.
3. Call the SDK hosted-payment method, for example requestHostedPaymentPage() or the version-appropriate equivalent, then redirect the customer to the returned URL.
4. Add a POST /webhooks/hipay route outside CSRF/auth. Queue the webhook, verify the transaction, update your payment, and return 200.

A thin factory keeps credentials in one place:

final class HiPayClientFactory
{
    public function make(): Client
    {
        $client = new Client();
        $client->setCredentials(
            config('hipay.username'),
            config('hipay.password')
        );
        $client->setEndpoint(config('hipay.endpoint'));

        return $client;
    }
}

Implementation Patterns

Wrap the SDK behind an interface. Define your own PaymentGateway contract with methods like startHostedPayment(), capture(), refund(), and fetchTransaction(). Implement it with the HiPay SDK. This gives you a fake for tests and prevents SDK-specific request DTOs from leaking across the app.

Use a local payment state machine. Store at least provider, provider_order_id, provider_transaction_id, status, amount, currency, and a JSON payload. Map HiPay statuses to your own enum instead of scattering raw SDK constants through controllers. Only allow valid transitions such as pending -> authorized -> captured or pending -> declined.

Do not hold a database transaction during the HTTP call. Create the local payment first, commit it, then call HiPay, then update it. This avoids long locks and gives you a record to reconcile if the HTTP call times out.

Treat webhooks as hints, not truth. The notification endpoint should be fast, idempotent, and unauthenticated but CSRF-exempt. Put processing in a queued job. Re-fetch the transaction from HiPay before marking an order paid, and compare amount and currency with your local record. Return 200 for duplicates and unknown orders to stop retries; log unknowns for investigation.

Separate redirect and notification flows. The customer return URL is for UX only. The server-to-server notification is the authoritative event. Never mark an order paid just because the browser returned to your success page.

Model maintenance operations explicitly. Capture, refund, and cancel should be separate service methods with their own persisted operation records. Store the provider operation/transaction reference, request payload, response, and status. If your business allows partial refunds, track each refund as its own row.

Use tokenization for repeat customers. For stored cards, use the Secure Vault/tokenization flow and store only the token, never the PAN. For one-off payments, prefer Hosted Payment Page or hosted fields over posting raw card data to your Laravel backend.

Dispatch domain events after persistence. After a status transition is committed, dispatch events such as PaymentCaptured, PaymentRefused, or RefundCompleted. Listeners can send mail, update fulfilment, or notify internal systems without coupling them to the SDK call.

Log with correlation IDs and redaction. Add order_id, transaction_id, provider, and latency to logs. Redact credentials, card data, and sensitive customer fields. If the SDK exposes a PSR-3 logger hook, adapt Laravel’s logger into it rather than using error_log().

Test with a fake adapter and a small sandbox suite. Most tests should assert that your service builds the right request DTO fields and handles the right response/status. Keep a small integration suite against HiPay sandbox for credential and endpoint validation.

Gotchas and Tips

• It is not Laravel-aware. No facade, no config publishing, no dependency injection. You own the integration layer, so keep it small and boring.
• SDK DTOs are mutable public-property objects. They provide little validation. Typos, wrong types, or missing required fields often fail only at the API. Validate your own input and map arrays to DTOs explicitly.
• Amounts are usually minor units. Send integers, e.g. (int) round($total * 100), and confirm currency exponent rules for non-decimal currencies. Never send floats.
• HTTP 200 does not always mean payment success. Inspect the response status, transaction status, and reason fields. Transport failures may throw; business declines may be returned as response objects. Handle both.
• Endpoint and credential mismatches are common. Sandbox and production credentials and endpoints are different. HPP, API, maintenance, and Secure Vault may need separate configuration depending on your account setup. Centralize this in config.
• Webhook routes need special middleware treatment. Exclude CSRF, exclude auth, allow public access, and avoid redirects. The endpoint must be reachable from HiPay’s servers and return quickly.
• Notifications can arrive more than once and out of order. Enforce idempotency with a unique provider transaction/operation reference. Use lockForUpdate() or an atomic status transition when updating payments.
• 3-D Secure/SCA is not automatic for direct API card payments. Hosted Payment Page handles much of the redirect/authentication flow. Direct card integrations need explicit handling of authentication and pending states.
• Retries can duplicate payments. Retry only idempotent operations or operations with a unique provider-side identifier. For payment creation, use your local UUID as orderid and reconcile before retrying.
• Set sane HTTP timeouts. The SDK uses its own HTTP layer, often Guzzle. If the client allows HTTP client or timeout configuration, set connect/read timeouts. Otherwise wrap calls with your own timeout policy and queue long-running operations.
• Low adoption means you are the integration test. With 11 stars and no dependents, pin the package version, run it in CI against your Laravel/PHP version, and read the changelog before upgrades. Public-property DTOs can change in patch releases more easily than typed APIs.
• Do not log full SDK request bodies in production. Payment payloads may contain customer and card-adjacent data. Use debug logging only in local/sandbox environments and redact before persisting.
• Keep a reconciliation command. Add an artisan command or scheduled job that fetches pending payments from HiPay and updates local status. This is your safety net for missed webhooks and timeouts.