How agorapay/php-sdk works
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: Main.php Main · EnumOperationType.php Enums · Amount.php Payment models · ApiPayIns.php PayIns
Components 19
External boundary
Consuming PHP applications and the CAPSPAYMENT REST API.
- PHP app · Embedding application that uses the SDK.
- CAPSPAYMENT API · External REST service called over HTTP(S).
SDK core
Package entrypoint, configuration, and shared transport.
- Main · Primary SDK entrypoint exposed to consumers.
CAPSPaymentApi/Main.php - Configuration · Base URL and authentication settings.
CAPSPaymentApi/Librairies/Configuration.php - ApiBase · Shared request execution and auth/header wiring.
CAPSPaymentApi/Librairies/ApiBase.php
Domain facades
Service-level API wrappers grouped by business capability.
- PayIns · Create, capture, cancel, refund, reload, and mandate payin operations.
CAPSPaymentApi/ApiPayIns.php - PaymentAccounts · IBAN, overdraft, floor limit, credit, reports, and account actions.
CAPSPaymentApi/ApiPaymentAccounts.php - Payouts · Payout creation and payout account settings.
CAPSPaymentApi/ApiPayouts.php - Transfers · Transfer creation and related operations.
CAPSPaymentApi/ApiTransferts.php - AccountHolder · Registration, updates, documents, and lifecycle management.
CAPSPaymentApi/ApiAccountHolder.php - Selfcare · Selfcare initialization flow.
CAPSPaymentApi/ApiSelfcare.php - Mandate · Mandate creation and updates.
CAPSPaymentApi/ApiMandate.php - PaymentMethod · Alias and IBAN lookup/removal for payment methods.
CAPSPaymentApi/ApiPaymentMethod.php - Operations · Operation listing and status reporting.
CAPSPaymentApi/ApiOperations.php
Models
DTOs, option objects, and payload builders used to compose requests and parse responses.
- Payin options · Payin request bodies and nested composition objects.
CAPSPaymentApi/PaymentPayinsOptions.php - Account options · Payment account actions and report option objects.
CAPSPaymentApi/PaymentAccountOptions.php - Holder models · Account holder registration, person, address, and requirement payloads.
CAPSPaymentApi/RegisterPerson.php - Payment models · 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 · Allowed values for types, statuses, roles, formats, and ticket attributes.
CAPSPaymentApi/EnumOperationType.php
Connections 24
- 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.