Introduction

WL Sips is a secure multi-channel e-commerce payment solution that complies with the PCI DSS standard. It allows you to accept and manage payment transactions by taking into account business rules related to your activity (payment on despatch, deferred payment, recurring payment, payment in instalments, etc.).

The purpose of this document is to explain how to switch from WL Sips Payment 1.0 to the Sips Paypage 2.0.

Topics not covered in this document:

  • This document shows only the migration to the Sips Paypage 2.0 POST which is a connector recommended on Sips Paypage 2.0. If you want to use the JSON version, please refer to the Integration guide document.

Who does this document target?

This document is intended for merchants having the WL Sips 1.0 offer and is intended to facilitate the migration to WL Sips 2.0.

For full details on the Sips Paypage 2.0 payment pages use, please refer to the WLSIPS.306 UG Sips Paypage POST document.

Contacting the support

For any technical question or request for assistance, our services are available:

  • by telephone at: +33 (0) 811 10 70 33
  • by e-mail: sips@worldline.com

In order to facilitate the processing of your requests, please provide your merchantId (15-digit number).

The Sips Paypage 2.0 assets

The Sips Paypage 2.0 allows to no longer store the files specific to the call of the payment pages on your server.

Also, the choice of payment method can be made on your merchant server (by specifying the payment method during the call) or payment server-side Sips Paypage 2.0.

Finally, with the Sips Paypage 2.0 POST, only a form in POST mode will be sent to Sips Paypage 2.0 servers to make the payment process. The redirection is made automatically by the payment server to the page for entering the payment method details.

Principle

What does changes in WL Sips 2.0?

For the payment part:

  • the opportunity to use a new transaction reference (35 car, AN) unique (can only be used for one transaction) to manage independently.
  • the new URL for the payment pages part.
  • the choice management of the payment method is deported to WL Sips .
  • the WL Sips certificate is replaced by a secret key.

The merchant no longer installs any files on his device, regardless of which WL Sips 2.0 interface he chooses.

What the merchant must do?

  • Decide which Sips Paypage 2.0 connector to use (POST, JSON).
  • Decide to stay with transactionID management or go to transactionReference .
  • Set up his payment requests by securing his new secret key.
  • Use the customer recipe environment to test Sips Paypage 2.0 applications with an available login ID.
  • Make an access request in production.
  • Delete references to Payment 1.0 on his website (certificate, settings files, executable files).

Choosing the Sips Paypage connector

This document shows only the POST connector (request sent to the WL Sips server in POST mode).

If you want the payment server calls to be made in machine-to-machine mode with JSON technology, please refer to the Integration guide document for setting up requests in this mode.

Choosing the transactionID or transactionReference mode

By default, the Sips Paypage 2.0 uses a transactionReference to identify a transaction to the payment server. This identifier is unique for all the duration of the merchant registration on WL Sips , it is not reusable for another payment transaction.

If you want to stay in the transactionID / transactionDate mode, you must make a request to WL Sips when registering your Merchant ID to the WL Sips 2.0 offer so that the configuration of your merchant ID is consistent with the expected.

The fields to be used in the payment request will therefore be:

TransactionReference AN35 Unique identifier of transaction

ou

s10TransactionReference. s10TransactionId N6 transactionReference is the default method to identify a transaction. s10TransactionReference.s10TransactionId is an alternative to identify a transaction, remaining compatible with the WL Sips 1.0.
s10TransactionReference. s10TransactionIdDate N8 (YYYYMMDD) The couple s10TransactionReference.s10TransactionId / s10TransactionReference.s10TransactionIdDate ensures the uniqueness of the transaction. At least one interface version must be used ( interfaceVersion field) equal to IR_HP_2.7.

How to switch from API to WL Sips 2.0 connector

This customisation is based on the use of the API Payment 1.0 Plugin and on the files given in example in the sample directory of this API.

The file contained in the sample directory of Payment 1.0 and named callrequest.php contains a certain amount of information to report in your new PHP file to prepare to make the form in POST mode of the payment request.

Note: all code examples are presented in PHP language and must be customised for actual use in production. They are not to reproduce like they are and are only there to quickly introduce how to connect to the Sips Paypage 2.0.

Files in the param directory

With the Payment 1.0, the default directory param contains the files parcom and pathfile with shop default settings. These files are no longer in use.

The new form used on Sips Paypage 2.0 must load the retrieval of information about the merchant's default settings and to connect to the Sips Paypage 2.0 to make the payment request.

The pathfile file, which contains the Payment installation paths on the merchant's server, is no longer in use: none of this information is useful for the Sips Paypage 2.0. This file will be deleted when the migration is complete.

