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 the implementation steps of the Sips Walletpage SOAP solution up to live operations.

Who does this document target?

This document is intended for merchants wishing to subscribe to the WL Sips offer and use a connector based on HTTPS exchanges in SOAP mode between their websites and the WL Sips servers, so as to enable their customers to manage their OneClick or subscriber wallets.

It is an implementation guide for your technical team.

To get an overview of the WL Sips solution, we advise you to consult the following documents:

  • Functional presentation
  • Functionality set-up guide
  • OneClick payment
  • Subscription payment

Prerequisites

Knowledge of standards related to web programming languages used today, such as Java, PHP or .Net, is necessary to develop a connection to Sips Walletpage SOAP .

Note: all code sections in this document are provided as samples, you will need to adapt them to your website for them to be fully operable.

Secret key management

Upon your subscription, Worldline provides a secret key on the Sips Download extranet that will allow you to secure exchanges between your website and the WL Sips server.

You are responsible for looking after this key and should take all measures to:

  • Restrict access to the key
  • Safeguard it by encrypting it
  • Never copy it onto a non-secure disc or device
  • Never send it (via e-mail or regular mail) in a non-secure method.

A secret key compromised (and used by a malicious third party) might disrupt the regular operation of your shop and might in particular generate unauthorised sales or cash transactions (e.g. refunds).

IMPORTANT: in the event that a secret key is compromised, you are required to ask as quickly as possible for its revocation then for its renewal via the Sips Download extranet (please refer to the "Secret key revocation and renewal" section in the Quick start guide).

The very same secret key is used on the various Sips Paypage , Sips Office , Sips In-App and Sips Walletpage connectors.

IMPORTANT: a secret key is associated with a version. After getting a new secret key, you must modify your request and populate the keyVersion field with the new version, otherwise you will get an answer code 34 (suspected fraud).

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

Understanding customer wallet management with Sips Walletpage SOAP

The wallet management process works as follows:

1. When the customer initiates the wallet management step, a request must be sent to the Sips Walletpage SOAP connector the URL of which is provided by Worldline . The request is then checked, and encrypted if it is valid (it is named RedirectionData in the system). The request is sent through a POST form via HTTPS. Any other solution that can sends such requests also works.

2. The merchant's website redirects the calling application to the wallet management interface, with the encrypted request. The latter is decrypted, and Sips Walletpage enables the customer to perform various operations on their wallet. For the customer to be able to return to your site, a response is created and sent to the response URL provided in workflow No. 1.

There are two independent response notifications:

3. The wallet management server sends the manual response to the manual response URL using the HTTP(S) POST method. This URL is supplied in the wallet management request when the customer clicks on the “Back to shop” button or link on the wallet management page. This is why the normal response URL is also the page the customer is redirected to when wallet management operations are over. As nothing guarantees that the customer will click on this link, the receipt of the manual response cannot be guaranteed either.

4. Automatic responses are sent separately from manual responses. They also use the HTTP(S) POST requests sent by the wallet management servers, but this time, they use the automatic response URL specified in the wallet management request. You will receive the response when the customer clicks on the “Back to shop” button or if the wallet management session expires.

Getting started with Sips Walletpage SOAP in 5 steps

Step 1: subscribing to the service

If your shop has not been registered yet, you must fill in the registration form (asking for the subscription service or the OneClick service) sent by Worldline and send it back to them.

If your shop has already been registered with WL Sips , you need to ask the technical contact to activate the subscription service or the OneClick service.

Note: if your wallet database is shared between several shops, you must specify it in your registration form or tell it to the technical support team.

If this information is not supplied, WL Sips defines a dedicated wallet database for your shop.

Step 2: managing your customers' wallets

The wallet management request is a call to a SOAP web service. In response, this web service will provide you with the URL to redirect the internet user to, and with the redirectionData and redirectionVersion fields. You must do this redirection via an HTML form using the POST method.

Generating the wallet management request

All the fields required for wallet management (please refer to the "Filling in the fields of the request" chapter) must be provided.

The value of the InterfaceVersion data element must be set to WMR_WS_ 2.6 .

Request syntax

The request is structured in compliance with the SOAP format.

