hyperpayopensource/hyperpay-ptsp-php-lib

Purpose and Entry Points

This is a PHP 8.1+ client library for Hyperpay PTSP payment-link APIs. Consumers either use the Laravel facade at src/Facades/Hyperpay.php or instantiate src/HyperpayPtspService.php directly. examples/basic.php demonstrates standalone/direct-service use.

Laravel Integration Boundary

src/HyperpayPtspServiceProvider.php registers package services and supports publishing config/hyperpay-ptsp.php. The facade in src/Facades/Hyperpay.php is the Laravel-oriented public API, resolving the underlying service rather than exposing HTTP details to application code.

Configuration and Environments

src/Config.php centralizes credentials, environment selection, base URLs, and request timeout. It can source Laravel configuration or environment variables; published defaults reside in config/hyperpay-ptsp.php. Production and sandbox selection determines the Hyperpay PTSP endpoint, while Basic Auth credentials are required for payment-link operations.

Core PTSP Service

src/HyperpayPtspService.php is the integration boundary with the external Hyperpay PTSP API. It uses Laravel’s HTTP client (illuminate/http) to:

• create payment links;

• retrieve payment status by merchant reference;

• retrieve payment-link details using a link token plus x-api-key.

The service owns request construction, Basic Auth/API-key headers, timeout behavior, response parsing, and conversion of API/transport failures into the package exception.

Typed API Contract

DTOs separate caller input and provider response payloads:

• Creation input: src/Dto/CreatePaymentLinkRequest.php

• Creation result: src/Dto/CreatePaymentLinkResponse.php

• Status result: src/Dto/PaymentStatusResponse.php

• Token lookup result: src/Dto/PaymentLinkResponse.php

Primary flow: caller populates CreatePaymentLinkRequest → HyperpayPtspService serializes and posts it → Hyperpay response is mapped into CreatePaymentLinkResponse. Lookup flows accept identifiers/credentials and map returned payloads into their corresponding response DTOs.

Error Model

src/HyperpayPtspException.php is the single package-level error boundary. Validation errors, non-success API results, and HTTP failures are surfaced as this exception, preserving PTSP response codes/messages and field-level validation context where available. Consumers should catch this type at the application boundary.

Runtime and External Dependencies

The package runs as a Composer PHP library (composer.json) and depends materially on Laravel’s HTTP client, but can be called directly outside Laravel when configuration is supplied. Its only described external service is Hyperpay PTSP over HTTPS: production ptsp.hyperpay.com or sandbox ptsp-stg.hyperpay.com.