Sign up

To create payments, you need to link your server to our platform via one of our integration methods.
Our PHP SDK library is the ideal solution to connect to our platform if you prefer to do so with your own stand-alone system using PHP language.

Choosing the PHP SDK, you can:

To take full advantage of this SDK, make sure you meet these requirements:

  • PHP 7.4 or higher
  • Strongly recommended: Installation of the composer tool

You can download and install the latest version of the PHP SDK by:

Find more details on GitHub. Also, check out all available SDK objects and properties in our Full API Reference. Once you are all set, read the next chapters on how to prepare and use the SDK.

This guide provides a general overview on the SDK’s functionalities. To see how they precisely work for the different integration methods, see the dedicated guides explaining every step with full code samples:

Initialisation

To connect your system to our platform by using the SDK, you need to initialise it at first.

Initialising requires you to:

After initialisation, you can start processing transactions via your PSPID. Learn how this works in the dedicated chapter.

Have a look at the code sample covering the steps mentioned above:

Make sure to use the following classes:

  • CommunicatorConfiguration
  • V1HmacAuthenticator
  • Communicator
  • Client
  • ProxyConfiguration

// Your PSPID in either our test or live environment
$merchantId = "PSPID";

// Put the value of the API Key which you can find in the Merchant Portal
$apiKey = 'API KEY';

// Put the value of the API Secret which you can find in the Merchant Portal
$apiSecret = 'API Secret';

// This endpoint is pointing to the TEST server
// Note: Use the endpoint without the /v2/ part here
$apiEndpoint = 'https://payment.preprod.direct.worldline-solutions.com/';

// Additional settings to easily identify your company in our logs.
$integrator = 'YOUR COMPANY NAME';

$proxyConfiguration = null;
/*
* To use proxy, you should uncomment the section below
* and replace proper settings with your settings of the proxy.
* (additionally, you can comment on the previous setting).
*/
/*
$proxyConfiguration = new ProxyConfiguration(
    'proxyHost',
    'proxyPort',
    'proxyUserName',
    'proxyPassword'
);
*/
$communicatorConfiguration = new CommunicatorConfiguration(
    $apiKey,
    $apiSecret,
    $apiEndpoint,
    $integrator,
    $proxyConfiguration
);

$authenticator = new V1HmacAuthenticator($communicatorConfiguration);

$communicator = new Communicator($communicatorConfiguration, $authenticator);

$client = new Client($communicator);

$merchantClient = $client->merchant($merchantId);


The following table provides an overview of the arguments accepted by the individual instances:

Properties
  • string $merchantId: Your PSPID in either our test environment/live environment. Make sure to use the correct apiKey / apiSecret together with the conjoining PSPID for your transactions request.
  • string $apiKey: The API Key you have defined in your PSPID to which you will send the transactions to.
  • string $apiSecret: The API Secret you have defined in your PSPID to which you will send the transactions to
    Check out our dedicated guide to learn all about $apiKey / $apiSecret.
  • string $apiEndpoint: It contains a link to either our test or live environment where your transaction requests are sent to.
  • string $integrator: Your (company) name or any unique identifier. We can use the value for debugging and tracking request you have sent to our platform. Therefore, we strongly suggest sending a value we can identify your requests easily in our logs.

You can re-use a Client instance for different calls. You can use:

  • The MerchantClient class object initialised in the example for all calls for that PSPID 
    By calling this line of the code, you will obtain the MerchantClient object:
    $client->merchant($merchantId).
    
  • The Client instance to create MerchantClients for different (or the same) PSPIDs.


After you have initialised the SDK, you can send requests to our platform via your PSPID. Learn how to do this in the next chapter.

As our SDKs always implement the latest version of our API, you can leave out "v2" in your code as shown in the example above.

Remember to pay attention to the environment you get the key set from. API Key and API Secret are different for test and live environments.

The full path of the of API endpoint for test/live environment is

  • https://payment.preprod.payone.com/v2/
  • https://payment.payone.com/v2/

respectively. If you are ready to switch to the live environment, substitute the endpoint link apiEndpoint = 'https://payment.preprod.payone.com/' for the live environment apiEndpoint = 'https://payment.payone.com/'