Most of the data in the parcom file is stored in the merchant's configuration when registering with WL Sips 2.0. However, some data may be forced into the payment request if they remain compatible with the data known at the merchant's registration. Also, some other data (for example, the currency of the amount) remain mandatory in the request.

Parcom data Sips Paypage 2.0 request field Mandatory/Optional
AUTO_RESPONSE_URL automaticResponseURL Optional
RETURN_URL normalReturnURL Mandatory
PAYMENT_MEANS paymentMeanBrandList Optional
CURRENCY currencyCode Mandatory
LANGUAGE customerLanguage Optional
TEMPLATE templateName Optional

Form basic data

The new form must load the recovery of the information concerning the merchant and allowing to make the payment request, for example:

      //Initialisation des données commerçant
$merchantid=<valeur du merchantID Sips>;
$secretkey=<clé secrète du commerçant>;
$keyversion=<version de la clé secrète du commerçant>;


$tref=’test_tref01’;
    

Contrary to the Payment 1.0 where the data was sent to the response.exe executable contained in the bin directory, it will now be necessary to retrieve the field named Data containing the response data and check the Seal field containing the message fingerprint to be sent.

Data field calculation

Then calculating the Data field with the data of the request (here with an amount of 1 euro):

      $Data='amount=100|currencyCode=978|merchantid='.$merchantid.'|automaticResponseUrl=http://www.mon
_url_marchand.com/call_autoresponse.php|normalReturnUrl=http://www.mon_url_marchand.com/call_response.php
|transactionReference='.$tref.'|keyVersion='.$keyversion.'|customerLanguage=fr;
    

SEAL field calculation

The request settings (payment request) are sent through the customer's browser. Theoretically, it is possible for a hacker to modify the settings during the transmission of data to the payment server.

It is therefore necessary to add security to ensure the integrity of the transmitted settings of the transaction. As solution WL Sips responds to this need by signatures exchange, called message fingerprints.

Successful signature control involves two things:

  • the integrity of the request and response messages, no alteration during the exchange
  • the authentication of the sender and receiver as they share the same secret key

The calculation of the message footprinting is done by the hash of the field Data by the merchant secret key:

      $Seal=hash('sha256', $Data.$secretkey);
    

Form in POST mode

And finally, sending the form in POST mode with the data (example with the URL of the recipe environment):

      echo '<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
  <head>
  <meta http-equiv="content-type" content="text/html; charset=windows-1250">
  <title>REDIRECTION VERS PAGE DE PAIEMENT</title>
  </head>
  <body>
<form method="post" action="https://payment-webinit.test.sips-atos.com/paymentInit">';
echo '<input type="text" name="Data" size="300" value="'.$Data.'"><br>';
echo '<input type="text" name="InterfaceVersion" size="300" value="HP_2.7"><br>';
echo '<input type="text" name="Seal" size="300" value="'.$Seal.'"><br>';
echo '<br><input type="submit" value="Connexion a Sips 2.0">';   
echo '</form></body></html>';
    

Form in JSON mode

Please refer to the Integration guide to get help for setting up a cURL call with JSON.

Customisation of the recovery in payment response

The sample response files given in the sample directory are named call_response.php and call_autoresponse.php .

Contrary to the Payment 1.0 where the data was sent to the response.exe executable contained in the bin directory, it will now be necessary to retrieve the field named Data containing the response data and check the Seal field containing the received message fingerprint.

Response basic data recovery

The new form must load the recovery of the information concerning the merchant and allowing to make the payment request, for example:

      //Recupération des donnees de la reponse
$Data=htmlspecialchars($_POST[“Data”]);
$Seal=htmlspecialchars($_POST[“Seal”]);

//Separation de tous les champs
$tableau = explode ("|", $Data);
    

SEAL field calculation

Then calculating the message fingerprint using the hash of the Data field by the merchant secret key:

      $SealCalc=hash('sha256', $Data.$secretkey);
    

It will then be necessary to verify that the Seal corresponds to the Seal received in the request.

Test on the recipe environment

Beforehand, you must apply for the creation of a test shop then install the deliverables allowing to personalise the payment pages so that they are installed on the Sips Paypage 2.0 recipe environment.

Please refer to the Personalisation tool for payment pages document։ Custompages for help with the migration of the payment pages customisation.

DEBUG mode

The DEBUG mode no longer exists, but during the test in a recipe environment, each error is displayed clearly and thus makes it possible to better prepare the payment requests.

Removing references to WL Sips Payment 1.0

When installing Payment 1.0, the following tree structure is created on the server:

Once the Sips Paypage 2.0 files have nothing more to do with this tree structure, you can completely delete the present files.