Sample wallet management request:
      <soapenv:Body>
      <urn:walletManagementInit>
         <urn:input>
            <urn:responseKeyVersion>1</urn:responseKeyVersion>
            <urn:merchantWalletId>9865578</urn:merchantWalletId>
            <urn:requestDateTime> 2014-12-19T14:06:06.273+01:00</urn:requestDateTime>
            <urn:interfaceVersion>WMR_WS_2.5</urn:interfaceVersion>
            <urn:merchantId>011223744550001</urn:merchantId>
         <urn:normalReturnUrl>http://www.normalreturnurl.com</urn:normalReturnUrl>
         </urn:input>
      </urn:walletManagementInit>
   </soapenv:Body>
    

Securing the request

The request includes the transaction parameters and is sent by the customer's web browser. Theoretically, a third party can intercept the request and modify its content before the data reaches the payment server.

Therefore it is necessary to strengthen security so as to ensure the integrity of the parameters of the transaction sent. The WL Sips solution meets this challenge by exchanging signatures. An effective signature control comprises two elements:

  • The integrity of the request and response messages.
  • The issuer and recipient authentication, as they share the same secret key.
IMPORTANT: if your secret key is compromised, or if you suspect this might be the case, you should always go to Sips Download to request a new one.

How to secure the request

The request is secured by calculating the hash value in line with the transaction parameters. Then, the secret key is added to it. All character strings are converted to UTF-8 before being hashed.

The hashing algorithm generates an irreversible result. When such a message is received, the recipient needs to recalculate the hash value and compare it with the one received. Any difference indicates that the data exchanged was falsified, or that the recipient and the issuer do not share the same secret key.

The result must be sent in hexadecimal format in the data element named Seal .

Calculating the Seal data element

HMAC-SHA algorithm

The value of the Seal data element is computed as follows:

  • Concatenation of data field values in the alphabetical order of field names (in accordance with ASCII character codes), without integrating the keyVersion and sealAlgorithm fields. Giving the field data , mentioned in the examples below.
    • as an example, a field that would be named authorMessageReference must be positioned before another field named authorisationId
  • Obtaining the UTF-8 encoding of the data from the previous result
  • HMAC with SHA256 encryption of bytes obtained with the secret key

This procedure can be summarised as follows:

      HMAC-SHA256( UTF-8(sortedDataValues), UTF-8(secretKey))
    
