Download the PHP package comfino/php-sdk without Composer

ComfinoPay PHP SDK

ComfinoPay PHP SDK with backend routines for e-commerce platforms integration

A complete PHP backend library for integrating any application or e-commerce platform with the ComfinoPay payment gateway API. Whether you are building a custom integration for a closed platform, writing a payment plugin for an open-source e-commerce system, or embedding ComfinoPay financing into your own application, this SDK provides all the backend building blocks you need.

The library covers the full integration lifecycle: API communication, secure webhook handling, configuration management, payment product filtering, category-based eligibility checks, and frontend widget support. All integration points are defined as interfaces, so the SDK adapts to any PHP application stack without imposing a concrete HTTP client, logger, or cache implementation.

Lightweight integration? If you only need the HTTP API layer — requests, responses, DTOs, retry, and auth — without the full plugin infrastructure, you can depend directly on the lower-level package:

comfino/php-api-client is the standalone API client that this SDK builds upon. It ships the PSR-18 HTTP client, all request/response classes, error types, and the webhook signature verifier, but nothing else. See the php-api-client documentation for details.

Features

• PSR-18 HTTP Client / PSR-7 Messages / PSR-17 Factories support.
• PSR-6 cache and PSR-3 logging interfaces.
• Production and sandbox environment support.
• Exponential backoff retry for transient API errors.
• Secure webhook handling with CR-Signature (SHA3-256) verification, per-tenant key resolution, replay protection and rate limiting.
• Multitenant-safe by design: every service is addressed by a tenant scope, and a stateless API client carries the credential per call instead of on the object.
• Outbound request queue with per-tenant fairness, exponential backoff and dead-lettering for fire-and-forget calls.
• Configuration manager with a pluggable storage adapter.
• Payment product type filter chain based on cart value and category.
• Hierarchical category tree with ancestor/descendant traversal.
• Frontend helpers for widget init script and paywall logo authentication.

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

Serving more than one merchant

A Client is its credential, which is the right shape for a plugin installed in a shop. In a long-lived process that serves many merchants — a SaaS connector, a queue worker — use the stateless client instead: nothing about a tenant lives on it, so one instance can be a container service and the tenant travels per call.

The same rule runs through the rest of the SDK: ConfigurationManager, SettingsManager, StatusManager, ProductTypeFilterManager and the loggers take a tenant scope in getInstance(), CacheManager::forScope($tenant) returns a per-tenant cache, and WebhookManager resolves the tenant before it verifies a signature. See UPGRADE.md if you are moving an existing integration to 3.0.

Documentation

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-sdk — standard container, no Xdebug. Start it once with docker-compose up -d.
• php-sdk-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-6 cache
• 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.