Subscr. 1.0 to Subscr. 2.0 via walletOrder migration

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

Give a feedback about this page

Introduction

Worldline Sips is a PCI DSS compliant, secure multi-channel e-commerce payment solution. It allows you to accept and manage payment transactions by taking into account the business rules related to your activity. (payment on delivery, deferred payment, recurring payment, 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.

IMPORTANT: this migration will require the re-enrolment of your shop(s) in 2.0. It is not possible to keep a 1.0 shop as part of this migration.

Topics not covered in this document:

This document only shows the migration to Sips Paypage 2.0 POST, the 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, the 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.

Who does this document target?

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

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

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

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 documentation.

Regulation

Under DSP2, a transaction chaining must be performed to ensure authentication is in place for a series of payment transactions. This is because the initial transaction (Customer Initiated Transaction, or CIT), issued when the subscriber is registered, is distinguished from the recurring subsequent payment (Merchant Initiated Transaction, or MIT) that must be linked to the initial transaction (CIT).

For more information, please read our documentation on chaining.

Attention: 3DSv2 authentication in challenge mode is required when registering the subscriber (CIT).

Principle

	What remains with Worldline Sips 2.0	What changes with Worldline Sips 2.0
Data and formats	The subscriber base is kept.	New URL.
Subscriber registration pages	Subscriber registration pages are kept.
Transaction identification		Ability to use a new transaction reference of 35 alpha-numeric characters.
Configuration		You no longer install any files on your side, whatever the Worldline Sips interface you choose.
Security		The Worldline Sips certificate is replaced by a secret key.
File transfer	The file transfer is kept.
Means of payment	The means of payment used remain the same.	The management of the means of payment choice is carried out in Worldline Sips 2.0.
Legal		VADS contract with acquirer.

What you need to do

Decide which Sips Paypage 2.0 connector to use (POST, JSON).
Decide which Sips Office 2.0 connector to use (JSON, SOAP).
Decide on the Sips Office Batch file format (XML or CSV).
Decide to keep managing the transactionId or to switch to the transactionReference.
Implement your payment request by securing your new secret key.
Review the structure of your request files so that they are 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 by Worldline Sips.
Implement the production data (url, secret key and merchant_id).
Unmount the Subscription 1.0 API (certificate, configuration files, etc.).
Keep the subscriber's credit card expiry date internally so they can register their new card when their old card expires.

Correlation table

You currently use a single Worldline Sips 1.0 API to manage your subscriptions. In 2.0, we offer the use of several connectors with their specificities and features. As a guide, you please find below a correlation table:

Function	Worldline Sips 1.0	Worldline Sips 2.0
Payment details collecting	Subscription	Sips Paypage 2.0
Recurring payments in batch mode	Subscription	Sips Office Batch 2.0
Recurring payments in M2M mode	PayId	Sips Office 2.0

Tip: the choice of connector type is at your discretion. However, for simple use, we recommend Sips Paypage POST, Sips Office JSON and Sips Office Batch CSV.

Migration from Subscription to Sips Paypage 2.0 + Sips Office Batch 2.0

Migration from Subscription to Sips Paypage 2.0 + Sips Office 2.0

Diagram describing the migration from Subscription to Sips paypage 2.0 + Sips Office Batch 2.0.

Choosing the transactionId or transactionReference mode

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 Worldline Sips, it is not reusable for another transaction. If you wish to remain in transactionId / transactionDate mode, you must request this from Worldline Sips when registering your merchant ID with the Worldline 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.

s10TransactionReference. s10TransactionId

transactionReference is the default way to identify a transaction. s10TransactionReference.s10TransactionId is an alternative to identify a transaction, while remaining compatible with Worldline Sips 1.0.

Migration of subscription taking processing

The payment details collecting is done on Sips Paypage 2.0.

Choosing the Sips Paypage 2.0 connector

This document only introduces the POST connector (form sent to the Worldline Sips server in POST mode).

If you would like the first call to the payment server to be made in "machine to machine" mode with JSON technology, please refer to the Sips Paypage POST so as to make payment 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 can be adapted 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 they are and are only there to quickly present how to connect to Sips Paypage 2.0.

You can find all our code examples on our GitHub space.

Files in the param directory

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

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

The pathfile file, containing the paths to the Subscription 1.0 installation on the merchant 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 parmcom file is saved in the merchant configuration when it is registered with Worldline 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) remain mandatory in the request.

Parmcom data	Sips Paypage 2.0 request field	Required/Optional
sub_automatic_response_url	automaticResponseURL	Optional
sub_normal_return_url	normalReturnURL	Required
card_list	PpymentMeanBrandList	Optional
currency_code	currencyCode	Required
language	customerLanguage	Optional
templatefile	templateName	Optional