Note: by default, the seal is calculated with the HMAC-SHA-256 algorithm. For a seal to be computed with the SHA-256 algorithm, the input parameters of the request must include the sealAlgorithm field populated with the following value: “SHA-256”.
Hmac Sha256 sample code
  • Sample Hmac Sha256 encoding in Php 5
            
    <?php
    
    …
    
    // Seal computation thanks to hash sorted data hash with merchant key
    
    $data_to_send= utf8_encode($data)
    
    $seal=hash_hmac('sha256', $data_to_send, $secretKey);
    
    …
    …
    
    ?> 
          

    data_to_send and secretKey must use a UTF-8 character set. Please refer to the utf8_encode function for the conversion of ISO-8859-1 characters in UTF-8.

  • Sample Hmac Sha256 encoding in Java
            
    import java.security.InvalidKeyException;
    import java.security.NoSuchAlgorithmException;
    
    import javax.crypto.Mac;
    import javax.crypto.spec.SecretKeySpec;
    
    public class ExampleHMACSHA256 {
    
    /**
     * table to convert a nibble to a hex char.
     */
    static final char[] hexChar = {
       '0' , '1' , '2' , '3' ,
       '4' , '5' , '6' , '7' ,
       '8' , '9' , 'a' , 'b' ,
       'c' , 'd' , 'e' , 'f'};
    
    /**
     * Fast convert a byte array to a hex string
     * with possible leading zero.
     * @param b array of bytes to convert to string
     * @return hex representation, two chars per byte.
     */
    public static String encodeHexString ( byte[] b )
       {
       StringBuffer sb = new StringBuffer( b.length * 2 );
       for ( int i=0; i<b.length; i++ )
          {
          // look up high nibble char
          sb.append( hexChar [( b[i] & 0xf0 ) >>> 4] );
    
          // look up low nibble char
          sb.append( hexChar [b[i] & 0x0f] );
          }
       return sb.toString();
       }
    
    /**
     * Computes the seal
     * @param Data the parameters to cipher
     * @param secretKey the secret key to append to the parameters 
     * @return hex representation of the seal, two chars per byte.
     */
    public static String computeSeal(String data, String secretKey) throws Exception
    {
      Mac hmacSHA256 = Mac.getInstance("HmacSHA256");
      SecretKeySpec keySpec = new SecretKeySpec(secretKey.getBytes(), "HmacSHA256");
      hmacSHA256.init(keySpec);
    
      return encodeHexString(hmacSHA256.doFinal(data.getBytes()));
    }
    
    /**
     * @param args
     */
    public static void main(String[] args) {
    try {
    System.out.println (computeSeal("parameters", "key"));
    } catch (Exception e) {
    e.printStackTrace();
    }
    }
    
    }
          
  • Sample Hmac Sha256 encoding in .net

    (Carried out using a simple form called "Form1" containing two text fields to enter data and txtSecretKey , and another field to display  lblHEX ).

            
    using System;
    using System.Collections.Generic;
    using System.ComponentModel;
    using System.Data;
    using System.Drawing;
    using System.Text;
    using System.Windows.Forms;
    using System.Security.Cryptography;
    
    namespace ExampleDotNET
    {
        public partial class Form1 : Form
        {
            public Form1()
            {
                InitializeComponent();
            }
    
            private void cmdGO_Click(object sender, EventArgs e)
            {
                String sChaine = data.Text;
                UTF8Encoding utf8 = new UTF8Encoding();
                Byte[] encodedBytes = utf8.GetBytes(sChaine);
            
                byte[] shaResult;
                
                HMAC hmac = new HMAC.Create("HMACSHA256");
                var key = "YourSecretKey";
                hmac.Key = utf8.GetBytes(key); 
                hmac.Initialize();
    
                shaResult = hmac.ComputeHash(encodedBytes);
    
                lblHEX.Text = ByteArrayToHEX(shaResult);
            }
    
            private string ByteArrayToHEX(byte[] ba)
            {
                StringBuilder hex = new StringBuilder(ba.Length * 2);
                foreach (byte b in ba)
                    hex.AppendFormat("{0:x2}", b);
                return hex.ToString();
            }
    
        }
    }
          
Seal calculation validation

Once you have set up your seal calculation, here is a sample request to help you verify that you find the correct seal:

            <urn:walletManagementInit>
         <urn:input>
            <urn:urn:automaticResponseUrl>https://automatic-response-url.fr/</urn:urn:automaticResponseUrl>
            <urn:normalReturnUrl>https://normal-return-url/</urn:normalReturnUrl>
            <urn:customerContact>
                <urn:email>customer@email.com</urn:email>
            </urn:customerContact>
            <urn:interfaceVersion>WMR_WS_2.4</urn:interfaceVersion>
            <urn:keyVersion>1</urn:keyVersion>
            <urn:merchantId>011223344550000</urn:merchantId>
            <urn:merchantWalletId>wallet01</urn:merchantWalletId>
            <urn:requestDateTime>2018-08-08T16:31:22.589+02:00</urn:requestDateTime>
            <urn:seal>5aad3874f828bc427cd58833164bdfcfd8bcdf7b0921addc9ef82e6f82b027ee</urn:seal>
         </urn:input>
      </urn:walletManagementInit>
    

For the above request, the concatenated string which must be calculated is:

      https://automatic-response-url.fr/customer@email.comWMR_WS_2.4011223344550000wallet01https://normal-return-url/2018-08-08T16:31:22.589+02:00
    

With a HMAC-SHA-256 hash algorithm and the following secret key:

      secret123
    

The expected seal is:

      5aad3874f828bc427cd58833164bdfcfd8bcdf7b0921addc9ef82e6f82b027ee
    

Sample wallet management request

Below is a sample request in XML SOAP 1.1 format:

      <soapenv:Body>
      <urn:walletManagementInit>
         <urn:input>
            <urn:responseKeyVersion>1</urn:responseKeyVersion>
            <urn:merchantWalletId>9865578</urn:merchantWalletId>
            <urn:requestDateTime> 2014-12-19T14:06:06.273+01:00</urn:requestDateTime>
            <urn:interfaceVersion>WMR_WS_2.5</urn:interfaceVersion>
            <urn:merchantId>011223744550001</urn:merchantId>
         <urn:normalReturnUrl>http://www.normalreturnurl.com</urn:normalReturnUrl>
            <urn:responseEncoding>base64</urn:responseEncoding>
         </urn:input>
      </urn:walletManagementInit >
   </soapenv:Body>
    