For transactions with no financial impact, use TEST-URL. The transactions will be sent to our test environment, thereby to your test account.

For transactions with a financial impact, use the LIVE-URL. The transactions will be sent to our live environment, thereby to your live account.

Use SDK

After the successful initialisation of the Client instance, you gain full access to our RESTful API. It enables you to:

  • Send requests for new transactions for any of our server integration methods.
  • Get your transactions’ current status.
  • Perform maintenance requests (i.e., captures, refunds) on existing transactions.

Make sure that the payment method you would like to use is active in your test/live account. Check this in the Merchant Portal via Business > Payment methods.

Check out our test cases in GitHub, including full code samples, and our Full API Reference to learn what is possible.

Below you may find some of the most common actions you can perform.

Create new transactions

To create a new transaction, you can use either the Client or MerchantClient instance for any of our integration methods to create a new transaction. It can be done through:

  • Routing the request to your PSPID on our platform (for Client).
  • Creating a request for the respective integration method.

The SDK instance only keeps track of the data used to initialise it. It does not track neither active sessions nor previous requests. Your system is responsible for managing PAYONE E-Payment sessions and payments.

Sessions and payments do not impact other sessions and payments.

Below you can find code samples related to particular integration methods:

Hosted Checkout Page

To use this integration method, you need to create a CreateHostedCheckoutRequest call. It must contain at least an Order object.

Make sure to use the following classes:
  • CreateHostedCheckoutRequests
  • Order
  • AmountOfMoney
/*
 *…. Initialisation....
 */

/*
 * The HostedCheckoutClient object based on the MerchantClient
 * object created during initialisation
 */
$hostedCheckoutClient = $merchantClient->hostedCheckout();

$createHostedCheckoutRequest = new CreateHostedCheckoutRequest();

$order = new Order();

// Example object of the AmountOfMoney
$amountOfMoney = new AmountOfMoney();
$amountOfMoney->setCurrencyCode("EUR");
$amountOfMoney->setAmount(100);
$order->setAmountOfMoney($amountOfMoney);

$createHostedCheckoutRequest->setOrder($order);

// Get the response for the HostedCheckoutClient
$createHostedCheckoutResponse = $hostedCheckoutClient->createHostedCheckout($createHostedCheckoutRequest);

You can specify an optional returnUrl, which will be used to redirect your customer back to your website.

This call returns a CreateHostedCheckoutResponse response. Store the hostedCheckoutId and RETURNMAC it contains, as well as any other information relevant for you. You will need these for steps described in the following chapters.

This response also contains a partialRedirectUrl.

You have to concatenate the base URL "https://payment." with partialRedirectUrl according to the formula

https://payment. + partialRedirectUrl

and perform a redirection of your customer to this URL. Once the customer visits the Hosted Checkout Page, the payment process continues there.

The newest version of our SDK also returns the full path in redirectUrl, allowing you to skip concatenate the base URL "https://payment." with partialRedirectUrl. Learn more more in our  Hosted Checkout Page guide. 

Hosted Tokenization Page

To use this integration method, you need to

Make sure to use the following classes:
  • CreateHostedTokenizationRequest

/*
 *…. Initialisation....
 */

/*
 * The HostedTokenizationClient object based on the
 * MerchantClient object created during initialisation
 */
$hostedTokenizationClient = $merchantClient->hostedTokenization();

$createHostedTokenizationRequest = new CreateHostedTokenizationRequest();

// Set your template
$createHostedTokenizationRequest->setVariant("my-custom-template.html");

// Get the response for the HostedTokenizationClient
$createHostedTokenizationResponse = $hostedTokenizationClient->createHostedTokenization($createHostedTokenizationRequest);

From CreateHostedTokenizationResponse retrieve hostedTokenizationId as $hostedTokenizationId and hostedTokenizationUrl as $hostedTokenizationUrl. Use the partialRedirectUrl for the iframe and the $hostedTokenizationId or $tokenId (see infobox) to create the actual payment via Server-to-server integration method.

You can send either the tokenID or the hostedTokenizationId in your CreatePayment request. Learn more about using either option in the dedicated chapters of our Hosted Tokenization Page guide:

