PHP SDK

Introduction

The PHP SDK helps you to communicate with the  Acquiring API . More specifically, it offers a PHP API that provides access to all the functionality of the RESTful Server API. Below, we discuss the following topics in detail.

• Setting up Composer

• Initialization of the PHP SDK

• Exceptions

• Logging

• Advanced use: Connection pooling

• Advanced use: Customization of the communication

• Advanced use: Proxy

The source code of the SDK is available on  Github . There you can find installation instructions.

The API documentation of the latest version of the SDK is available  here . For a specific major version, replace latest with the actual version in format <major>.x .

Setting up Composer

Composer is a dependency management tool for PHP. It allows you to declare the libraries your project depends on and it will manage (install/update) them for you.

In order to use composer, you first need to initialize composer in your project:

composer init

See  Introduction - Composer  for more information on how to get started with Composer.

Next we need to install the PHP SDK with composer:

composer require worldline-acquiring/acquiring-sdk-php

Composer manages the dependencies on a per-project basis; running this command will create a directory called  vendor  containing all the installed dependencies.

Finally, make sure you've included the  composer autoload file  in your project before you're using the classes:

require __DIR__ . '/vendor/autoload.php';

All classes of the PHP SDK are compliant with  PSR-4 . The PHP SDK uses root namespace  Worldline\Acquiring\Sdk .

Initialization of the PHP SDK

All PHP code snippets presented in the API Reference assume you have initialized the PHP SDK before using them in your Development Environment. This section details the initialization of the PHP SDK.

To initialize the PHP SDK, create an instance of the  Client  class. This class facilitates methods to communicate with the Worldline Acquiring API.

The  Client  constructor requires an instance of a  Communicator , which contains all the logic to transform a request object to a HTTP request and an HTTP response to a response object. This class requires an instance of  CommunicationConfiguration  for holding configuration values, an instance of  Authenticator  for providing authentication, and an instance of  Connection  for performing actual HTTP requests. Only the  CommunicationConfiguration  and Authenticator are required; if the  Connection  is not provided, a new instance will be created using the given  CommunicatorConfiguration . That means you only need to provide a  Connection  if the default isn't sufficient. If that is the case, you can provide your own implementation.

CommunicationConfiguration  is a class of which the constructor has the following required parameters:

• $authorizationId : the OAuth2 client id. It has a generic name to allow different authentication mechanism to be used in the future

• $authorizationSecret : the OAuth2 client secret. It has a generic name to allow different authentication mechanism to be used in the future

• $apiEndpoint : the API endpoint URI including scheme. See  API endpoints  for the possible values

• $integrator : the name of the integrator, e.g. your company name

Authenticator  is an interface with currently one provided implementing class, OAuth2Authenticator , of which the constructor has the following required parameters:

• $communicatorConfiguration : the CommunicatorConfiguration instance to use; this should usually be the same instance also used for the Communicator

• $oauth2TokenUri : the OAuth2 token URI. See  API endpoints  for the possible values

In code:

$communicatorConfiguration =
    new CommunicatorConfiguration($oauth2ClientId, $oauth2ClientSecret, $apiEndpoint, $integrator);
$authenticator = new OAuth2Authenticator($communicatorConfiguration, $oauth2TokenUri);
$communicator = new Communicator($communicatorConfiguration, $authenticator);
$client = new Client($communicator);

OAuth2 token caching

By default, OAuth2 tokens are cached for the current request only. The OAuth2Authenticator constructor accepts an optional third argument for an implementation of interface OAuth2TokenCache . The SDK provides one implementation, DefaultOAuth2TokenCache , which can be used to cache OAuth2 tokens for the current HTTP session instead:

$communicatorConfiguration =
    new CommunicatorConfiguration($oauth2ClientId, $oauth2ClientSecret, $apiEndpoint, $integrator);
$oauth2TokenCache = new DefaultOAuth2TokenCache($_SESSION);
$authenticator = new OAuth2Authenticator($communicatorConfiguration, $oauth2TokenUri, $oauth2TokenCache);
$communicator = new Communicator($communicatorConfiguration, $authenticator);
$client = new Client($communicator);

For more advanced forms of token caching you can provide your own OAuth2TokenCache implementation.

Exceptions

All calls can throw one of the following runtime exceptions:

• A  ValidationException  if the request was not correct and couldn't be processed (HTTP status code 400)

• An  AuthorizationException  if the request was not allowed (HTTP status code 403)

• An  IdempotenceException  if an idempotent request caused a conflict (HTTP status code 409)

• A  ReferenceException  if an object was attempted to be referenced that doesn't exist or has been removed, or there was a conflict (HTTP status code 404 or 409)

• A  PlatformException  if something went wrong on our end, we were unable to process a message from a downstream partner/acquirer, or the service that you're trying to reach is temporary unavailable (HTTP status code 500, 502 or 503)

