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 Sips Office 1.0 components to the Sips Office 2.0 connector.

Who does this document target

This document is intended for merchants having the WL Sips 1.0 offer.

For full details on the Sips Office 2.0 use, please refer to the Integration guide .

Topics not covered in this document:

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

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 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 connection URL.
  • the WL Sips certificate is replaced by a secret key.

You no longer install any files on your device, regardless of which WL Sips 2.0 interface you choose.

What the merchant must do?

  • Decide which Sips Office 2.0 connector to use (JSON, SOAP).
  • Decide to stay with transactionID management or go to transactionReference .
  • Set up his Sips Office management requests by securing his new secret key.
  • Use the customer recipe environment to test Sips Office 2.0 applications with an available login ID.
  • Make an access request in production.
  • Delete references to Sips Office 1.0 on his 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 WL 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 Integration guide document for setting up requests in this mode.

Choosing the transactionID or transactionReference mode

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

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 Transaction unique identifier

or

s10TransactionId N6 TransactionReference is the default method to identify a transaction.
s10TransactionIdDate N8 (YYYYMMDD) s10TransactionId is an alternative to identify a transaction, remaining compatible with the WL Sips 1.0. The couple s10TransactionId / s10TransactionIdDate ensures the uniqueness of the transaction.

How to switch from Sips Office 1.0 to WL Sips 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.

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

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 WL 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-atos.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-atos.com /rs-services/v2/checkout/cardOrder

This component, for the cash management part, is now available on the URL: https://office-server.sips-atos.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-atos.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-atos.com /rs-services/v2/checkout/

Service Sips Office 1.0 Service Sips Office 2.0 Comment
merchantWallet_Order walletOrder

This component, for the payment part on Paylib, is now available on the URL: https://office-server.sips-atos.com /rs-services/v2/checkout/

Service Sips Office 1.0 Service Sips Office 2.0 Comment
paymentProvider_Init paymentProviderInitialize
paymentProvider_Finalize paymentProviderFinalize

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-atos.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-atos.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-atos.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-atos.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 recipe 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.