$hostedTokenizationId = $createHostedTokenizationResponse->getHostedTokenizationId();
$hostedTokenizationUrl = $createHostedTokenizationResponse->getHostedTokenizationUrl();

$createPaymentRequest = new CreatePaymentRequest();
$createPaymentRequest->setHostedTokenizationId($hostedTokenizationId);

$order = new Order();

$amountOfMoney = new AmountOfMoney();
$amountOfMoney->setCurrencyCode("EUR");
$amountOfMoney->setAmount(100);
$order->setAmountOfMoney($amountOfMoney);

$createPaymentRequest->setOrder($order);

// Get the response for the PaymentsClient
$createPaymentResponse = $merchantClient->payments()->createPayment($createPaymentRequest);

Server-to-server

A minimum CreatePaymentRequest requires you to set at least an Order object and a payment method:

Make sure to use the following classes:
  • CreatePaymentRequest
  • AmountOfMoney
  • Card
  • CardPaymentMethodSpecificInput
  • Order

/* 
 *…. Initialisation....
 */

$merchantClient = $client->merchant($merchantId);

/*
 * The PaymentsClient object based on the MerchantClient  
 * object created in initialisation 
 */
$paymentsClient = $merchantClient->payments();

$createPaymentRequest = new CreatePaymentRequest(); 

$order = new Order();

// Example object of the AmountOfMoney 
$amountOfMoney = new AmountOfMoney();
$amountOfMoney->setCurrencyCode("EUR");
$amountOfMoney->setAmount(100);
$order->setAmountOfMoney($amountOfMoney);

$createPaymentRequest->setOrder($order);
$cardPaymentMethodSpecificInput = new CardPaymentMethodSpecificInput(); // Example object of the Card $card = new Card(); $card->setCvv("123"); $card->setCardNumber("4111111111111111"); // // Find more test data here $card->setExpiryDate("1236"); $card->setCardholderName("Wile E. Coyote"); $cardPaymentMethodSpecificInput->setCard($card); $createPaymentRequest->setCardPaymentMethodSpecificInput( $cardPaymentMethodSpecificInput ); // Get the response for the PaymentsClient $createPaymentResponse = $paymentsClient->createPayment($createPaymentRequest);

We have dedicated guides for each of the aforementioned integration methods:

The documents contain all crucial details you need to profit from the integration methods full potential, including full transaction flows, code samples and other useful features.

Get transaction status

Our RESTful API allows you to request a transaction’s status anytime by one of our GET calls:

A GetPaymentDetails request looks like this:


// Get the response for the PaymentsClient
$createPaymentResponse = $merchantClient->payments()->createPayment($createPaymentRequest);

// Here you get $paymentId that you can use in further code
$paymentId = $createPaymentResponse->getPayment()->getId();

// Get the PaymentResponse object with status information
// concerning payment of the given ID
$paymentResponse = $merchantClient->payments()->getPaymentDetails($paymentId);
Properties
string $paymentId: The unique reference of your transaction on our platform. This reference can be retrieved from the CreatePaymentResponse or createHostedCheckoutResponse created in the previous section.

For more information about statuses visit the status documentation page.

Perform maintenance operation

To perform follow-up actions on existing transactions (i.e. captures or refunds), use our CapturePayment or RefundPayment API call respectively:

CapturePayment

Make sure to use the following classes:

  • CapturePaymentRequest

/*
 *…. Initialisation....
 */
        
// Here you get $paymentId that you can use in further code
$paymentId = $createPaymentResponse->getPayment()->getId();

/*
 * . ...
 */

$capturePaymentRequest = new CapturePaymentRequest();
$capturePaymentRequest->setAmount(100);
$capturePaymentRequest->setIsFinal(true);

// Get CaptureResponse object
$captureResponse = $merchantClient
    ->payments()
    ->capturePayment(
        $paymentId,
        $capturePaymentRequest
    );

RefundPayment

Make sure to use the following classes:

  • RefundRequest
  • AmountOfMoney
/*
 *…. Initialisation....
 */

// Here you get $paymentId you can use in further code 
$paymentId = $createPaymentResponse->getPayment()->getId();