Sample redirection form to Sips Walletpage SOAP

In return to this request, you should receive a response (also in  XML SOAP 1.1 ) containing the following fields:

Field name Description
redirectionData Request token to be provided during the redirection to the wallet management pages.
redirectionStatusCode List of possible response codes.
redirectionStatusMessage Short message providing the initialisation status.
redirectionUrl URL of the WL Sips wallet management pages you have to redirect the customer to.
redirectionVersion Redirection version.
seal Output seal.
reponseEncoding Encoding type used for responses.

If the wallet management initialisation was successful, the redirectionStatusCode field must be populated with "00". The redirectionData, redirectionVersion and redirectionUrl fields will likewise be populated to allow the redirection to the WL Sips wallet management pages.

To redirect the customer to the wallet management pages, you must implement a POST form sending the two following fields: redirectionData and redirectionVersion. The POST form shall redirect the customer to the URL provided in the redirectionUrl field.

Below is a sample form that must be submitted automatically:

      <form method="post" action=”value of redirectionURL”>
    <input type="hidden" name="redirectionVersion" value=”value of redirectionVersion”>
    <input type="hidden" name="redirectionData" value=”value of redirectionData”>
  </form>
    

Processing wallet management initialisation errors

All fields received by Sips Walletpage SOAP through the connector are checked individually. The table below lists the error messages that might be displayed during this step, and the solutions to be implemented.

redirectionStatusCode Description
00 Standard situation followed by the standard process used to display the wallet management pages.
03 The merchantId or the acquirer contract is not valid.
12 The transaction parameters are not valid. Please check the request parameters.
30 The request format is not valid.
34 Security issue: e.g. the calculated seal is not correct.
94 The transaction already exists.
99 Service temporarily unavailable.

There are four possible situations:

  • RedirectionStatusCode = 00

The user must be redirected to the payment page.

  • RedirectionStatusCode = 03, 12, 30, 34

These error codes indicate that the request has an issue that needs to be fixed. The payment process must be stopped.

  • RedirectionStatusCode = 99

The payment service is unavailable. Try to submit the request again. A new transaction reference must be used to prevent response code 94 from being returned.

Populating the request fields

Generic fields

Field Presence As of Version Comments
customerId Optional WMR_WS_ 2.0
customerIpAddress Optional WMR_WS_ 2.0
customerLanguage Optional WMR_WS_ 2.0
interfaceVersion Mandatory WMR_WS_ 2.0
merchantId Mandatory WMR_WS_ 2.0
merchantSessionId Optional WMR_WS_ 2.0
merchantWalletId Mandatory WMR_WS_ 2.0
normalReturnUrl Mandatory WMR_WS_ 2.0
automaticResponseURL Optional WMR_WS_ 2.0
paymentMeanBrandList Optional WMR_WS_ 2.0
walletActionNameList Optional WMR_WS_ 2.0
requestDateTime Mandatory WMR_WS_ 2.0 It is the date and time of which the request is sent. The date and time between Sips receives the request and requestDateTime should not exceed 2 minutes; otherwise the request will be refused.
responseKeyVersion Optional WMR_WS_ 2.0
returnContext Optional WMR_WS_ 2.0
templateName Optional WMR_WS_ 2.0
billingAddress Optional WMR_WS_ 2.0 See the Containers part
billingContact Optional WMR_WS_ 2.0 See the Containers part
customerAddress Optional WMR_WS_ 2.0 See the Containers part
customerContact Optional WMR_WS_ 2.0 See the Containers part
customerData Optional WMR_WS_ 2.0 See the Containers part
deliveryAddress Optional WMR_WS_ 2.0 See the Containers part
deliveryContact Optional WMR_WS_ 2.0 See the Containers part
fraudData Optional WMR_WS_ 2.0 See the Containers part
holderAddress Optional WMR_WS_ 2.0 See the Containers part
holderContact Optional WMR_WS_ 2.0 See the Containers part
holderData Optional WMR_WS_ 2.0 See the Containers part
paymentMeanData Optional WMR_WS_ 2.4 See the Containers part
intermediateServiceProviderId Optional WMR_WS_ 2.2
seal Mandatory WMR_WS_ 2.2
keyVersion Mandatory WMR_WS_ 2.2
sealAlgorithm Optional WMR_WS_ 2.2
mandateId Optional WMR_WS_ 2.4
transactionActors Optional WMR_WS_ 2.4
responseEncoding Optional WMR_WS_ 2.5
merchantName Optional WMR_WS_ 2.6
merchantUrl Optional WMR_WS_ 2.6

