# agorapay/php-sdk architecture

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

- Interactive diagram: https://gitdiagram.com/agorapay/php-sdk
- Repository: https://github.com/agorapay/php-sdk

## Overview

1. **What this repository is**
   - This is a **PHP SDK/client library** for the CAPSPAYMENT REST API, not a server application.
   - Its purpose is to let PHP applications call CAPSPAYMENT endpoints through typed objects and service-specific facades.

2. **Top-level shape**
   - The repo is centered under the `CAPSPaymentApi/` namespace.
   - The package is distributed as a Composer library with autoloading via `vendor/autoload.php`.
   - `Main.php` is the main entry point for consumers.

3. **Primary runtime boundary**
   - The SDK targets **PHP 7.2+** and depends on **cURL** for HTTP calls.
   - All external communication goes over HTTPS/HTTP to a configured CAPSPAYMENT base URL.

4. **Core orchestration layer**
   - `Main` appears to assemble the client and expose domain services such as `PayIn`, `PaymentAccount`, `Payout`, `Transfer`, `AccountHolder`, `Selfcare`, `Mandate`, `PaymentMethod`, and `Operation`.
   - `Librairies/ApiBase.php` is the transport/service base class, and `Librairies/Configuration.php` holds shared runtime settings like base URL and authentication token parameters.

5. **Domain service facades**
   - The `Api*.php` files represent endpoint groupings, each likely wrapping a family of REST routes.
   - The architecture is organized by business capability rather than by low-level HTTP concerns:
     - Payin flow
     - Payment accounts
     - Payouts
     - Transfers
     - Account holder lifecycle
     - Selfcare initialization
     - Mandate management
     - Payment method lookup and alias/IBAN operations
     - Operations reporting/listing

6. **Request/response model layer**
   - Most other PHP classes are **DTOs / payload objects** for request bodies and parsed responses.
   - Examples include `Amount`, `Payer`, `Details`, `RegisterPerson`, `RegisterAccount`, `CreatePayoutsOptions`, `CreateTransfersOptions`, `PaymentPayinsOptions`, and many others.
   - This suggests a strongly model-driven SDK where consumers construct structured objects instead of raw arrays.

7. **Enum and constraint layer**
   - The many `Enum*.php` files define the allowed values for API fields such as operation type/status, payment method type, role, gender, report format/type, ticket type/side/format, and transaction status.
   - These enums are part of the contract boundary and encode CAPSPAYMENT-specific vocabulary in the client.

8. **Authentication and request flow**
   - The README shows a two-step configuration: set `BaseUrl`, then configure token acquisition with `TokenUrl`, `TokenUser`, and `TokenPassword`.
   - That implies the SDK first obtains an auth token and then uses it for subsequent API requests.
   - The actual token retrieval and HTTP header wiring are likely handled centrally in `ApiBase` and `Configuration`.

9. **Business capability groupings**
   - The SDK’s largest surface area is around **payin** and **account holder** workflows, which include payment creation, capture/cancel/refund, mandate creation, onboarding, registration details, and document upload.
   - Secondary flows include **payment accounts** (IBAN, overdraft, floor limits, reports, credits), **payouts/transfers**, and **payment method management** (alias and IBAN retrieval/removal).

10. **Data flow pattern**
   - Typical flow is: consumer creates one or more option/DTO objects → calls a service method on `Main` → SDK serializes payloads, sends an authenticated REST request, and returns a response object or raw response structure.
   - The README examples show nested payload composition, such as `Amount` + `Payer` + `TransPaymentMethod` inside a payin or mandate request.

11. **Notable integration points**
   - The SDK is meant to be embedded in another PHP system; it does not provide its own UI or persistence layer.
   - The only external dependency visible from the repository shape is the CAPSPAYMENT API itself, plus Composer/cURL for runtime packaging and transport.

12. **Practical architecture diagram takeaway**
   - A good diagram would show:
     - a consumer PHP application
     - the `Main` SDK entry point
     - a shared config/auth/HTTP core
     - multiple domain API facades
     - DTO/enums as the model layer feeding requests
     - the external CAPSPAYMENT REST service as the backend boundary.

