Introduction
Worldline 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 Sips Payment 1.0 to the Sips Paypage 2.0 as part of a simplified migration.
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 Sips Paypage JSON document.
Who does this document target?
This document is intended for merchants having the Worldline Sips 1.0 offer . It is intended to facilitate the migration to Worldline 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 (recommended connector).
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 Worldline Sips 2.0?
For the payment part:
- the new URL for the payment pages part
- the choice management of the payment method is deported to Worldline Sips
- the Worldline Sips certificate is replaced by a secret key
You no longer install any files on your device, regardless of the choosen Worldline Sips 2.0 interface.
What you need to do?
- Decide which Sips Paypage 2.0 connector to use (POST, JSON).
- Set up your payment requests by securing the new secret key.
- Use the customer test environment to test your Sips Paypage 2.0 applications with an available login ID.
- Delete references to Sips Payment 1.0 on your website (certificate, settings files, executable files).
Choosing the Sips Paypage 2.0 connector
This document shows only the POST connector (request sent to the Worldline 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 Sips Paypage POST integration guide document for setting up requests in this mode.
How to switch from API to Worldline Sips 2.0 connector
This customisation is based on the use of the API Sips 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 Sips 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.
Files in the param directory
With the Sips Payment 1.0, the default directory param contains the files parmcom 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 Sips Payment installation paths on your 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 parmcom file is stored in your merchant's configuration when registering with Worldline Sips 2.0. However, some data may be forced into the payment request if they remain compatible with the data known at your registration. Also, some other data (for example, the currency of the amount) remain mandatory in the request.
| Parmcom 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 your data 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 Sips 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 Worldline 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 your 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 test 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 TO PAYMENT PAGES</title>
</head>
<body>
<form method="post" action="https://payment-webinit.test.sips-services.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="Connection to Worldline Sips 2.0">';
echo '</form></body></html>';Form in JSON mode
Please refer to the Sips Paypage JSON to get help for setting up a call in JSON.
Customisation of the recovery in payment response
The automatic and manual responses will be adapted based upon the versions presented on Sips Payment 1.0.
The sample response files given in the sample directory are named call_response.php and call_autoresponse.php.
Contrary to the Sips 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 your data 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 your 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 simulation environment
Integrate the 2.0 connectors and test with simulation data
A basic knowledge of the standards for today’s web programming languages, such as Java, PHP or .Net, is required to implement the connection.
You will choose the connector you want to integrate. This choice is made according to your need. For example, if you are currently using Sips Payment 1.0, you can choose the Sips Paypage connector.
Your integration will necessarily be with a transaction_id generated on your side. This
configuration is mandatory so as to:
- allow your shop to run with 1.0 APIs and 2.0 connectors
- keep the formats of 1.0 reports
| Data | Transaction creation via Sips Paypage |
|---|---|
| transactionId provided by you | Standard processing |
| Absent transactionId | Reject code = 12 |
| transactionReference provided by you | Reject code = 12 |
| Absent transactionReference | OK |
| Additional reference generated by Worldline Sips | transactionReference |
| Response content | s10TransactionId s10TransactionIdDate transactionReference |
The online documentation site provides you with dedicated documents for each connector in the 'Developers' section. We invite you to refer to the documentation tree structure available in Appendix 2 herein for reference documents. You can use the online documentation site for all additional documentation.
After integration and to perform your tests, simulation data is available in the dedicated documentation of the connectors you integrate.
For the Sips Paypage connector, the simulation data
consists of a URL, a merchant_id and
a dedicated secret key, which will allow you to do some tests without
impacting your current workflow.
| Field | Value |
|---|---|
| Your ID (merchantId) | 002001000000003 |
| Key version (keyVersion) | 1 |
| Secret key | 002001000000003_KEY1 |
DEBUG mode
The DEBUG mode no longer exists, but during the test in a test environment, each error is displayed clearly and thus makes it possible to better prepare the payment requests.
Removing references to Sips Payment 1.0
When installing Sips 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.