Optional fields pertaining to the customer's billing address

Content of billingAddress

Field As of Version Comments
addressAdditional1 WMR_WS_ 2.0
addressAdditional2 WMR_WS_ 2.0
addressAdditional3 WMR_WS_ 2.0
city WMR_WS_ 2.0
company WMR_WS_ 2.0
country WMR_WS_ 2.0
postBox WMR_WS_ 2.0
state WMR_WS_ 2.0
street WMR_WS_ 2.0
streetNumber WMR_WS_ 2.0
zipCode WMR_WS_ 2.0
businessName WMR_WS_ 2.4

Content of billingContact

Field As of Version Comments
email WMR_WS_ 2.0
firstname WMR_WS_ 2.0
gender WMR_WS_ 2.0
lastname WMR_WS_ 2.0
mobile WMR_WS_ 2.0
phone WMR_WS_ 2.0
title WMR_WS_ 2.0
initials WMR_WS_ 2.2
legalId WMR_WS_ 2.4
positionOccupied WMR_WS_ 2.4

Optional fields pertaining to the customer's delivery address

Content of deliveryAddress

Field As of Version Comments
addressAdditional1 WMR_WS_ 2.0
addressAdditional2 WMR_WS_ 2.0
addressAdditional3 WMR_WS_ 2.0
city WMR_WS_ 2.0
company WMR_WS_ 2.0
country WMR_WS_ 2.0
postBox WMR_WS_ 2.0
state WMR_WS_ 2.0
street WMR_WS_ 2.0
streetNumber WMR_WS_ 2.0
zipCode WMR_WS_ 2.0
businessName WMR_WS_ 2.4

Content of deliveryContact

Field As of Version Comments
email WMR_WS_ 2.0
firstname WMR_WS_ 2.0
gender WMR_WS_ 2.0
lastname WMR_WS_ 2.0
mobile WMR_WS_ 2.0
phone WMR_WS_ 2.0
title WMR_WS_ 2.0
initials WMR_WS_ 2.2
legalId WMR_WS_ 2.4
positionOccupied WMR_WS_ 2.4

Optional fields pertaining to fraud

Content of fraudData

Field As of Version Comments
bypassCtrlList WMR_WS_ 2.0
bypassInfoList WMR_WS_ 2.0
bypass3DS WMR_WS_ 2.0
allowedCardCountryList WMR_WS_ 2.0
deniedCardCountryList WMR_WS_ 2.0
allowedIpCountryList WMR_WS_ 2.0
deniedIpCountryList WMR_WS_ 2.0
allowedCardArea WMR_WS_ 2.0
deniedCardArea WMR_WS_ 2.0
allowedIpArea WMR_WS_ 2.0
deniedIpArea WMR_WS_ 2.0
riskManagementDynamicSettingList WMR_WS_ 2.0 List of container riskManagementDynamicSetting . See the Containers part

Content of riskManagementDynamicSetting

Field As of Version Comments
riskManagementDynamicParam WMR_WS_ 2.0
riskManagementDynamicValue WMR_WS_ 2.0

Optional fields pertaining to cardholder data

Content of holderAddress

Field As of Version Comments
addressAdditional1 WMR_WS_ 2.0
addressAdditional2 WMR_WS_ 2.0
addressAdditional3 WMR_WS_ 2.0
city WMR_WS_ 2.0
company WMR_WS_ 2.0
country WMR_WS_ 2.0
postBox WMR_WS_ 2.0
state WMR_WS_ 2.0
street WMR_WS_ 2.0
streetNumber WMR_WS_ 2.0
zipCode WMR_WS_ 2.0
businessName WMR_WS_ 2.4

Content of holderContact