• An  ApiException  if the RESTful Server API returned any other error

A payment attempt can now be handled as follows:

try {
    $processPaymentResponse =
        $client->v1()->acquirer($acquirerId)->merchant($merchantId)->payments()->processPayment($createPaymentRequest);
} catch (ValidationException $e) {
    $message = 'Input validation error: ' . $e->getDetail();
    //Do something with $message
} catch (AuthorizationException $e) {
    $message = 'Authorization error: ' . $e->getDetail();
    //Do something with $message
}
} catch (ReferenceException $e) {
    $message = 'Incorrect object reference: ' . $e->getDetail();
    //Do something with $message
} catch (PlatformException $e) {
    $message = 'Error occurred at Worldline or a downstream partner/acquirer: ' . $e->getDetail();
    //Do something with $message
} catch (ApiException $e) {
    $message = 'Worldline error: ' . $e->getStatusCode() . ', ' . $e->getDetail();
    //Do something with $message
}

Exception overview

The following table is a summary that shows when each of these exceptions will be thrown:

Logging

The PHP SDK supports logging of requests, responses, and exceptions of the API communication.

In order to start using the logging feature, an implementation of the  CommunicatorLogger  interface should be provided. The SDK provides two example implementations for logging to resources ( ResourceLogger ) and logging to  SplFileObjects ( SplFileObjectLogger ).

Logging can be enabled by calling the  enableLogging  method on a  Client  object, and providing the logger as an argument. The logger can subsequently be disabled by calling the  disableLogging  method.

The following code exemplifies the use of adding a logger:

$communicatorConfiguration = new CommunicatorConfiguration(...);
$authenticator = new OAuth2Authenticator(...);
$communicator = new Communicator($communicatorConfiguration, $authenticator);
$client = new Client($communicator);
 
$logger = new ResourceLogger(STDOUT);
$client->enableLogging($logger);
//... Do some calls
$client->disableLogging();

Advanced use: Connection pooling

The PHP SDK supports connection pooling by allowing connections to be shared amongst communicators, and by allowing communicators to be shared amongst clients. Pooling is enabled when the same  DefaultConnection  instance is provided to  Communicator  instances. The  Communicator  can in turn be used by different  Client  instances.

The following example reuses the connections between the different  Client  instances, since the same  DefaultConnection  object is used:

$communicatorConfiguration1 = new CommunicatorConfiguration(...);
$communicatorConfiguration2 = new CommunicatorConfiguration(...);

$authenticator1 = new OAuth2Authenticator($communicatorConfiguration1, ...);
$authenticator2 = new OAuth2Authenticator($communicatorConfiguration2, ...);
 
$sharedConnection = new DefaultConnection();
 
$communicator1 = new Communicator($communicatorConfiguration1, $authenticator1, $sharedConnection);
$communicator2 = new Communicator($communicatorConfiguration2, $authenticator2, $sharedConnection);
 
client1 = new Client($communicator1);
client2 = new Client($communicator2);

Advanced use: Customization of the communication

A  Client  uses a  Communicator  to communicate with the Worldline RESTful Acquiring API. This  Communicator  uses a  Connection  to perform the actual HTTP requests and a  ConnectionResponse  to hold the HTTP response.

Connection  is an interface. The SDK provides a default implementation via classes  DefaultConnection . It uses  cURL  via the standard  PHP/cURL bindings  to implement the  get() ,  delete() ,  post()  and  put()  methods.

If needed, the  DefaultConnection  class can be extended or completely replaced. In order to use this class, initialize the client with an instance of this class:

$communicatorConfiguration =
    new CommunicatorConfiguration($oauth2ClientId, $oauth2ClientSecret, $apiEndpoint, $integrator);
$authenticator = new OAuth2Authenticator($communicatorConfiguration, $oauth2TokenUri);

$connection = new MyDefaultConnection();
$communicator = new Communicator($communicatorConfiguration, $authenticator, $connection);
 
$client = new Client($communicator);

Advanced use: Proxy

The PHP SDK provides basic HTTP proxy support with authentication. Proxy support is enabled by supplying an optional  ProxyConfiguration  object to the constructor of the  CommunicatorConfiguration  class.

To exemplify the use of a proxy, consider the following code snippet:

$proxyConfiguration = new ProxyConfiguration(
    'proxyHost',
    'proxyPort',
    'proxyUserName',
    'proxyPassword'
);
 
$communicatorConfiguration = new CommunicatorConfiguration(
    $oauth2ClientId,
    $oauth2ClientSecret,
    $apiEndpoint,
    $integrator
    $proxyConfiguration
);
 
$communicator = new Communicator($communicatorConfiguration, $authenticator);
$proxyClient = new Client($communicator);