Installation

Install and configure the PHP SDK using Composer.

This guide covers installing and configuring the Paysera Checkout PHP SDK.

Requirements

• PHP: 7.4, 8.0, 8.1, 8.2, 8.3 or 8.4 (^7.4 || ^8.0)
• Extensions: ext-curl, ext-json
• Composer: For dependency management

Installation via Composer

composer require paysera/lib-checkout-integration-sdk

The package is published on Packagist as paysera/lib-checkout-integration-sdk — no additional repository configuration is required.

Builder Options

Everything is configured through SdkFacadeBuilder before calling build():

use Paysera\CheckoutSdk\SdkFacadeBuilder;

$sdkFacade = (new SdkFacadeBuilder())
    ->setLogger($logger)                                          // PSR-3, NullLogger by default
    ->setHttpClient($httpClient)                                  // PSR-18, cURL client by default
    ->setCacheItemPool($cacheItemPool)                            // PSR-6, InMemoryCache by default
    ->setClock($clock)                                            // PSR-20, system clock by default
    ->setPaymentApiAuthTokenRepository($authTokenRepository)      // in-memory by default
    ->setPaymentApiCredentialsRepository($credentialsRepository)  // in-memory by default
    ->setApiClientFormatter($apiClientFormatter)                  // log formatting
    ->setJwtLeeway(60)                                            // clock-skew allowance in seconds
    ->build();

PSR Components

Method	Standard	Default	Purpose
setLogger()	PSR-3	NullLogger	SDK logging
setHttpClient()	PSR-18	php-http/curl-client	Outgoing HTTP requests
setCacheItemPool()	PSR-6	InMemoryCache	Caches the JWKS key set used for JWT verification
setClock()	PSR-20	System clock	Time-based operations such as token expiration

setApiClientFormatter() controls how requests and responses are rendered in logs. The default SecureApiClientFormatter masks sensitive values — replace it only if you understand the implications.

setJwtLeeway() widens the allowance for iat, nbf and exp claim validation. It defaults to 0, so raise it when merchant servers may have unsynchronised clocks — otherwise clock drift surfaces as a JWT validation failure.

Token and Credentials Persistence

By default, tokens and credentials are stored in memory and lost when the script ends. For persistent storage, implement the repository interfaces and pass them to the builder:

• PaymentApiAuthTokenRepositoryInterface — Permanently stores the payment API access token. Helps avoid additional token requests between calls. The token is stored automatically during authorization.
• PaymentApiCredentialsRepositoryInterface — Permanently stores payment API credentials. Needed for automatically refreshing tokens and for callback processing. Credentials are stored automatically during authorization.

$sdkFacade = (new SdkFacadeBuilder())
    ->setPaymentApiAuthTokenRepository($myTokenRepository)
    ->setPaymentApiCredentialsRepository($myCredentialsRepository)
    ->build();

Production Configuration

JWKS Cache

The SDK verifies JWT access token signatures against the Paysera Keycloak JWKS endpoint. The key set is fetched once on cold start and cached for 30 days; the endpoint is contacted again only when an incoming token carries an unknown kid (key rotation).

Inject a persistent cache pool

The default InMemoryCache is scoped to a single PHP request. In shared-nothing deployments (PHP-FPM, multi-container setups) it defeats caching entirely and triggers a JWKS fetch on every validation. Pass a persistent PSR-6 pool via setCacheItemPool().

Recommended backends — anything that survives across PHP request lifecycles:

Stack	Adapter
Symfony	Symfony\Component\Cache\Adapter\RedisAdapter
Laravel	Illuminate\Cache\Psr6\CachePool wrapping the application cache
WordPress / WooCommerce	Any bridge from WP transients or object cache to PSR-6
Plain PHP	Symfony\Component\Cache\Adapter\FilesystemAdapter

Keep the pool SDK-scoped. If a signing key must be purged during incident response, the whole pool is flushed — sharing it with application data would wipe business data too.

HTTP Client Timeouts

JWKS fetches block the calling thread. An unbounded client timeout turns a slow endpoint into a hung checkout request, so configure finite timeouts on the injected PSR-18 client:

• Symfony HttpClient: HttpClient::create(['timeout' => 10, 'max_duration' => 10])
• Guzzle: new Client(['connect_timeout' => 5, 'timeout' => 10])

The bundled cURL client already sets a 10 s connect timeout and a 30 s total timeout.

Environment Overrides

The SDK targets production by default. Base URLs can be overridden with environment variables — useful for local development and testing:

Variable	Overrides
PAYSERA_CHECKOUT_SDK_PAYMENT_API_PRODUCTION_BASE_URL	Payment API production base URL
PAYSERA_CHECKOUT_SDK_PAYMENT_API_SANDBOX_BASE_URL	Payment API sandbox base URL
PAYSERA_CHECKOUT_SDK_MERCHANT_AREA_PRODUCTION_BASE_URL	Merchant Area production base URL
PAYSERA_CHECKOUT_SDK_MERCHANT_AREA_SANDBOX_BASE_URL	Merchant Area sandbox base URL

See Environments for the hosted environments and Test Mode for running payments without real funds.