Field As of Version Comments
email WMR_WS_ 2.0
firstname WMR_WS_ 2.0
gender WMR_WS_ 2.0
lastname WMR_WS_ 2.0
mobile WMR_WS_ 2.0
phone WMR_WS_ 2.0
title WMR_WS_ 2.0
initials WMR_WS_ 2.2
legalId WMR_WS_ 2.4
positionOccupied WMR_WS_ 2.4

Content of holderData

Field As of Version Comments
birthCity WMR_WS_ 2.0
birthCountry WMR_WS_ 2.0
birthDate WMR_WS_ 2.0
birthZipCode WMR_WS_ 2.0
nationalityCountry WMR_WS_ 2.0
newPassword WMR_WS_ 2.0
password WMR_WS_ 2.0

Optional fields pertaining to means of payment

Content of paymentMeanData

Field As of Version Comments
sdd WMR_WS_ 2.4 See the Containers part

Content of sdd

Field As of Version Comments
mandateAuthentMethod WMR_WS_ 2.4
mandateCertificationType WMR_WS_ 2.4

Setting up the wallet management request

Here is an example of how to set up the wallet management request for each funtionality available in Sips Walletpage SOAP (the details of these functionalities are described in the Functionality set-up guide, OneClick payment and Subscription payment ).

Restriction of customer functionalities for wallet management

