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

ComfinoPay PHP API client

ComfinoPay PHP API client library

A portable, PSR-compliant PHP protocol layer for the ComfinoPay payment gateway REST API. This library handles all HTTP communication with the ComfinoPay 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 ComfinoPay 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

Plain HTTP for local development

Cleartext http:// is refused by default, including for private IPs and Docker service names: the API key travels as a request header, so an http destination hands it to anyone on the path. It is enabled by COMFINO_DEV_ENV — the same server-set variable the ComfinoPay plugins already gate their dev overrides on:

With it set, http://localhost:8080, http://comfino-api and http://shop.test become valid destinations. It never widens the host allowlist — a public IP or a spoofed domain stays refused — and the real API always requires HTTPS. Do not set it in production.

Querying financial products

Order management

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

Shop owner registration

createUser() and fetchAgreements() are the one pair of calls made before an API key exists — construct the client with a null key (or, for SharedClient, an ApiContext whose apiKey is ''):

A shop already registered under webSiteUrl throws Comfino\Api\Exception\Conflict (HTTP 409); its message carries the field-level reason from the API.

Account and widget

The widget key is a public identifier associated with the ComfinoPay 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 ComfinoPay 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

ComfinoPay 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 ComfinoPay 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).

Serving many merchants from one process

Comfino\Api\Client holds one merchant's credentials as mutable state, which is right for a shop plugin and wrong for a long-lived service that handles many merchants in sequence. For that, use SharedClient: it stores no credential at all, so a single instance — one transport, one connection pool, one retry executor — can serve every tenant.

Keep the PSR-18 transport shared. The credential is a header, not a connection property, so one TLS pool serving every tenant is both safe and the point — giving each merchant its own transport costs a handshake per merchant per request.

Already have code written against the mutable surface? SharedClient::bind($context) returns a BoundClient implementing the same ClientInterface, one binding per tenant, with the credential still off anything shared.

Retry, backoff and timeout escalation

Wrap the client with a RetryExecutor to retry transient failures with exponentially growing, jittered delays:

Two schedules grow per attempt, and they answer different failures. The timeout doubles, which is the right answer to a slow far side. The delay doubles with full jitter, which is the right answer to a refused connection — and to not turning every tenant on a node into one synchronized retry wave. Both are bounded: the escalation by maxTotalTransferTimeout, the delay by maxDelayMs. They bound different clocks, so getWorstCaseWallClockMs() reports the sum, which is the number to size a request latency budget against.

On a path that cannot absorb a sleep, say so rather than sleeping in it:

Retryable failures are transport errors, HTTP 429, 502, 503 and 504, plus 500 for requests that are safe to replay. A Retry-After header is honored in both of its RFC 9110 forms and clamped, so a wrong header cannot park a worker.

Order creation is safe to retry and needs no idempotency key. The API deduplicates a replayed POST /orders by orderId — mandatory, and unique per shop — plus the hash of the request body: a request for an id that already exists with the same body is answered with the existing order at 201 Created rather than creating a second loan application, and a differing body under the same id is rejected as a validation error. The one thing this asks of a caller is not to vary the body between attempts; the client builds each request once and reuses it across attempts, so that holds automatically.

If you write a Request of your own against an endpoint with no such key, say so and it will be sent exactly once:

For per-request timeouts to reach the wire, the transport has to accept them. Implement TimeoutConfigurableClientInterface::withTimeouts(), which returns a configured copy, or wrap a transport whose timeouts are construction options:

The older TimeoutAwareClientInterface::updateTimeouts() is still honored, but it mutates the transport in place and never restores it — on transport shared between tenants, one tenant's escalated budget stays applied to the next tenant's call. Prefer the copy-returning interface.

Circuit breaker and outbound rate limiting

Both are optional and off by default. A breaker stops a ComfinoPay outage from becoming your outage: instead of every worker paying the full timeout on a dead socket, calls fail immediately once a host looks unhealthy.

The limiter is keyed by (tenantKey, endpoint) through RateLimitKey, which drops the query string before building the key: without that, GET /financial-products?loanAmount=130000 and ?loanAmount=130100 are separate buckets, and the endpoint an integration calls most — with the cart total in the query — is the one the limit never reaches. Scheme, host and path are kept, so a merchant's sandbox traffic does not spend its production budget.

The breaker is keyed by (tenantKey, host), and only transport failures and 5xx feed it: one merchant's wrong API key produces 401s, and a breaker opened by those would block every healthy merchant on the same host. The limiter is non-blocking by contract — what happens on rejection is a call-site decision:

Pass a shared store to either one (both take a store interface) when several workers need to agree on what they have learned; the in-memory defaults are per process.

A shared store needs a compare-and-swap to be exact. Reserving a token is a read-modify-write, so two workers over a plain TokenBucketStoreInterface both read the same bucket and the second write erases the first — the limiter then admits one burst per worker. Implement AtomicTokenBucketStoreInterface (and AtomicCircuitBreakerStoreInterface) instead: the limiter switches to a bounded swap loop, and the breaker uses the swap to let exactly one worker claim the half-open probe rather than all of them. TokenBucketRateLimiter::isExact() and CircuitBreaker::isExact() report which path a given wiring took, so it can be asserted in a test — a shared store that cannot swap looks identical to one that can, right up to the load that breaks it. comfino/php-sdk ships PSR-6 implementations of the plain interfaces (Psr6TokenBucketStore, Psr6CircuitBreakerStore) for hosts that want shared state without writing the serialization; PSR-6 itself has no swap, so read their docblocks on which of the two costs that leaves you with.

Observing requests and retries

Implement RequestObserverInterface or RetryObserverInterface to emit per-tenant metrics without patching anything. Both receive the tenant, so nothing has to be inferred:

Custom requests

Call an endpoint that doesn't have a dedicated client method yet with sendCustomRequest(). It reuses the same authentication, track ID, and error-mapping infrastructure as every built-in method:

For a typed response, pass your own Response subclass (see src/Api/Response/GetProductTypes.php for a minimal example) as the second argument:

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.