PHPackages comfino/php-api-client - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [HTTP & Networking](/categories/http) 4. / 5. comfino/php-api-client ActiveLibrary[HTTP & Networking](/categories/http) comfino/php-api-client ====================== Comfino PHP API client library for the Comfino payment gateway with PSR-7/17/18 support - portable protocol layer for the Comfino REST API. 2.0.0(1mo ago)0711BSD-3-ClausePHPPHP >=8.1CI passing Since Apr 15Pushed 1w agoCompare [ Source](https://github.com/comfino/php-api-client)[ Packagist](https://packagist.org/packages/comfino/php-api-client)[ Docs](https://github.com/comfino/php-api-client)[ RSS](/packages/comfino-php-api-client/feed)WikiDiscussions master Synced 1w ago READMEChangelog (2)Dependencies (9)Versions (3)Used By (1) [ ![Comfino](assets/comfino_logo.svg)](https://developers.comfino.pl)Comfino PHP API client ====================== [](#comfino-php-api-client) [![Latest Version](https://camo.githubusercontent.com/24a350f9b06ad7b2192019ae6436c6faa218fa51f324394bc079342e61adfda5/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f72656c656173652f636f6d66696e6f2f7068702d6170692d636c69656e742e737667)](https://github.com/comfino/php-api-client/releases)[![PHP Version](https://camo.githubusercontent.com/331306f7d90331de46ab0f76681f8accbfec9f6df53f51db913423b4ab4028c5/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f646570656e64656e63792d762f636f6d66696e6f2f7068702d6170692d636c69656e742f7068702e737667)](https://packagist.org/packages/comfino/php-api-client)[![Build Status](https://github.com/comfino/php-api-client/actions/workflows/tests.yml/badge.svg)](https://github.com/comfino/php-api-client/actions/workflows/tests.yml)[![Software License](https://camo.githubusercontent.com/ba163b9d6a47bcfeeaeeae8a91d4fa1a8df3d528367d69952295f31f2f770cad/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d425344253230332d2d436c617573652d6f72616e67652e737667)](LICENSE)[![Total Downloads](https://camo.githubusercontent.com/a23fe9cc56fde4002b126db55faa5c906f6a3396a9c57abbd250710e61546ec4/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f636f6d66696e6f2f7068702d6170692d636c69656e742e737667)](https://packagist.org/packages/comfino/php-api-client)[![API Documentation](https://camo.githubusercontent.com/b2e7feb6e6f17d534d0fcadc30e1f4d74bd06681abe353feb46bdb3741ea02b6/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4150492d646f63756d656e746174696f6e2d356139653333)](https://developers.comfino.pl) **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 -------- [](#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 ------------ [](#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 ------------ [](#installation) ``` composer require comfino/php-api-client ``` Suggested companion packages: ``` composer require nyholm/psr7 # PSR-7/17 message and factory implementation composer require sunrise/http-client-curl # PSR-18 cURL client implementation ``` Quick start ----------- [](#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. ``` use Comfino\Api\Client; use Nyholm\Psr7\Factory\Psr17Factory; use Sunrise\Http\Client\Curl\Client as CurlClient; $psr17Factory = new Psr17Factory(); $client = new Client( httpClient: new CurlClient($psr17Factory), requestFactory: $psr17Factory, streamFactory: $psr17Factory, apiKey: 'your-api-key', // Private - keep server-side only. ); $client->enableSandboxMode(); // Omit or call disableSandboxMode() for production. // Submit a loan application. $response = $client->createOrder($order); // $order implements OrderInterface header('Location: ' . $response->applicationUrl); ``` Usage ----- [](#usage) ### Client configuration [](#client-configuration) ``` // Override the default user agent. $client->setCustomUserAgent('my-plugin/1.0.0'); // Set the API language (ISO 639-1) and currency (ISO 4217). $client->setApiLanguage('pl'); $client->setApiCurrency('PLN'); // Add a custom HTTP header (e.g., for platform identification). $client->addCustomHeader('X-Shop-Platform', 'WooCommerce/8.5'); // Use a different API endpoint (e.g., staging). $client->setCustomApiBaseUrl('https://staging-api.example.com'); ``` ### Querying financial products [](#querying-financial-products) ``` use Comfino\Api\Dto\Payment\LoanQueryCriteria; use Comfino\Enum\LoanType; use Comfino\Enum\ProductListType; // List all products for a 1 500 PLN cart (amounts in grosz). $criteria = new LoanQueryCriteria(loanAmount: 150000); $response = $client->getFinancialProducts($criteria); foreach ($response->financialProducts as $product) { echo $product->name . ' - ' . $product->instalmentAmount . " grosz/month\n"; } // Filter by product type. $criteria = new LoanQueryCriteria( loanAmount: 150000, loanType: LoanType::INSTALLMENTS_ZERO_PERCENT ); // Get detailed information about a specific financial product (e.g., for a product detail page). $details = $client->getFinancialProductDetails($criteria, $cart); // $cart implements CartInterface // Get available product types configured for this shop account (for promotional banner widget at shop product page). $types = $client->getProductTypes(ProductListType::WIDGET); ``` ### Order management [](#order-management) ``` // Create a loan application - $order implements Comfino\Shop\Order\OrderInterface. $createResponse = $client->createOrder($order); $applicationUrl = $createResponse->applicationUrl; // Validate an order without submitting it. $validateResponse = $client->validateOrder($order); // Retrieve order status. $orderDetails = $client->getOrder('ORDER-123'); // Cancel an order. $client->cancelOrder('ORDER-123'); ``` See [request-signing.md](docs/request-signing.md) for details on how request signatures are computed automatically for order creation. ### Account and widget [](#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. ``` // Check that the API key belongs to an active account. $isActive = $client->isShopAccountActive(); // Retrieve the widget key (public) for use in frontend scripts (e.g., promotional banner). $widgetKey = $client->getWidgetKey(); // List available widget types. $widgetTypes = $client->getWidgetTypes(); ``` ### Notifications (fire-and-forget) [](#notifications-fire-and-forget) These methods catch all exceptions internally and return `bool`. They are safe to call without a try/catch block. ``` use Comfino\Api\Dto\Plugin\ShopPluginError; // Report a plugin error for remote diagnostics (e.g., from an exception handler). $client->sendLoggedError(new ShopPluginError( host: 'myshop.example.com', platform: 'ExampleEcommercePlatform', environment: ['php' => PHP_VERSION, 'plugin' => '2.0.0'], errorCode: 'API_ERROR', errorMessage: 'Unexpected API response.', stackTrace: $exception->getTraceAsString(), )); // Notify Comfino when the payment plugin is uninstalled. $client->notifyPluginRemoval(); // Notify Comfino of an abandoned cart event. $client->notifyAbandonedCart('checkout_abandoned'); ``` ### Webhook signature verification [](#webhook-signature-verification) Comfino signs status-update webhook requests with a `CR-Signature` header. Verify it before processing: ``` use Comfino\Auth\WebhookSignatureVerifier; $verifier = new WebhookSignatureVerifier(); $signature = $_SERVER['HTTP_CR_SIGNATURE'] ?? ''; $payload = file_get_contents('php://input'); if (!$verifier->verify($signature, 'your-api-key', $payload)) { http_response_code(401); exit; } // Process verified payload. $data = json_decode($payload, true); ``` See [webhook-verification.md](docs/webhook-verification.md) for comprehensive webhook handling patterns, including framework integration, multiple API keys, replay attack prevention, and troubleshooting. ### Paywall authentication token [](#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: ``` use Comfino\Auth\PaywallAuthKeyGenerator; $generator = new PaywallAuthKeyGenerator(); // $widgetKey - public, obtained via $client->getWidgetKey() and stored in shop config // $apiKey - private, never sent to the browser $authKey = $generator->generateAuthKey(widgetKey: $widgetKey, apiKey: $apiKey); // Pass only $authKey to the frontend widget initialization script served from the Comfino CDN (part of the official Comfino Web Frontend SDK). ``` Tokens are valid for 15 minutes (enforced server-side). ### Retry and timeout escalation [](#retry-and-timeout-escalation) Wrap the client with a `RetryExecutor` to retry transient network failures with exponential backoff: ``` use Comfino\Api\Client; use Comfino\Api\Retry\ExponentialBackoffRetryPolicy; use Comfino\Api\Retry\RetryExecutor; use Comfino\Api\Retry\TimeoutConfig; $retryPolicy = new ExponentialBackoffRetryPolicy( timeoutConfig: new TimeoutConfig(connectionTimeout: 5, transferTimeout: 15), maxAttempts: 3, ); $client = new Client( httpClient: $httpClient, requestFactory: $requestFactory, streamFactory: $streamFactory, apiKey: 'your-api-key', retryExecutor: new RetryExecutor($retryPolicy), ); ``` 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 -------------- [](#error-handling) All API errors are thrown as typed exceptions that implement `HttpErrorExceptionInterface` and preserve the original request and response bodies for debugging: HTTP statusExceptionDescription400`Comfino\Api\Exception\RequestValidationError`Invalid request data.401`Comfino\Api\Exception\AuthorizationError`Missing or invalid API key.403`Comfino\Api\Exception\Forbidden`Permission issues.404`Comfino\Api\Exception\NotFound`Resource not found.405`Comfino\Api\Exception\MethodNotAllowed`HTTP method not allowed.409`Comfino\Api\Exception\Conflict`Resource state conflict.5xx`Comfino\Api\Exception\ServiceUnavailable`Server-side error.timeout/retry exhausted`Comfino\Api\Exception\ConnectionTimeout`HTTP client timeout or all retry attempts failed.``` use Comfino\Api\Exception\AuthorizationError; use Comfino\Api\Exception\RequestValidationError; use Comfino\Api\Exception\ServiceUnavailable; try { $response = $client->createOrder($order); } catch (RequestValidationError $e) { // $e->errors contains field-level validation messages from the API. } catch (AuthorizationError $e) { // Invalid or missing API key. } catch (ServiceUnavailable $e) { // Comfino API is temporarily unavailable. } ``` Development ----------- [](#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. ``` # Start the standard development container. docker-compose up -d # Install dependencies. ./bin/composer install # Run all tests. ./bin/composer test # Run unit tests only. ./bin/phpunit --testsuite Unit # Run integration tests against the sandbox (requires a sandbox API key). COMFINO_SANDBOX_API_KEY=your-key ./bin/phpunit --testsuite Integration # Generate HTML coverage report (Xdebug container starts automatically). ./bin/phpunit --coverage-html coverage # Check PSR-12 code style. ./bin/composer cs # Auto-fix PSR-12 violations. ./bin/composer cs-fix # Run PHPStan static analysis (level 6). ./bin/composer analyse ``` PSR standards ------------- [](#psr-standards) - **PSR-4** autoloading - **PSR-7** HTTP messages - **PSR-17** HTTP factories - **PSR-18** HTTP client - **PSR-12** coding style Changelog --------- [](#changelog) See [CHANGELOG](CHANGELOG.md) for recent changes. License ------- [](#license) BSD 3-Clause License. See [LICENSE](LICENSE) for details. Support ------- [](#support) Bug reports and feature requests: [GitHub issue tracker](https://github.com/comfino/php-api-client/issues). Contributing ------------ [](#contributing) The [GitHub repository](https://github.com/comfino/php-api-client) is a read-only public mirror that receives automated clean-snapshot releases. Please report bugs and suggest improvements via the [issue tracker](https://github.com/comfino/php-api-client/issues). ### Health Score 40 — FairBetter than 86% of packages Maintenance94 Actively maintained with recent releases Popularity9 Limited adoption so far Community5 Small or concentrated contributor base Maturity43 Maturing project, gaining track record How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~46 days Total 2 Last Release 8d ago ### Community Maintainers ![](https://avatars.githubusercontent.com/u/83001403?v=4)[Artos Rakshasa](/maintainers/akozubskicr)[@akozubskicr](https://github.com/akozubskicr) --- Tags apiapi-clientbnplclientcomfinoinstallmentspay-laterpayment-gatewaypayment-integrationpaymentspsr-7apiclientpsr-18paymentgatewayinstallmentsbnplpay latercomfino ### Code Quality TestsPHPUnit Static AnalysisPHPStan Code StylePHP\_CodeSniffer Type Coverage Yes ### Embed Badge ![Health badge](/badges/comfino-php-api-client/health.svg) ``` [![Health](https://phpackages.com/badges/comfino-php-api-client/health.svg)](https://phpackages.com/packages/comfino-php-api-client) ``` ### Alternatives [guzzlehttp/psr7 PSR-7 message implementation that also provides common utility methods 7.9k1.1B3.7k](/packages/guzzlehttp-psr7)[cakephp/cakephp The CakePHP framework 8.8k19.1M1.7k](/packages/cakephp-cakephp)[tempest/framework The PHP framework that gets out of your way. 2.2k31.1k11](/packages/tempest-framework)[mollie/mollie-api-php Mollie API client library for PHP. Mollie is a European Payment Service provider and offers international payment methods such as Mastercard, VISA, American Express and PayPal, and local payment methods such as iDEAL, Bancontact, SOFORT Banking, SEPA direct debit, Belfius Direct Net, KBC Payment Button and various gift cards such as Podiumcadeaukaart and fashioncheque. 61315.4M74](/packages/mollie-mollie-api-php)[telnyx/telnyx-php Official Telnyx PHP SDK — APIs for Voice, SMS, MMS, WhatsApp, Fax, SIP Trunking, Wireless IoT, Call Control, and more. Build global communications on Telnyx's private carrier-grade network. 35729.6k2](/packages/telnyx-telnyx-php)[phpro/http-tools HTTP tools for developing more consistent HTTP implementations. 28146.3k](/packages/phpro-http-tools) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)