/* 
 * . ... 
 */

$refundRequest = new RefundRequest();

$amountOfMoney = new AmountOfMoney();
$amountOfMoney->setCurrencyCode("EUR");
$amountOfMoney->setAmount(100);

$refundRequest->setAmountOfMoney($amountOfMoney);

// Get RefundResponse object 
$refundResponse = $merchantClient
    ->payments()
    ->refundPayment(
        $paymentId,
        $refundRequest
    );
Properties
string $paymentId: The unique reference of your transaction on our platform. This reference can be retrieved from the CreatePaymentResponse or createHostedCheckoutResponse created in the previous section.

Handle exceptions

If a transaction is rejected, our platform provides detailed information with an Exception instance. The affiliated HTTP status code also help you troubleshoot the error.

You can encounter two types of exceptions: transaction exceptions and HTTP exceptions.

Transaction exceptions

This kind of exception refers to transaction requests that are technically correct but were rejected by your customer’s issuer or your acquirer. If the transaction is returned in the exception then, it was created in our systems but not successfully processed.

The following code samples use implicit methods provided as an example. You are expected to provide your own implementation for these or replace them with similar logic:

Exception type /
HTTP status code
Code Sample
Rejected transactions /
Various(see PaymentResponse object)

/*
 *…. Initialisation....
 */

$createPaymentRequest = new CreatePaymentRequest();
/*
 * populate payment request
 */

try {
    $createPaymentResponse =
        $merchantClient->payments()->createPayment(
            $createPaymentRequest
        );

    $paymentId = $createPaymentResponse
        ->getPayment()->getId();
}
catch (DeclinedPaymentException $e) {
    $paymentResult = $e->getCreatePaymentResponse();
    $payment = $paymentResult->getPayment();
    $paymentId = $payment->getId();
    handleError($payment);
}

$paymentResponse = $merchantClient->payments()->getPayment($paymentId);

// Your code to check transaction status and
// handle errors
if (isNotSuccessful($paymentResponse)) {
    handleError($paymentResponse);
}
Rejected Refund /
Various(see PaymentResponse object)
/*
 *…. Initialisation....
 */

$paymentId = $createPaymentResponse->getPayment()->getId();
$refundRequest = new RefundRequest();
/**
 * populate refund request
 */

try {
    // Get the RefundResponse object
    $refundResponse = $merchantClient->payments()->refundPayment($paymentId, $refundRequest);

    $refundId = $refundResponse->getId();
} catch (DeclinedRefundException $e) {
    $refundResult = $e->getRefundResponse();
    $refundId = $refundResult->getId();
    handleError($refundResult);
}

$refundResponse = $merchantClient->payments()->refundPayment($paymentId, $refundRequest);

// Your code to check transaction status and
// handle errors
if (isNotSuccessful($refundResponse, $refundId)) {
    handleError($refundResponse);
}

HTTP exceptions

This kind of exception refers to various problems caused by technical errors in the API call or payment request.

You can combine any of the following code snippets with this standard CreatePayment request:

Make sure to use the following classes:
  • ApiException

/*
 *…. Initialisation....
 */

$createPaymentRequest = new CreatePaymentRequest();

$order = new Order();

// The example object of the AmountOfMoney
$amountOfMoney = new AmountOfMoney();
$amountOfMoney->setCurrencyCode("EUR");
$amountOfMoney->setAmount(100);
$order->setAmountOfMoney($amountOfMoney);

$createPaymentRequest->setOrder($order);

$cardPaymentMethodSpecificInput = new CardPaymentMethodSpecificInput();

// The example object of the Card – you can find test cards on
// /documentation/test-cases/
$card = new Card();
$card->setCvv("123");
$card->setCardNumber("4111111111111111");
$card->setExpiryDate("1236");
$card->setCardholderName("Wile E. Coyote");
$cardPaymentMethodSpecificInput->setCard($card);

$createPaymentRequest->setCardPaymentMethodSpecificInput($cardPaymentMethodSpecificInput);