Main entry points: [`CAPSPaymentApi/Main.php`](https://github.com/agorapay/php-sdk/blob/main/CAPSPaymentApi/Main.php) (Main), [`CAPSPaymentApi/EnumOperationType.php`](https://github.com/agorapay/php-sdk/blob/main/CAPSPaymentApi/EnumOperationType.php) (Enums), [`CAPSPaymentApi/Amount.php`](https://github.com/agorapay/php-sdk/blob/main/CAPSPaymentApi/Amount.php) (Payment models), [`CAPSPaymentApi/ApiPayIns.php`](https://github.com/agorapay/php-sdk/blob/main/CAPSPaymentApi/ApiPayIns.php) (PayIns)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_external["External boundary"]
  node_consumer["PHP app<br/>client"]
  node_caps_api[("CAPSPAYMENT API<br/>rest backend")]
end

subgraph group_sdk["SDK core"]
  node_main["Main<br/>entrypoint<br/>[Main.php]"]
  node_config["Configuration<br/>runtime config<br/>[Configuration.php]"]
  node_api_base["ApiBase<br/>http transport<br/>[ApiBase.php]"]
end

subgraph group_facades["Domain facades"]
  node_payins_api["PayIns<br/>payin facade<br/>[ApiPayIns.php]"]
  node_accounts_api["PaymentAccounts<br/>account facade"]
  node_payouts_api["Payouts<br/>payout facade<br/>[ApiPayouts.php]"]
  node_transfers_api["Transfers<br/>transfer facade<br/>[ApiTransferts.php]"]
  node_holder_api["AccountHolder<br/>onboarding facade"]
  node_selfcare_api["Selfcare<br/>init facade<br/>[ApiSelfcare.php]"]
  node_mandate_api["Mandate<br/>[ApiMandate.php]"]
  node_method_api["PaymentMethod<br/>method facade"]
  node_ops_api["Operations<br/>reporting facade<br/>[ApiOperations.php]"]
end

subgraph group_models["Models"]
  node_payin_opts["Payin options<br/>request DTOs"]
  node_account_opts["Account options<br/>request DTOs"]
  node_holder_models["Holder models<br/>person DTOs<br/>[RegisterPerson.php]"]
  node_payment_models["Payment models<br/>payload DTOs<br/>[Amount.php]"]
end

subgraph group_enums["Enums"]
  node_enum_models{{"Enums<br/>constraints"}}
end

node_consumer -->|"uses"| node_main
node_main -->|"configures"| node_config
node_main -->|"creates"| node_api_base
node_api_base -->|"calls"| node_caps_api
node_main -->|"exposes"| node_payins_api
node_main -->|"exposes"| node_accounts_api
node_main -->|"exposes"| node_payouts_api
node_main -->|"exposes"| node_transfers_api
node_main -->|"exposes"| node_holder_api
node_main -->|"exposes"| node_selfcare_api
node_main -->|"exposes"| node_mandate_api
node_main -->|"exposes"| node_method_api
node_main -->|"exposes"| node_ops_api
node_payins_api -->|"accepts"| node_payin_opts
node_payins_api -->|"builds with"| node_payment_models
node_accounts_api -->|"accepts"| node_account_opts
node_holder_api -->|"accepts"| node_holder_models
node_mandate_api -->|"accepts"| node_payment_models
node_method_api -->|"uses"| node_payment_models
node_ops_api -->|"filters by"| node_enum_models
node_payin_opts -->|"constrains"| node_enum_models
node_account_opts -->|"constrains"| node_enum_models
node_holder_models -->|"constrains"| node_enum_models
node_payment_models -->|"constrains"| node_enum_models

click node_main "https://github.com/agorapay/php-sdk/blob/main/CAPSPaymentApi/Main.php"
click node_config "https://github.com/agorapay/php-sdk/blob/main/CAPSPaymentApi/Librairies/Configuration.php"
click node_api_base "https://github.com/agorapay/php-sdk/blob/main/CAPSPaymentApi/Librairies/ApiBase.php"
click node_payins_api "https://github.com/agorapay/php-sdk/blob/main/CAPSPaymentApi/ApiPayIns.php"
click node_accounts_api "https://github.com/agorapay/php-sdk/blob/main/CAPSPaymentApi/ApiPaymentAccounts.php"
click node_payouts_api "https://github.com/agorapay/php-sdk/blob/main/CAPSPaymentApi/ApiPayouts.php"
click node_transfers_api "https://github.com/agorapay/php-sdk/blob/main/CAPSPaymentApi/ApiTransferts.php"
click node_holder_api "https://github.com/agorapay/php-sdk/blob/main/CAPSPaymentApi/ApiAccountHolder.php"
click node_selfcare_api "https://github.com/agorapay/php-sdk/blob/main/CAPSPaymentApi/ApiSelfcare.php"
click node_mandate_api "https://github.com/agorapay/php-sdk/blob/main/CAPSPaymentApi/ApiMandate.php"
click node_method_api "https://github.com/agorapay/php-sdk/blob/main/CAPSPaymentApi/ApiPaymentMethod.php"
click node_ops_api "https://github.com/agorapay/php-sdk/blob/main/CAPSPaymentApi/ApiOperations.php"
click node_payin_opts "https://github.com/agorapay/php-sdk/blob/main/CAPSPaymentApi/PaymentPayinsOptions.php"
click node_account_opts "https://github.com/agorapay/php-sdk/blob/main/CAPSPaymentApi/PaymentAccountOptions.php"
click node_holder_models "https://github.com/agorapay/php-sdk/blob/main/CAPSPaymentApi/RegisterPerson.php"
click node_payment_models "https://github.com/agorapay/php-sdk/blob/main/CAPSPaymentApi/Amount.php"
click node_enum_models "https://github.com/agorapay/php-sdk/blob/main/CAPSPaymentApi/EnumOperationType.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_consumer,node_caps_api toneBlue
class node_main,node_config,node_api_base toneAmber
class node_payins_api,node_accounts_api,node_payouts_api,node_transfers_api,node_holder_api,node_selfcare_api,node_mandate_api,node_method_api,node_ops_api toneMint
class node_payin_opts,node_account_opts,node_holder_models,node_payment_models toneRose
class node_enum_models toneIndigo
```

## Components

### External boundary

Consuming PHP applications and the CAPSPAYMENT REST API.

- **PHP app**: client · Embedding application that uses the SDK.
- **CAPSPAYMENT API**: rest backend · External REST service called over HTTP(S).

### SDK core

Package entrypoint, configuration, and shared transport.

- [Main](https://github.com/agorapay/php-sdk/blob/main/CAPSPaymentApi/Main.php): entrypoint · Primary SDK entrypoint exposed to consumers. · `CAPSPaymentApi/Main.php`
- [Configuration](https://github.com/agorapay/php-sdk/blob/main/CAPSPaymentApi/Librairies/Configuration.php): runtime config · Base URL and authentication settings. · `CAPSPaymentApi/Librairies/Configuration.php`
- [ApiBase](https://github.com/agorapay/php-sdk/blob/main/CAPSPaymentApi/Librairies/ApiBase.php): http transport · Shared request execution and auth/header wiring. · `CAPSPaymentApi/Librairies/ApiBase.php`

### Domain facades

Service-level API wrappers grouped by business capability.

- [PayIns](https://github.com/agorapay/php-sdk/blob/main/CAPSPaymentApi/ApiPayIns.php): payin facade · Create, capture, cancel, refund, reload, and mandate payin operations. · `CAPSPaymentApi/ApiPayIns.php`
- [PaymentAccounts](https://github.com/agorapay/php-sdk/blob/main/CAPSPaymentApi/ApiPaymentAccounts.php): account facade · IBAN, overdraft, floor limit, credit, reports, and account actions. · `CAPSPaymentApi/ApiPaymentAccounts.php`
- [Payouts](https://github.com/agorapay/php-sdk/blob/main/CAPSPaymentApi/ApiPayouts.php): payout facade · Payout creation and payout account settings. · `CAPSPaymentApi/ApiPayouts.php`
- [Transfers](https://github.com/agorapay/php-sdk/blob/main/CAPSPaymentApi/ApiTransferts.php): transfer facade · Transfer creation and related operations. · `CAPSPaymentApi/ApiTransferts.php`
- [AccountHolder](https://github.com/agorapay/php-sdk/blob/main/CAPSPaymentApi/ApiAccountHolder.php): onboarding facade · Registration, updates, documents, and lifecycle management. · `CAPSPaymentApi/ApiAccountHolder.php`
- [Selfcare](https://github.com/agorapay/php-sdk/blob/main/CAPSPaymentApi/ApiSelfcare.php): init facade · Selfcare initialization flow. · `CAPSPaymentApi/ApiSelfcare.php`
- [Mandate](https://github.com/agorapay/php-sdk/blob/main/CAPSPaymentApi/ApiMandate.php): mandate facade · Mandate creation and updates. · `CAPSPaymentApi/ApiMandate.php`
- [PaymentMethod](https://github.com/agorapay/php-sdk/blob/main/CAPSPaymentApi/ApiPaymentMethod.php): method facade · Alias and IBAN lookup/removal for payment methods. · `CAPSPaymentApi/ApiPaymentMethod.php`
- [Operations](https://github.com/agorapay/php-sdk/blob/main/CAPSPaymentApi/ApiOperations.php): reporting facade · Operation listing and status reporting. · `CAPSPaymentApi/ApiOperations.php`

### Models

DTOs, option objects, and payload builders used to compose requests and parse responses.

- [Payin options](https://github.com/agorapay/php-sdk/blob/main/CAPSPaymentApi/PaymentPayinsOptions.php): request DTOs · Payin request bodies and nested composition objects. · `CAPSPaymentApi/PaymentPayinsOptions.php`
- [Account options](https://github.com/agorapay/php-sdk/blob/main/CAPSPaymentApi/PaymentAccountOptions.php): request DTOs · Payment account actions and report option objects. · `CAPSPaymentApi/PaymentAccountOptions.php`
- [Holder models](https://github.com/agorapay/php-sdk/blob/main/CAPSPaymentApi/RegisterPerson.php): person DTOs · Account holder registration, person, address, and requirement payloads. · `CAPSPaymentApi/RegisterPerson.php`
- [Payment models](https://github.com/agorapay/php-sdk/blob/main/CAPSPaymentApi/Amount.php): payload DTOs · Shared payment payload objects such as amount, payer, metadata, and method details. · `CAPSPaymentApi/Amount.php`

### Enums

Contract values and constrained vocabulary used across requests and responses.

- [Enums](https://github.com/agorapay/php-sdk/blob/main/CAPSPaymentApi/EnumOperationType.php): constraints · Allowed values for types, statuses, roles, formats, and ticket attributes. · `CAPSPaymentApi/EnumOperationType.php`

## Connections

- PHP app → Main: uses · Consumer instantiates the SDK entrypoint.
- Main → Configuration: configures · Main coordinates runtime settings.
- Main → ApiBase: creates · Main relies on the shared transport base.
- ApiBase → CAPSPAYMENT API: calls · Central HTTP layer sends authenticated requests to the API.
- Main → PayIns: exposes · Facade available through the main entrypoint.
- Main → PaymentAccounts: exposes · Facade available through the main entrypoint.
- Main → Payouts: exposes · Facade available through the main entrypoint.
- Main → Transfers: exposes · Facade available through the main entrypoint.
- Main → AccountHolder: exposes · Facade available through the main entrypoint.
- Main → Selfcare: exposes · Facade available through the main entrypoint.
- Main → Mandate: exposes · Facade available through the main entrypoint.
- Main → PaymentMethod: exposes · Facade available through the main entrypoint.
- Main → Operations: exposes · Facade available through the main entrypoint.
- PayIns → Payin options: accepts · Payin facade consumes specialized option objects.
- PayIns → Payment models: builds with · Payin requests are composed from shared payload DTOs.
- PaymentAccounts → Account options: accepts · Payment account facade consumes account options.
- AccountHolder → Holder models: accepts · Account holder facade uses registration DTOs.
- Mandate → Payment models: accepts · Mandate flow reuses shared payment payloads.
- PaymentMethod → Payment models: uses · Payment method lookup/removal is parameterized by SDK payload objects.
- Operations → Enums: filters by · Operation queries rely on status/type/value constraints.
- Payin options → Enums: constrains · Option objects use enums for allowed field values.
- Account options → Enums: constrains · Account operations use enums for report and account settings.
- Holder models → Enums: constrains · Registration models encode role, gender, and requirement vocabularies.
- Payment models → Enums: constrains · Shared payload objects use enums for payment and transaction states.
