WL SIPS DOCS

Release 22.6

go directly to content

Search by keywords

Payment Subscription 1.0 to Subscription 2.0 migration through duplication

To search in the page use Ctrl+F on your keyboard

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 the business rules related to your business. (payment on delivery, deferred payment, recurring payment, in instalments, etc.).

In order to comply with DSP2, it is necessary to switch from Subscription 1.0 to the new Subscription 2.0 solution.

The purpose of this document is to explain the migration from Subscription 1.0 to Subscription 2.0.

Topics not covered in this document:

  • This document only shows the migration to Sips Paypage 2.0 POST, recommended connector on Sips Paypage 2.0. If you would like to use the Sips Paypage 2.0 JSON connector, please refer to the dedicated guide.
  • This document only shows the migration to Sips Office 2.0 JSON, recommended connector on Sips Office 2.0. If you would like to use the Sips Office 2.0 SOAP connector, please refer to the dedicated guide.

This document is intended for merchants with a WL Sips 1.0 offer. It is intended to facilitate the migration to WL Sips 2.0.

For full details on how to use the Sips Paypage 2.0 payment pages, please refer to Sips Paypage 2.0 POST.

For full details on how to use Sips Office 2.0, please refer to Sips Office 2.0 JSON.

For full details on how to use Sips Office Batch 2.0, please refer to the Sips Office Batch XML or Sips Office Batch CSV documents.

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.

  • Ability to use a new transaction reference of 35 alphanumeric characters.
  • New URL.
  • Handling the selection of the means of payment is carried out by WL Sips.
  • The WL Sips certificate is replaced by a secret key.
  • The merchant no longer installs any files on their side, regardless of the WL Sips 2.0 interface they choose.
  • Decide which Sips Paypage 2.0 connector to use (POST, JSON).
  • Decide which Sips Office 2.0 connector to use (JSON, SOAP).
  • Decide which Sips Office Batch file format to use (XML or CSV).
  • Decide to stay with transactionId management or switch to transactionReference.
  • Set up your payment request by securing your new secret key.
  • Review the structure of your response files so they can be compatible with Sips Office Batch 2.0.
  • Review the processing of your response files in Sips Office Batch 2.0 format.
  • Use the customer test environment to test the Sips Paypage 2.0, Sips Office 2.0, or Sips Office Batch 2.0 applications with a connection identifier provided.
  • Request access to production.
  • Remove references to Subscription 1.0, to the PayId 1.0 component and/or to the Batch SUB on your site (certificate, settings files, executables).
  • Keep the subscriber's credit card expiry date in-house so they can register their new card when their old card expires.

By default, 2.0 connectors use a transactionReference to identify a transaction to the payment server. This identifier is unique for the duration of the merchant’s registration on WL Sips, it is not reusable for another transaction. If you would like to remain in transactionId / transactionDate mode, you need to request this from WL Sips when registering your merchant ID with the WL Sips 2.0 offer so that your merchant ID configuration is as expected.

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

TransactionReference AN35 The unique identifier of the transaction.

or

S10TransactionReference. S10TransactionId N6 transactionReference is the default way to identify a transaction. S10TransactionReference.s10TransactionId is an alternative to identify a transaction, while remaining compatible with WL Sips 1.0.

The collecting of the payment details is done on Sips Paypage 2.0.

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 Sips Paypage POST integration guide document for setting up requests in this mode.

How to switch from the Subscription 1.0 API to the Sips Paypage POST 2.0 connector

This tutorial is based on using the Subscription 1.0 API in PHP as originally packaged. However, this tutorial is transposable to other programming languages.

Attention: all code examples are presented in PHP language and can be customised for real use in production. They are not to be reproduced as is and are featured herein only to briefly introduce how to connect to Sips Paypage 2.0.

With the Subscription 1.0 API, the default param directory contains the default settings parcom and pathfile files for the webshop. These files are now no longer used.

The new form used on Sips Paypage 2.0 must include the retrieval of the merchant's default settings information that can be used to log in to Sips Paypage 2.0 to complete the payment request.

The pathfile file, containing the Subscription 1.0 installation paths on your server, is no longer used, as none of this information is useful to Sips Paypage 2.0. This file will therefore be deleted when the migration is complete.

Most of the data in the parcom file is saved in the merchant configuration when it is registered with WL Sips 2.0. However, some data may be forced into the payment request if it remains compatible with the data known when registering the merchant. Also, some other data (for example, the amount currency) remains mandatory in the request.

parcom data Scope of the Sips Paypage 2.0 request Required/Optional
sub_automatic_response_url automaticResponseURL Optional
sub_normal_return_url normalReturnURL Required
card_list paymentMeanBrandList Optional
currency_code currencyCode Required
language customerLanguage Optional
templatefile templateName Optional

The new form should include the retrieval of merchant information to set up the payment request, for example:

