Download the PHP package comfino/php-api-client without Composer

Comfino PHP API client

Comfino PHP API client library

A portable, PSR-compliant PHP protocol layer for the Comfino payment gateway REST API. This library handles all HTTP communication with the Comfino API: creating and managing loan applications (orders), querying available financial products, verifying webhook signatures, and generating paywall iframe authentication tokens for the shop checkout page. It imposes no concrete HTTP client, serializer, or framework dependency — bring your own PSR-18 client and PSR-17 factories.

Features

• PSR-18 HTTP Client / PSR-7 Messages / PSR-17 Factories support.
• Production and sandbox environment support.
• Exponential backoff retry for transient API errors.
• Secure webhook handling with CR-Signature (SHA3-256) verification.
• Time-limited HMAC-signed auth token generation for paywall iframe embedded at the shop checkout page.
• Typed exception hierarchy mapped to HTTP status codes.
• Forward-compatible enums: unknown API values are represented as flyweights rather than thrown as errors.

Requirements

• PHP 8.1 or higher
• Extensions: ext-json, ext-sodium, ext-zlib
• PSR-18 HTTP Client and PSR-17 HTTP Factories implementations
• Composer

Installation

Suggested companion packages:

Quick start

The API key is issued by Comfino when your shop signs a merchant contract. It authenticates all server-to-server API calls and must be kept secret — never expose it in frontend code, browser requests, or public repositories.

Usage

Client configuration

Querying financial products

Order management

See request-signing.md for details on how request signatures are computed automatically for order creation.

Account and widget

The widget key is a public identifier associated with the Comfino merchant account pointed to by the API key. Unlike the API key, it is safe to embed in frontend scripts — it is used by the Comfino Web Frontend SDK to render the promotional banner widget and the paywall iframe at the shop checkout page.

Notifications (fire-and-forget)

These methods catch all exceptions internally and return bool. They are safe to call without a try/catch block.

Webhook signature verification

Comfino signs status-update webhook requests with a CR-Signature header. Verify it before processing:

See webhook-verification.md for comprehensive webhook handling patterns, including framework integration, multiple API keys, replay attack prevention, and troubleshooting.

Paywall authentication token

The Comfino paywall iframe embedded at the shop checkout page requires a short-lived signed token. Generate one server-side per page render using the public widget key and the private API key, then pass only the resulting token to the frontend — the API key never leaves the server:

Tokens are valid for 15 minutes (enforced server-side).

Retry and timeout escalation

Wrap the client with a RetryExecutor to retry transient network failures with exponential backoff:

When the HTTP client also implements TimeoutAwareClientInterface, the executor automatically escalates connection and transfer timeouts on each retry attempt according to the policy schedule.

Error handling

All API errors are thrown as typed exceptions that implement HttpErrorExceptionInterface and preserve the original request and response bodies for debugging:

Development

The bin/ wrappers delegate to Docker containers when docker-compose is available, or fall back to the host PHP. Two containers are used:

• php-api-client — standard container, no Xdebug. Start it once with docker-compose up -d.
• php-api-client-coverage — built with Xdebug (XDEBUG_MODE=coverage). Started on demand automatically by bin/phpunit whenever a --coverage* flag is detected; no manual up needed.

PSR standards

• PSR-4 autoloading
• PSR-7 HTTP messages
• PSR-17 HTTP factories
• PSR-18 HTTP client
• PSR-12 coding style

Changelog

See CHANGELOG for recent changes.

License

BSD 3-Clause License. See LICENSE for details.

Support

Bug reports and feature requests: GitHub issue tracker.

Contributing

The GitHub repository is a read-only public mirror that receives automated clean-snapshot releases. Please report bugs and suggest improvements via the issue tracker.