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 Office 1.0 components to the Sips Office 2.0 connector in easy migration mode.
Who does this document target
This document is intended for merchants having the Worldline Sips 1.0 offer.
For full details on the Sips Office 2.0 use, please refer to the Sips Office JSON integration guide.
Topics not covered in this document:
- This document only shows the migration to the Sips Office JSON 2.0 which is a connector recommended on Sips Office 2.0. If you want to use the SOAP version, please refer to the Sips Office SOAP integration guide.
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 Office 2.0 assets
Contrary to the Sips Office 1.0, the Sips Office 2.0 no longer requires you to store files on your server for exchange.
Also, with the 2.0, only a request in JSON mode will be sent to the Sips Office 2.0 servers to make different payment processes (payment, cash management, wallet). No special components are needed to perform some types of operations.
Principle
What does change in Worldline Sips 2.0?
For the payment part:
- the new connection URL.
- the Worldline Sips certificate is replaced by a secret key.
You no longer install any files on your device, regardless of which Worldline Sips 2.0 interface you choose.
What you need to do
- Decide which Sips Office 2.0 connector to use (JSON, SOAP).
- Set up your Sips Office management requests by securing your new secret key.
- Use the customer test environment to test Sips Office 2.0 applications with an available login ID.
- Delete references to Sips Office 1.0 on your website (certificate, components, settings files, executable files).
Choosing the Sips Office 2.0 Connector
This document shows only the JSON connector (request sent to the Worldline Sips server in JSON mode).
If you want the payment server calls to be made in machine-to-machine mode with SOAP technology, please refer to the Sips Office SOAP document for setting up requests in this mode.
How to switch from Sips Office 1.0 to Sips Office 2.0 connector
The migration of Sips Office 1.0 relies mainly on the migration of components installed with the latter. You should start by taking an inventory of the components you have under the component/services directory of your Sips Office 1.0 installation.
Files in the param directory
With the Sips Office 1.0, each component contains a param directory that contains the file pathfile with shop default settings and certificate. These files are no longer in use.
The pathfile file, which contains the Sips Office installation paths on the merchant's server, is no longer in use: none of this information is useful for the Sips Office 2.0. This file will be deleted when the migration is complete.
Exchanges with Sips Office 2.0
Contrary to the Sips Office 1.0, where the components are installed locally on your server, the Sips Office 2.0 exchanges are done by JSON request on the URL of the service concerned.
It will now calculate a field named Seal containing the fingerprint of the message to send.
SEAL field calculation
The request settings (payment request or cash management operation, wallet) are sent from machine to machine. 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 the security to ensure the integrity of the transmitted settings of the transaction. The solution Worldline Sips responds to this need by signatures exchange, called message fingerprints.
The 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 make as follows:
- the concatenation of the fields values in alphabetical order, without taking into account the keyVersion field and the sealAlgorithm field,
- UTF-8 encoding of the previous result data,
- HMAC with SHA256 encryption of data obtained with the secret key.
The calculation of the message footprinting can be summarised as follows:
$Seal=hash_hmac('sha256', $Data, $secretkey);Components migration
Each component, when available on the Sips Office 2.0, is replaced by a particular URL followed by the service concerned.
Also, refer to the chapters presented below to migrate each component on the Sips Office 2.0 as well as to the Integration guide document to know the details of the possible fields on each request.
Office component migration
This component, for the payment order part, is now available on the URL:https://office-server.sips-services.com/rs-services/v2/checkout/
The table below shows the service equivalence between Sips Office 1.0 and its version Sips Office 2.0.
| Service Sips Office 1.0 | Service Sips Office 2.0 | Comment |
|---|---|---|
| author | cardOrder | |
| elvauthor | directDebitOrder | paymentMeanBrand=ELV |
| directdebitorder | directDebitOrder |
For example, the URL used to perform the operation equivalent to author on Sips Office 1.0 will be: https://office-server.sips-services.com/rs-services/v2/checkout/cardOrder
This component, for the cash management part, is now available on the URL: https://office-server.sips-services.com/rs-services/v2/cashManagement
| Service Sips Office 1.0 | Service Sips Office 2.0 | Comment |
|---|---|---|
| validate | validate | |
| cancel | cancel | |
| credit | refund | |
| advice | referral | |
| duplicate | duplicate | |
| crediholder | creditHolder |
Checkout component migration
This component, for the 3-D Secure part, is now available on the URL: https://office-server.sips-services.com/rs-services/v2/checkout/
| Service Sips Office 1.0 | Service Sips Office 2.0 | Comment |
|---|---|---|
| card3D_CheckEnrollment | cardCheckEnrollment | |
| card3D_Order | cardValidateAuthenticationAndOrder | |
| card3D_Authenticate | cardValidateAuthentication | |
| merchantWallet3D_CheckEnrollment | walletCheckEnrollment |
This component, for the payment part by wallet, is now available on the URL:https://office-server.sips-services.com/rs-services/v2/checkout/
| Service Sips Office 1.0 | Service Sips Office 2.0 | Comment |
|---|---|---|
| merchantWallet_Order | walletOrder |
The Buyster payment method no longer exists and can no longer be used.
CashManagement component migration
This component, for the payment order part, is now available on the URL: https://office-server.sips-services.com/rs-services/v2/checkout/
| Service Sips Office 1.0 | Service Sips Office 2.0 | Comment |
|---|---|---|
| merchantwallet_credit | walletCreditHolder |
Diag component migration
This component, for the payment order part, is now available on the URL: https://office-server.sips-services.com/rs-services/v2/diagnostic/
| Service Sips Office 1.0 | Service Sips Office 2.0 | Comment |
|---|---|---|
| diagnosis | getTransactionData |
MerchantWallet component migration
This component, for the payment order part, is now available on the URL: https://office-server.sips-services.com/rs-services/v2/wallet/
| Sips Office 1.0 service | Sips Office 2.0 service | Comment |
|---|---|---|
| signInCard | * Not available * | The addCard function directly makes the signInCard․ |
| signOff | signOff | |
| addCard | addCard | The addCard function directly makes the signInCard․ |
| updatePaymentMean | updatePaymentMean | |
| deletePaymentMean | deletePaymentMean | |
| getWalletData | getWalletData | |
| getPaymentMeanData | getPaymentMeanData |
PayId component migration
The PayID component is the predecessor of the MerchantWallet component. Please refer to the chapter on the MerchantWallet component.
Paypal component migration
This component, for the payment part on Paypal, is now available on the URL: https://office-server.sips-services.com/rs-services/v2/checkout/
| Service Sips Office 1.0 | Service Sips Office 2.0 | Comment |
|---|---|---|
| Setcontext | paymentProviderInitialize | |
| Docontext | paymentProviderFinalize | |
| Getcontext | paymentProviderGetContext |
Test on the test environment
Beforehand, you must apply for the creation of a test shop. During this request, you have to specify the required services to test (payment, cash management, wallet). You can then test all the available operations. Please refer to the Integration guide document for setting up requests in this mode.
Removing references to Sips Office 1.0
When installing Sips Office 1.0, the following tree structure is created on the server:
Once the Sips Office 2.0 files have nothing more to do with this tree structure, you can completely delete the present files.