Web form core data

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

//Merchant data initialisation
 $merchantid=<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 request data and a Seal field containing the fingerprint of the message to be sent.

Calculating the `Data` field

The Data field is actually the name given to the full request message (= concatenation of all fields in the request).

The next step is to calculate the Data field with the data from the request (here with an amount of 1 euro):

$data='amount=100|currencyCode=978|merchantid='.$merchantid.'|automaticResponseUrl=http://www.my
 _merchant_url.com/call_autoresponse.php|normalReturnUrl=http://www.my_merchant_url.com/call_response.php
 |transactionReference='.$tref.'|keyVersion='.$keyversion.'|customerLanguage=en;

Calculating the `seal` field

The transaction parameters (payment request) are sent through the web user’s browser. Theoretically, it is possible for a hacker to change the parameters during data transmission to the payment server.

It is therefore necessary to add some security to ensure the integrity of the transmitted parameters of the transaction. The Worldline Sips solution meets this need through the exchange of signatures, called message fingerprints.

A successful signature check involves two things:

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

The calculation of the message fingerprint thanks to the hash of the data field by the merchant's secret key:

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

Form in POST mode

And finally, send the form in POST mode with data (example with the test environment URL):

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>REDIRECTING TO PAYMENT PAGE</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="Connecting to Worldline Sips 2.0">';   
echo '</form></body></html>';

Retrieving the payment response

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.

Retrieving the response core data

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 of the customer data, it is important to back up this data:

Data	Notes
maskedPan	Allows you to customise the views of the customer.
panExpiryDate	Allows 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 `walletOrder` operation.
s10TransactionDate	Only if you are in `transactionId/transactionDate` mode. This data will allow you to save the initial transaction date.

Calculating the `seal` field

The next step is to calculate the message fingerprint using the hash of the data field by the merchant secret key:

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

You will then need to chack that the seal matches the seal received in the request.

Deleting references to Subscription 1.0

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

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

Migrating the recurring payments

Batch mode: switching the Subscription batch to Sips Office Batch 2.0

Naming of files

A change in the naming of files is required:

The request file needs to be transmitted 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 a ZIP format archive. 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].

File structure

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 documentations for more information.

Example:

Sample file type on Batch SUB 1.0 (fields separated by ":" or spaces in SUB 1.0 format)

03fr023101122334455000001A96ZQ701
SOBSIMS336499270000000001000978
::customer.email@worldline.com159
00106556e55fe2f863b831052020122329
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;111: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>

Processing response code

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 a file is processed 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 includes the overall processing result code in the processingResponseCode field in the file header.

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

Code	`processingResponseCode` meaning (Worldline 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.

walletOrder operation

The walletOrder function will allow you to make payments using the information contained in your customers’ wallet. Please refer to the documentation Sips Office Batch XML - walletOrder function or Sips Office Batch CSV - walletOrder function.

M2M mode: switching from the PayId component to Sips Office 2.0

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.

Files in the param directory

The PayId component includes 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.

Exchanges with Sips Office 2.0

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.

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

walletOrder function

The walletOrder operation will allow you to make payments using one of the means of payment included in your customers' wallet. Please refer to the Sips Office JSON - walletOrder function or Sips Office SOAP - walletOrder function documentation.

Testing on the test environment

Once all of these migration steps have been completed, you can proceed to the testing phase on the test environment, using the test data available on our online documentation site.

You must first ask for a shop to be created on the test environment with all connectors implemented on your site as well as deliverables for customising the pages (for Sips Paypage).

On the other hand, as part of using the Sips Office Batch connector, specific settings must be put in place on your test shop for the exchange of files between our server and your FTP account to take place.

Lastly, you will need to tell us which services you would like to use (means of payments, cash transactions).

Appendices

Appendix 1: Document Tree

In this appendix you will find a summary table of the reference documents to accompany your migration:

Need	Reference documentation
Connectors	Sips Paypage POST
	Sips Office JSON
	Sips Office BatchCSV
MIT/CIT chaining	MIT/CIT chaining
3-D Secure	3-D Secure
Customising of pages	Migration of payment pages customisation (Paypage)
Reports	1.0 2.0 reports correlation
Fields	Data 1.0 and 2.0 correlation
Data dictionary	Data dictionary
Online documentation	Online documentationn
Sips Office Extranet	Sips Office Extranet
Merchant Extranet	Merchant Extranet
Sips Download	Sips Download
CustomPages	CustomPages

Need help?

Consulting the faq