By default, the customer has access to all the wallet management functionalities. To restrict access, you must specify the list of desired functionalities in the WalletActionNameList field (as in the example below to only allow to add or modify payment methods in one's wallet):

      <walletActionNameList>
 <walletActionName>ADDPM</walletActionName>
 <walletActionName>UPDATEPM</walletActionName>
</walletActionNameList>
    

Dynamic restriction of means of payment

The means of payment that will be available for addition to the wallet must be filtered using the paymentMeanBrandList field:

      <paymentMeanBrandList>
       <paymentMeanBrand>VISA</paymentMeanBrand>
       <paymentMeanBrand>PAYPAL</paymentMeanBrand>
</paymentMeanBrandList>
    

Customer's wallet identification

The customer's wallet ID must be populated in the merchantWalletId field.
      <merchantWalletId>1205987</merchantWalletId>
    

Provider acting on behalf of a merchant

You must pass the provider's ID in the intermediateServiceProvider field of the request, and use the provider's secret key to compute the Seal data element:

      <intermediateServiceProviderId>241891</intermediateServiceProviderId>
    

Response processing

There are two types of responses. Although the protocol, format and content of both responses are identical, the latter must be managed differently because they meet different needs.

Responses are HTTP(S) POST responses sent to the normalReturnUrl (mandatory) and automaticResponseUrl (optional) URLs specified in the request.

You must set up the system that will decode these responses so you can know the result of the request.

The following four data are defined in the responses:

Field name Comments/rules
Data Fields concatenation in the response.
Encode Type of encoding used to encode the Data field. This field is populated using the responseEncoding field from the request.
Seal Response message signature.
InterfaceVersion Connector interface version.

If the value of the Encode field is “base64” or “base64url”, the Data field must be encoded using Base64/Base64Url so the concatenated string of fields is reconstructed. The concatenated string is structured as follows: key1=value1|key2=value2, etc. The seal ( Seal field) of both responses is hashed with the same algorithm as the one supplied as input in the sealAlgorithm field. If no value was defined, SHA-256 is used by default.

Note: for a seal to be computed with the HMAC-SHA-256 algorithm, the input parameters of the request must include the sealAlgorithm field populated with the following value: “HMAC-SHA-256”.

The value of the Seal field is computed as follows:

For the HMAC-SHA algorithm:

  • use of the shared secret key to generate the HMAC variant of the message
  • use of the Data field only (encoded if the corresponding option is selected)
  • UTF-8 encoding of the data constituting the result of the previous operation
  • HMAC-SHA hashing of the bytes obtained

This procedure can be summarised as follows:

      HMAC-SHA256( UTF-8(Data), UTF-8(secretKey))
    

For the SHA-256 algorithm (although this is the default value, this algorithm is no longer recommended):

  • concatenation of the Data field and of the secret key (encoded if the corresponding option is selected)
  • UTF-8 encoding of the data constituting the result of the previous operation
  • SHA256 hashing of the bytes obtained

This procedure can be summarised as follows:

      SHA256( UTF-8(Data+secretKey ) )
    

Specifying the manual response URL

The main goal of the manual response is to redirect the customer to your website and specify the wallet management result.

The main WL Sips page includes the "Back" button with a link that redirects the customer to your website. Clicking on this button, the customer is redirected by WL Sips to the URL address included in the normalReturnUrl field provided in the request. The redirection is a HTTP(S) POST request that contains the data of the response. It is your responsibility to retrieve those paramaters and check the signature, thus ensuring the integrity of the response. Besides, you are in charge of displaying relevant messages to your customer (i.e. messages pertaining to the details of the response).

This normalReturnUrl field is also used for all payment results (cancellation, refusal, etc.) so as to perform the redirection to your site.

It is important to note that the receipt of the response cannot be guaranteed, since this response is sent by the customer’s Web browser. First, the customer may choose not to click on the link. Then he might encounter connection issues that block the transmission of this response. Therefore, your business processes cannot be based only on this response.

Note: the current version of InterfaceVersion is  HP_ 2.6 . Please refer to the WL Sips data dictionary for a comprehensive description of parameters included in the response.

Specifying the automatic response URL

The automatic response is sent only if the automaticResponseUrl field was sent in the wallet management request. If that is the case, the WL Sips server sends a HTTP(S) POST response to the URL address received.

The fields of the automatic response are the same as those of the manual response. The only difference between both procedures is that the automatic response is sent directly by the WL Sips server and does not go through the customer's Web browser. Therefore, this response is much more reliable since it is always sent. The WL Sips server does not expect any response after the automatic response has been sent.

It is your responsibility to retrieve the various data of the response, check the signature to make sure the fields of the response have not been tampered with, and update your back office.

Note: the current version of InterfaceVersion is HP_ 2.32 . Please refer to the Data dictionary for a comprehensive description of the settings included in the response.

Solving response receipt issues

Below is a list of the most common issues that block the receipt of automatic and manual responses. Please make sure you have checked them before you call the technical support:

  • Make sure the response URLs are provided in the wallet management request and are valid. To do this, simply copy and paste them into the address bar of your browser.
  • The supplied URLs must be accessible from the outside, i.e. the Internet. Access control mechanisms (login/password or IP address filter) or a firewall might block access to your server.
  • Access to response URLs must be confirmed in the notifications report of your web browser.
  • If you use a non-standard port, it must be within the 80 to 9999 range to ensure compatibility with WL Sips .

In some error cases, the WL Sips Server is unable to sign the response message. This applies, for instance, to the "Unknown merchantID" error and to the situation where the secret key is unkwown to WL Sips . For these particular reasons, the payment server will send a response without a signature in the Seal field.

Retrieving response fields

The content of Sips Walletpage 's automatic and manual web responses is identical.

Field name Version Comments
merchantId WMR_WS_ 2.0
keyVersion WMR_WS_ 2.0
merchantWalletId WMR_WS_ 2.0
merchantSessionId WMR_WS_ 2.0
customerId WMR_WS_ 2.0
customerIpAddress WMR_WS_ 2.0
returnContext WMR_WS_ 2.0
walletCreationDateTime WMR_WS_ 2.0
walletLastActionDateTime WMR_WS_ 2.0
walletPaymentMeanDataList WMR_WS_ 2.0 List of wallet payment means (see table below: fields in the walletPaymentMeanData element).
customerCompanyName WMR_WS_ 2.4
customerBusinessName WMR_WS_ 2.4
customerLegalId WMR_WS_ 2.4
customerPositionOccupied WMR_WS_ 2.4
Field name Version Comments
paymentMeanId WMR_WS_ 2.0
paymentMeanAlias WMR_WS_ 2.0
paymentMeanBrand WMR_WS_ 2.0
maskedPan WMR_WS_ 2.0
panExpiryDate WMR_WS_ 2.0
mandateId WMR_WS_ 2.4
transactionActors WMR_WS_ 2.4
Note: manual and automatic responses are encoded in base64 or in base64url.

Analysing the response to the wallet management request

If you carry out the authentication steps by means of an electronic seal, you should make sure the seal you received actually matches the seal you recomputed using the response fields.

In case the seal you received does not match the seal you recomputed, the wallet management session status is considered unknown, please contact the support.

Status Response fields Action to perform
Wallet management operation taken into account

walletLastActionDateTime populated with the current date and time

walletPaymentMeanDataList contains the means of payment in the wallet after the update

Store the following wallet data in your customer database:

  • paymentMeanAlias
  • paymentMeanId
  • paymentMeanBrand
  • PanExpiryDate
  • maskedPAN
Wallet management operation not taken into account

walletLastActionDateTime not populated with the current date and time

walletPaymentMeanDataList contains the means of payment in the wallet

If the wallet must be updated, then submit a request again.

Step 3: testing in the simulation environment

Once you have developed the connection to Sips Walletpage , you can do a test on the Sips Walletpage simulation server.

URL de simu du serveur https://payment-webinit.simu.sips-atos.com/services/v2/walletManagementInit

To do the test, use the id depending on the identification mode you wish to use:

Table 1. transactionReference generated by the merchant
Field Value
Merchant ID (merchantId) 002001000000001
Key Version (keyVersion) 1
Secret key 002001000000001_KEY1
Table 2. transactionReference generated by WL Sips
Field Value
Merchant ID (merchantId) 002001000000002
Key Version (keyVersion) 1
Secret key 002001000000002_KEY1
Table 3. transactionId generated by the merchant
Field Value
Merchant ID (merchantId) 002001000000003
Key Version (keyVersion) 1
Secret key 002001000000003_KEY1
Table 4. transactionId generated by WL Sips
Field Value
Merchant ID (merchantId) 002001000000004
Key Version (keyVersion) 1
Secret key 002001000000004_KEY1
Note: in the simulation environment, all operations are simulated. There is no interaction with the wallet database when adding or deleting means of payment.

Testing the addition of cards into the wallet

If you want to save a card, you will be redirected to the card details entry page where you will enter the detailed information of your card.

The following simulation rules apply:

  • The PAN must be 15 to 19 digits long (depending on the means of payment used).
  • The first six digits of the PAN determine the type of card as per the table below.
Card type Card number beginning with
AMEX 340000
VPAY 400000
VISA 410000
CB 420000
CB-VISA co-branded cards 430000
CB-VPAY co-branded cards 440000
CB-VISA_ELECTRON co-branded cards 450000
VISA-MASTERCARD co-branded cards 460000
MASTERCARD 510000
MAESTRO 500000
CB-MASTERCARD co-branded cards 520000
CB-MAESTRO co-branded cards 530000
  • you can simulate the successful or failed addition of a card by choosing from all response codes (see the Data Dictionary) and changing the last two digits. Only the answer code '00' simulates a successful addition.

Example : if you use card number 4100 00 00 0000 00 05 , the card is identified as VISA and the addition is not made (response code WL Sips 0 5 ).

Note: co-branded cards can be used with each of the brands specified in the table.

Moreover, all cards are enrolled in the 3-D Secure programme. You are redirected to the 3-D Secure simulation server where you choose the desired result for 3-D authentication.

Step 4: validating the switch to the production environment

Once you have tested your website connection to Sips Walletpage SOAP , you can validate the connection to the production version of Sips Walletpage SOAP .

Prior to this, we recommend you block public access to your website to prevent customers from carrying out transactions during this validation phase.

If you would like to customise your payment pages, you can use our CustomPages tool to test and view the rendering on payment pages. To do so, please refer to the CustomPages documentation to use the tool.

To switch to the production server, you must change the URL in order to connect to the WL Sips production server using the merchantId , secretKey and keyVersion credentials you received during the registration phase.

WL Sips URL https://payment-webinit.sips-atos.com/services/v2/walletManagementInit
merchantId Shop identifier received by e-mail
SecretKey Secret key you can retrieve from the Sips Download extranet
keyVersion Secret key version retrieved from Sips Download (obviously 1 for the first key)
Note: forgetting one of these 4 parameters is a common mistake that systematically results in an error.

How to validate proper functioning in the production environment

  • Initiate a wallet by adding a first card into it.
  • Make sure the wallet has been created.
  • Add a second card into an existing wallet if you have subscribed to the multi-card option.
  • Make sure the second card has been added.

Step 5: launching live operation

Once the validation for the transition to live operation has been carried out, make your site public so your customers can add means of payment to their wallets.