try {
// Get the response for the PaymentsClient
    $createPaymentResponse = $merchantClient->payments()->createPayment($createPaymentRequest);
} catch (ApiException $e) {
// refer to the list below to see how specific
// implementations of ApiException can be handled.
}
Exception type /
HTTP status code
Code Sample
ValidationException /
400
catch (ValidationException $e) {
    $message = 'Input validation error:' . PHP_EOL;
    foreach ($e->getErrors() as $error) {
        $message .= '- ';
        if (!empty($error->getPropertyName())) {
            $message .= $error->getPropertyName() . ': ';
        }

        $message .= $error->getMessage();
        $message .= '(' . $error->getErrorCode() . ')' . PHP_EOL;
    }
    // Do something with $message
}
AuthorizationException /
403

catch (AuthorizationException $e) {
    $message = 'Authorization error:' . PHP_EOL;
    foreach ($e->getErrors() as $error) {
        $message .= '- ' . $error->getMessage();
        $message .= '(' . $error->getErrorCode() . ')' . PHP_EOL;
    }
    // Do something with $message
}
IdempotenceException /
409

catch (IdempotenceException $e) {
    $message = 'Idempotence error:' . PHP_EOL;
    foreach ($e->getErrors() as $error) {
        $message .= '- ' . $error->getMessage();
        $message .= '(' . $error->getErrorCode() . ')' . PHP_EOL;
    }
    // Do something with $message
}
ReferenceException /
404/409/410

catch (ReferenceException $e) {
    $message = 'Incorrect object reference:' . PHP_EOL;
    foreach ($e->getErrors() as $error) {
        $message .= '- ' . $error->getMessage();
        $message .= '(' . $error->getErrorCode() . ')' . PHP_EOL;
    }
    // Do something with $message
}
PlatformException /
500/502/503

catch (PlatformException $e) {
    $message = 'Error occurred at payment platform or ';
    $message .= 'a downstream partner/acquirer:' . PHP_EOL;
    foreach ($e->getErrors() as $error) {
        $message .= '- ' . $error->getMessage();
        $message .= '(' . $error->getErrorCode() . ')' . PHP_EOL;
    }
    // Do something with $message
}
ApiException /
Any other codes

catch (ApiException $e) {
    $message = 'Unexpected error:' . PHP_EOL;
    foreach ($e->getErrors() as $error) {
        $message .= '- ' . $error->getMessage();
        $message .= '(' . $error->getErrorCode() . ')' . PHP_EOL;
    }
    // Do something with $message
}

HTTP status codes

All our exceptions are linked to one or more HTTP status codes, indicating the root cause for many possible errors.

Status code Description Exception type
200

Successful
Our platform processed your request correctly

-
201

Created
Our platform processed your request correctly and created a new resource. We return the URI of this resource in the Location header of the response

-
204

No content
Our platform processed your request correctly

-
Various
paymentResult key is in the response

Payment Rejected
Either our platform or one of our downstream partners/acquirers rejected your request

DeclinedPaymentException
Various
payoutResult key is in the response

Payout Rejected
Either our platform or one of our downstream partners/acquirers rejected your request

DeclinedPayoutException

Various
refundResult key is in the response

Refund Rejected
Either our platform or one of our downstream partners/acquirers rejected your request

DeclinedRefundException
400

Bad Request
Your request contains errors, thus our platform cannot process it

ValidationException
403

Not Authorised
You are trying to do something that is not allowed or that you are not authorised to do

AuthorizationException
404

Not Found
The object you were trying to access could not be found on the server

ReferenceException
409

Conflict
Your idempotent request resulted in a conflict because of either:

  • The first request has not finished yet
  • Your request resulted in a conflict. Either you submitted a duplicate request, or you are trying to create something with a duplicate key
IdempotenceException
ReferenceException
410

Gone
The object that you are trying to reach has been removed.

ReferenceException
500

Internal Server Error
An error occurred on our platform

PlatformException
502 Bad Gateway
Our platform was unable to process a message from a downstream partner/acquirer
PlatformException
503 Service Unavailable
The service that you are trying to reach is temporarily unavailable. Please try again later
PlatformException
Other Unexpected error
An unexpected error has occurred
ApiException

Was this page helpful?

Do you have any comments?

Thank you for your response.