//Merchant data initialisation
 $merchantid=<WL Sips merchantId value>;
 $secretKey=<merchant secret key>;
 $keyVersion=<merchant secret key version>;
 $tref='tref01';

Unlike the Subscription 1.0 API where data was sent to the recordabo.exe executable contained in the bin directory, You will now have to calculate a field named data containing the query data and a seal field containing the fingerprint of the message to be sent.

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;

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 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 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 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 WL Sips 2.0">';   
echo '</form></body></html>';

Please refer to the Sips Paypage JSON to get help for setting up a call in JSON.

The automatic and manual responses will be adapted to the versions presented on Subscription 1.0.

The sample response processing files in the example directory are named call_responseabo.php and call_autoresponseabo.php.

Unlike Subscription 1.0 where the data was sent to the responseabo.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 fingerprint of the received message.

The new form must include the retrieval of the response information to interpret the result of the payment request, for example:

// Retrieving the response data
$Data=htmlspecialchars($_POST[“Data”]);
$Seal=htmlspecialchars($_POST[“Seal”]);

//Separating all fields
$tableau = explode ("|", $Data);

In order to keep track of the transaction and customer data , it is important to back up this data:

Data Notes
maskedPan Allows you to customise the views of the customer.
panExpiryDate Will allow you to notify the customer for the addition of a new card.
s10TransactionId Only if you are in transactionId/transactionDate mode.​ This data will allow you to save the initial transaction to be taken up during the duplicate operation.
s10TransactionDate Only if you are in transactionId/transactionDate mode. This data will allow you to save the initial transaction date.

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.

When you install Subscription 1.0, the following tree is created on the server:


List of subscription 1.0 folders and files

A subscription folder containing the folders bin, example, logo and param and the files uninstall.exe and Version.txt.

Since the Sips Paypage 2.0 files no longer have anything to do with this tree, you can completely delete the files.

A change in the naming of files is required:

  • The request file needs to be transmitted in an archive in a ZIP format archive. The archive must be named OFBREQxx.ZIP. The file must be named [Sips Office Batch].[Alias].[Date].[time].[File Format].
  • The response file is transmitted in an archive in ZIP format. The name of this archive is OFBREPxx.[Day].[Month].[Year].ZIP. The name of the file in this archive is OFFUBZ.OFFBAREP.[Alias].[Date]-[Time].[File Format].
  • You will have to adapt the writing of your file. You can choose between two formats: XML or CSV.
  • Unlike the SUB batch file that was made up of three parts; header, detail, end, the Sips Office Batch 2.0 file is made up of four successive parts; FILE TYPE, header, BODY, END.
  • The format and version fields (which do not exist on the Subscription 1.0 batch) are mandatory on Sips Office Batch 2.0. Indeed, on Sips Office Batch 2.0, these fields depend on the type of service called:
Format Version Description of the service
office Must be set to 10 Acceptance of transactions and cash management operations.

Please refer to the Sips Office Batch XML and Sips Office Batch CSV documents for more information.

Example:
  • Sample file type on Batch SUB 1.0 (fields separated by ":" or spaces in SUB 1.0 format)
    03fr​023101122334455​000001A96ZQ701
    SOBSIMS33649927​0000000001000978
    ::customer.email@​worldline.com159
    00106556e55fe2f863​b831052020122329
    MASTERCARD:​5133.4404202200
  • Sample CSV file type on Sips Office Batch 2.0 (fields separated by ";" in SOB 2.0 CSV format)
    FILE;request;office;v10
    HEADER;023101122334455;
    2020-08-17+0200;1​11:19:16+0100;WALLETORDER
    ;1023101122334455​;SOBSIMS62958901
    ;1000;;;978;2;​AUTHOR_CAPTURE;
    customer.email@worldline.com
    ;1000000000000000011​;123.6.53.68;;;
    INTERNET;159;;;;;;;;​;;;;;;;;440012;20200817;;
  • Sample XML file type on Sips Office Batch 2.0
    <file type="request" format="office" version="v10">
        <header>
            <remitterId>023101122334455</remitterId>
            <date>2020-08-17+02:00</date>
            <time>11:19:10+01:00</time>
            <sequence>1</sequence>
        </header>
        <body>
            <walletOrder recordSequence="1">
                <merchantId>023101122334455</merchantId>
                <transactionReference>SOBSIMS33649927</transactionReference>
                <amount>599</amount>
                <currencyCode>978</currencyCode>
                <captureDay>2</captureDay>
                <captureMode>AUTHOR_CAPTURE</captureMode>
                <customerEmail>customer.email@worldline.com</customerEmail>
                <customerIpAddress>123.6.53.68</customerIpAddress>
                <merchantWalletId>100000000000000000011</merchantWalletId>
                <paymentMeanId>1</paymentMeanId>
                <orderId>159</orderId>
            </walletOrder>
        </body>
        <end nbRecord="1"/>
    </file>

