# hyperpayopensource/hyperpay-ptsp-php-lib architecture

> Architecture diagram of the GitHub repository hyperpayopensource/hyperpay-ptsp-php-lib, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hyperpayopensource/hyperpay-ptsp-php-lib
- Repository: https://github.com/hyperpayopensource/hyperpay-ptsp-php-lib

## Overview

#### 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`.

Main entry points: [`src/HyperpayPtspService.php`](https://github.com/hyperpayopensource/hyperpay-ptsp-php-lib/blob/master/src/HyperpayPtspService.php) (PTSP service), [`src/HyperpayPtspServiceProvider.php`](https://github.com/hyperpayopensource/hyperpay-ptsp-php-lib/blob/master/src/HyperpayPtspServiceProvider.php) (Service provider), [`src/Facades/Hyperpay.php`](https://github.com/hyperpayopensource/hyperpay-ptsp-php-lib/blob/master/src/Facades/Hyperpay.php) (Hyperpay facade), [`config/hyperpay-ptsp.php`](https://github.com/hyperpayopensource/hyperpay-ptsp-php-lib/blob/master/config/hyperpay-ptsp.php) (Published defaults)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_laravel["Laravel integration"]
  node_provider["Service provider<br/>Laravel provider"]
  node_facade["Hyperpay facade<br/>Laravel facade<br/>[Hyperpay.php]"]
  node_published_config["Published defaults<br/>Laravel config<br/>[hyperpay-ptsp.php]"]
end

subgraph group_package["PTSP client library"]
  node_service["PTSP service<br/>API client"]
  node_config["Configuration<br/>settings<br/>[Config.php]"]
  node_create_request["Create-link request<br/>input DTO"]
  node_create_response["Create-link response<br/>result DTO"]
  node_status_response["Payment-status response<br/>result DTO"]
  node_link_response["Payment-link response<br/>result DTO"]
  node_exception{{"PTSP exception<br/>package exception"}}
  node_laravel_http["Laravel HTTP client<br/>HTTP dependency"]
end

subgraph group_external["External API"]
  node_hyperpay{{"Hyperpay PTSP<br/>payment-link API"}}
end

node_consumer(("Application consumer<br/>caller"))
node_example["Direct-use example<br/>[basic.php]"]

node_consumer -->|"Laravel API"| node_facade
node_consumer -->|"direct use"| node_service
node_example -.->|"demonstrates"| node_service
node_provider -->|"registers"| node_service
node_provider -->|"publishes"| node_published_config
node_facade -->|"resolves"| node_service
node_published_config -.->|"defaults"| node_config
node_config -->|"credentials, endpoint, timeout"| node_service
node_create_request -->|"create input"| node_service
node_service -->|"maps create result"| node_create_response
node_service -->|"maps status lookup"| node_status_response
node_service -->|"maps token lookup"| node_link_response
node_service -->|"normalizes failures"| node_exception
node_service -->|"uses"| node_laravel_http
node_laravel_http -->|"HTTPS requests"| node_hyperpay
node_exception -.->|"caught by"| node_consumer

click node_example "https://github.com/hyperpayopensource/hyperpay-ptsp-php-lib/blob/master/examples/basic.php"
click node_provider "https://github.com/hyperpayopensource/hyperpay-ptsp-php-lib/blob/master/src/HyperpayPtspServiceProvider.php"
click node_facade "https://github.com/hyperpayopensource/hyperpay-ptsp-php-lib/blob/master/src/Facades/Hyperpay.php"
click node_published_config "https://github.com/hyperpayopensource/hyperpay-ptsp-php-lib/blob/master/config/hyperpay-ptsp.php"
click node_service "https://github.com/hyperpayopensource/hyperpay-ptsp-php-lib/blob/master/src/HyperpayPtspService.php"
click node_config "https://github.com/hyperpayopensource/hyperpay-ptsp-php-lib/blob/master/src/Config.php"
click node_create_request "https://github.com/hyperpayopensource/hyperpay-ptsp-php-lib/blob/master/src/Dto/CreatePaymentLinkRequest.php"
click node_create_response "https://github.com/hyperpayopensource/hyperpay-ptsp-php-lib/blob/master/src/Dto/CreatePaymentLinkResponse.php"
click node_status_response "https://github.com/hyperpayopensource/hyperpay-ptsp-php-lib/blob/master/src/Dto/PaymentStatusResponse.php"
click node_link_response "https://github.com/hyperpayopensource/hyperpay-ptsp-php-lib/blob/master/src/Dto/PaymentLinkResponse.php"
click node_exception "https://github.com/hyperpayopensource/hyperpay-ptsp-php-lib/blob/master/src/HyperpayPtspException.php"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_provider,node_facade,node_published_config toneBlue
class node_service,node_config,node_create_request,node_create_response,node_status_response,node_link_response,node_exception,node_laravel_http toneAmber
class node_hyperpay toneMint
class node_consumer,node_example toneNeutral
```

## Components

### Laravel integration

- [Service provider](https://github.com/hyperpayopensource/hyperpay-ptsp-php-lib/blob/master/src/HyperpayPtspServiceProvider.php): Laravel provider · Registers package services and publishes defaults. · `src/HyperpayPtspServiceProvider.php`
- [Hyperpay facade](https://github.com/hyperpayopensource/hyperpay-ptsp-php-lib/blob/master/src/Facades/Hyperpay.php): Laravel facade · Laravel-oriented public API resolving the service. · `src/Facades/Hyperpay.php`
- [Published defaults](https://github.com/hyperpayopensource/hyperpay-ptsp-php-lib/blob/master/config/hyperpay-ptsp.php): Laravel config · `config/hyperpay-ptsp.php`

### PTSP client library

- [PTSP service](https://github.com/hyperpayopensource/hyperpay-ptsp-php-lib/blob/master/src/HyperpayPtspService.php): API client · Builds requests, authenticates, parses responses, and normalizes failures. · `src/HyperpayPtspService.php`
- [Configuration](https://github.com/hyperpayopensource/hyperpay-ptsp-php-lib/blob/master/src/Config.php): settings · Resolves credentials, environment endpoint, and timeout. · `src/Config.php`
- [Create-link request](https://github.com/hyperpayopensource/hyperpay-ptsp-php-lib/blob/master/src/Dto/CreatePaymentLinkRequest.php): input DTO · `src/Dto/CreatePaymentLinkRequest.php`
- [Create-link response](https://github.com/hyperpayopensource/hyperpay-ptsp-php-lib/blob/master/src/Dto/CreatePaymentLinkResponse.php): result DTO · `src/Dto/CreatePaymentLinkResponse.php`
- [Payment-status response](https://github.com/hyperpayopensource/hyperpay-ptsp-php-lib/blob/master/src/Dto/PaymentStatusResponse.php): result DTO · `src/Dto/PaymentStatusResponse.php`
- [Payment-link response](https://github.com/hyperpayopensource/hyperpay-ptsp-php-lib/blob/master/src/Dto/PaymentLinkResponse.php): result DTO · `src/Dto/PaymentLinkResponse.php`
- [PTSP exception](https://github.com/hyperpayopensource/hyperpay-ptsp-php-lib/blob/master/src/HyperpayPtspException.php): package exception · Single error boundary for validation, API, and transport failures. · `src/HyperpayPtspException.php`
- **Laravel HTTP client**: HTTP dependency

### External API

- **Hyperpay PTSP**: payment-link API · Production or sandbox HTTPS endpoint.

### Other components

- **Application consumer**: caller · Uses the facade or service and catches package exceptions.
- [Direct-use example](https://github.com/hyperpayopensource/hyperpay-ptsp-php-lib/blob/master/examples/basic.php): example · `examples/basic.php`

## Connections

- Application consumer → Hyperpay facade: Laravel API
- Application consumer → PTSP service: direct use
- Direct-use example → PTSP service: demonstrates
- Service provider → PTSP service: registers
- Service provider → Published defaults: publishes
- Hyperpay facade → PTSP service: resolves
- Published defaults → Configuration: defaults
- Configuration → PTSP service: credentials, endpoint, timeout
- Create-link request → PTSP service: create input
- PTSP service → Create-link response: maps create result
- PTSP service → Payment-status response: maps status lookup
- PTSP service → Payment-link response: maps token lookup
- PTSP service → PTSP exception: normalizes failures
- PTSP service → Laravel HTTP client: uses
- Laravel HTTP client → Hyperpay PTSP: HTTPS requests · Basic Auth for operations; API key for token lookup.
- PTSP exception → Application consumer: caught by