On the SUB batch, 3 response types are returned: the global response, the per subscriber response, and the per acquirer response. On Sips Office Batch 2.0 there are the responses when checking the file and the responses caused by an operation.

For file checking responses, there are several levels of response codes when processing a file by Sips Office Batch. These response codes are returned in the processingResponseCode field on Sips Office Batch 2.0. Several overall checks are performed before the file is processed. If any of these checks fail, the file is completely rejected (processingResponseCode is not equal to either 00 or 01). The returned response file contains the overall processing result code in the processingResponseCode field in the file header.

Here is a summary of possible values for the processingResponseCode field (WL Sips 2.0) with a comparison of the overall response (SUB batch):

Code processingResponseCode meaning (WL Sips 2.0) Code Overall response code meaning (SUB 1.0 batch)
00 File processed successfully: the file contains the list of operations. 00 File processed successfully (see code per subscriber for details).
01 File processed successfully: an operation has been associated with a merchant who is not linked to the remitter ID. The officeBatchResponseCode field will be set to 80 by the operation. N/A
02 File already processed: the file sequence number is lower than it should be. The correct number is sent in the message describing the error. 02 File already processed.
03 Sequence jump in the file sequence number. The file sequence number is higher than it should be. The correct number is sent in the message describing the error. 03 Sequence jump in the file sequence number.
04 Technical issue. Internal issue. 99 Technical issue on the subscription server.
05 File is too large. N/A
06 The number of operations exceeds the maximum allowed quantity. The maximum number of operations has been reached. N/A
07 The counted number of operations is different from the number specified in the nbRecord field. N/A
08 Duplicate operation. N/A
09 Invalid record. 12 Invalid transaction (correct format, incorrect content).
10 Invalid file format: the file format is invalid (the error description will be returned in the "error details" tag). 01 Incorrect format.
11 Invalid remitter: the remitter declared in the header is invalid. 14 Unknown subscriber.
N/A 04 Inconsistent file (incorrect counter, invalid or missing header or end)
Other codes Invalid file: these codes are for older Sips Office Batch versions. N/A

For errors caused by an operation, since each operation is independent, it has its own response code stored in the officeBatchResponseCode field. This code indicates the field that is causing the problem.

For these codes, you can refer to the documentation Sips Office Batch XML – analysing errors by operation

Or Sips Office Batch CSV – analysing errors by operation

The acquirer response at the SUB batch level is not transmitted in Sips Office Batch 2.0.

To keep making subscriptions, you will need to use the duplicate function that will allow you to create a new transaction from the data of an initial transaction, made on Sips Paypage 2.0. You can refer to the documentation Sips Office Batch XML - duplicate function or Sips Office Batch CSV - duplicate function

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 document for setting up requests in this mode.

The PayId component contains a param directory that contains the default settings pathfile file of the shop and the certificate of the shop. These files are now no longer used.

The pathfile file, containing the paths to install Sips Office on the merchant's server, is no longer used, as none of this information is useful to Sips Office 2.0. This file should be deleted when the migration is complete.

Unlike the PayId component that is installed locally on your server, exchanges with Sips Office 2.0 are performed by JSON request on the relevant service URL.

It will now be necessary to calculate a field named seal and containing the fingerprint of the message to be sent.

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);

The PayId component will be replaced by the duplicate operation. It will allow you to create a new transaction from the data of an initial transaction, made on Sips Paypage 2.0. Please refer to the Sips Office JSON - duplicate function or Sips Office SOAP - duplicate function documentation.

You will first need to ask for a test shop to be created and then for the deliverables allowing the payment pages customisation to be installed so they are available on the Sips Paypage 2.0 test environment.

Please refer to the Custompages payment pages customisation help document.

You will first need to ask for a test shop to be created. When making this request, you will need to specify that you would like to test the Sips Office Batch 2.0 solution. Indeed, a configuration of the test shop is necessary for the exchange of files between our server and your SFTP account to take place.


description of api and connectors used before and after the migration

Before migrating, you use the subscription 1.0 for the first payment and the Batch SUB 1.0 API for the subsequent deadlines. After the migration, you use Sips Paypage for the first payment and then the duplicate function of Sips Office Batch for the subsequent deadlines.

You will first need to ask for a test shop to be created. When making this request, it will be necessary to specify the services you would like to test (payment, cash management, wallet). You will then be able to test all available operations. Please refer to the document pertaining to the setting up of requests in this mode.


description of api and connectors used before and after the migration

Before migrating, you use the subscription 1.0 for the first payment and the Batch SUB 1.0 API for the subsequent deadlines. After the migration, you use Sips Paypage for the first payment and then the duplicate function of Sips Office for the subsequent deadlines.

This site uses trackers to improve your experience, perform analysis and researches on your use of WL Sips documentation website.
You have several options:
Closing this banner you refuse the use of trackers on your device.

Configuration