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 Paypage POST 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 POST mode between their websites and the Sips Paypage POST payment servers.

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

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 Paypage POST .

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 payment with Sips Paypage POST

The general principle for a payment process is as follows:

1. When the customer makes a payment, a payment request must be sent to Sips Paypage POST . The URL of this connector is provided by Worldline . The request is then checked, and quantified if valid (it is named RedirectionData in the system). The request is sent through a POST form via HTTPS. Any other solution that can send such requests also works.

2. Sips Paypage POST redirects the calling application to the WL Sips payment pages. The customer must enter the information of the means of payment for the WL Sips payment server to process the transaction. It is worth noting that payment details can be entered directly on the server that provides the means of payment (e.g. PayPal or SEPA mandate). At the end of the payment process, whether successful or not, two responses are created and sent to the URL specified as part of flow No. 1.

There are two independent response notifications:

3. The payment server sends the manual responses in HTTP(S) POST format to the manual response  URL. This URL is specified in the payment request and is used when the customer clicks on the Continue button of the payment page. It is the page the user is redirected to at the end of the payment. As nothing guarantees that the customer will click on this link, you have no guarantee of receiving the manual response either.

4. Automatic responses are sent separately from manual responses. They also use the HTTP(S) POST requests sent by the WL Sips payment servers, this time using the automatic response  URL specified in the payment request. This means you receive the reponse as soon as the payment is made on the WL Sips payment pages.

Note: if the payment has failed and the customer is redirected to your website, it is no longer possible to return to the WL Sips payment pages and attempt to pay again or correct card data. The role of your website is to initialise a new payment request, beginning with calling the Sips Paypage connector.

Getting started with Sips Paypage POST in 5 steps

Step 1: registering the shop

In order to register your shop as live, you are required to complete the registration form sent by Worldline and send the form back to the latter.

When filling in the form, you must appoint an administrator contact and a technician contact so that Worldline can send you the information needed to launch your shop.

Worldline will then register your shop and e-mail you your merchant ID, together with your IDs and passwords for Sips Download (to retrieve the secret key) and (cash management).

Note: for Sips Office Extranet , the ID and password are sent to the administrator contact. For Sips Download , the ID is sent to the administrator contact and the password is sent to the technician contact.

Registering the shop is not needed to start integrating the connector and testing the connection on the customer test environment. It is possible to defer requesting shop registration until you perform live operation tests.

Step 2: making a payment

The payment request is an HTTPS POST request sent to the Sips Paypage POST connector. The request is sent via an HTML form using the POST method.

Note: You can consult the examples published on our GitHub repository to help you make a payment request.

Generating the payment request

Three mandatory data elements are provided in the payment request.

Data element name Description
Data Contains all the information about the transaction.
InterfaceVersion Defines the request version and the response exchanged with the WL Sips server.
Seal Used to validate the exchanged data integrity. The Seal element is computed using the Data data element and the secret key.

The InterfaceVersion element should be set to HP_ 2.33 .

Additional optional data elements are available:

Data element name Description
Encode Specifies the method used to encode the Data field element.
SealAlgorithm Specifies the algorithm used to compute the Seal field element.

Data field element syntax

The Data field element is structured using the following format:

      <fieldName1>=<fieldValue1>|<fieldName2>=<fieldValue2>|…|<fieldNameN>=<fieldValueN>
    

All fields required for the transaction (see details in the data dictionary) should be included in the character string. The order of fields is irrelevant.

Sample payment request with an amount of 55 euros:

      amount=5500|currencyCode=978|merchantId=011223744550001|normalReturnUrl=http://www.normalreturnurl.com|transactionReference=534654|keyVersion=1
    

A field can have several values:

      ..|fieldName=value1,value2, … ,valueX|…
    

Sample paymentMeanBrandList field with VISA and MASTERCARD as values:

      …|amount=5500|currencyCode=978|merchantId=011223744550001|normalReturnUrl=http://www.normalreturnurl.com|transactionReference=534654[paymentMeanBrandList=VISA,MASTERCARD|keyVersion=1|…
    

If the field is a container, you should use a full stop between the container name and the field name:

      ..|Container.fieldName1=fieldValue1|container.fieldName2=fieldValue2|……
    

Sample customerContact field containing customer's e-mail (me@email.com), first name and last name (John Smith):

      …|customerContact.email=me@email.com|customerContact.firstname=John|customerContact.lastname=Smith|…
    

If a field contains a list of complex objects, its representation is built using the following format:

      ..|<field1>=<value1>| <objectName>.<itemName= {<fieldNameA1>=<fieldValueA1>,<fieldNameA2>=<fieldValueA2>}, {<fieldNameB1>=<fieldValueB1>,<fieldNameB2>=<fieldValueB2>}, {<fieldNameC1>=<fieldValueC1>,<fieldNameC2>=<fieldValueC2>}| <fieldName2>=<fieldValue2>|……
    

Sample payment request with a list of complex objects for the shoppingCartDetail field, containing three products named apple, mango and pear:

      amount=5500|currencyCode=978|merchantId=011223744550001|normalReturnUrl=http://www.normalreturnurl.com
|transactionReference=534654|shoppingCartDetail.shoppingCartItemList={productName=apple,
productDescription=red},{productName=pear,productDescription=green},{productName=mango,productDescription=yellow}|keyVersion=1
    

Encoding the Data field

The Data field should be encoded using base64 or base64Url if it contains special characters (such as accented characters).

Note: since the signature is computed using the Data field, please note that it is the encoded Data value which is used for the request signature.

Request fields presence

Some fields of the payment request are required:

  • Only when using certain means of payment. Please read the dedicated means of payment guide to know the mandatory fields.
  • Depending on your shop configuration. Please read the Functionality set-up guide to find out the mandatory fields.
  • Only in certain use cases (e.g. recurring payment). Please read the Functionality set-up guide to know the mandatory fields.

Those fields are marked as "conditional".

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:

  • Content of the Data field sent in the POST form. Giving the data , mentioned in the examples below.
  • UTF-8 encoding of 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(Data), UTF-8(secretKey))
    
Note: by default, the seal is calculated with the SHA-256 algorithm, 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”.
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:

      automaticResponseURL=https://automatic-response-url.fr/|normalReturnURL=https://normal-return-url/|captureDay=0|captureMode=AUTHOR_CAPTURE|merchantId=011223344550000|amount=2500|orderId=ORD101|currencyCode=978|transactionReference=TREFEXA2012|keyVersion=1|transactionOrigin=SO_WEBAPPLI|returnContext=ReturnContext|orderChannel=INTERNET|customerContact.email=customer@email.com
    

For the above request, with a HMAC-SHA-256 hash algorithm and the following secret key:

      secret123
    

The expected seal is:

      ac2332b57a674aba5b28a03dae677fa2f4c1ae8a349ebbdd6772a098c7f29861
    
SHA-256 algorithm

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

  • Concatenation of the Data field element 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 bytes obtained.

This procedure can be summarised as follows:

      SHA256( UTF-8(Data+secretKey ) )
    
Sample Sha256 code
  • Sample Sha256 encoding in Php 5
      <?php
echo hash('sha256', $data.$secretKey);
?> 
    

The UTF-8 character set should be used for the Data and secretKey data. To convert ISO-8859-1 to UTF-8, use the utf8_encode function.

  • Sample Sha256 encoding in Java
      import java.security.MessageDigest;

public class ExampleSHA256 {

/**
 * 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
{
  MessageDigest md = MessageDigest.getInstance("SHA-256");
  md.update((Data+secretKey).getBytes("UTF-8"));

  return encodeHexString(md.digest());
}

/**
 * @param args
 */
public static void main(String[] args) {
try {
System.out.println (computeSeal("parameters", "key"));
} catch (Exception e) {
e.printStackTrace();
}
}
}
    
  • Sample Sha256 encoding in .NET

Completed using a simple form called "Form 1" containing two text fields to be filled in: data, txtSecretKey and another one to be displayed: 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 + txtSecretKey.Text;
            UTF8Encoding utf8 = new UTF8Encoding();
            Byte[] encodedBytes = utf8.GetBytes(sChaine);
        
            byte[] shaResult;
            SHA256 shaM = new SHA256Managed();
            shaResult = shaM.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();
        }

    }
}
    

Sample payment request

Below is a sample form with the Data field element not encoded:

      <form method="post" action="https://url.vers.serveur.sips/paymentInit">
    <input type="hidden" name="Data" value="amount=5500|currencyCode=978|merchantId=011223744550001|normalReturnUrl=http://www.normalreturnurl.com|transactionReference=534654|keyVersion=1">
    <input type="hidden" name="InterfaceVersion" value="HP_2.20">
    <input type="hidden" name="Seal" value="21a57f2fe765e1ae4a8bf15d73fc1bf2a533f547f2343d12a499d9c0592044d4">
    <input type="submit" value="Payer">   
  </form>
    

Processing payment initialisation errors

All fields received by Sips Paypage POST 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.

Note: messages are displayed on the simulation platform to help you validate the integration of your website. For security reasons, much simpler error messages are displayed on the production platform. Ex: "Error when processing the payment request. Please contact your dealer".
Message Root Solution

Unknown version interface: <version>

The <version> value in the InterfaceVersion field is unknown. Check the interface version in this user guide (the current version is HP_ 2.33 ).

Invalid keyword: <fieldName>= <field value>

The <fieldName> field is not expected in the payment request. Check the field names in the following chapter and in the Data dictionary.

Invalid field size: <fieldName>= <field value>

The <fieldName> field is of incorrect length. Check the field length in the Data dictionary.

Invalid field value: <fieldName >= <field value>

The <fieldName> field value is incorrect. Check the available field values in the Data dictionary.

Mandatory field missing: <fieldName>

The <fieldName> field is missing in the payment request. Please read the following chapter to check the mandatory fields in the payment request.

Unknown security version: <version>

The <version> value of the keyVersion field is unknown. Check the available key versions in Sips Download .

Invalid signature

The payment request seal checking has failed. This may be caused by an incorrect computing of the Seal data or may indicate the alteration of some fields after the signature was computed. Check that the computing of the Seal is carried out as described in the previous chapter. If it is, ask for a secret key change via Sips Download because the request has been altered.

Transaction already processed: <transaction reference>

A payment request with the same transactionReference has already been received and processed by the WL Sips servers. Check if the transactionReference field value is unique for the relevant transaction.

<Other messages>

In the case of technical errors, various messages may appear. Please get in touch with the technical support.

Processing the response to payment initialisation errors

In case of payment initialisation errors, the sending of a manual and/or automatic response can be activated depending on your configuration. Please get in touch with the support and they will activate this functionality.

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 to payment initialisation errors are HTTP(S) POST responses sent to the URLs populated through the manualErrorResponseInitPOST (optional) and automaticErrorResponseInitPOST (optional) fields specified in the request.

If you would like to use these responses, you must set up the system that decodes them so you can know the result of the payment. The following two fields are defined in the response:

Field name Comments/rules
Data Concatenation of fields in the response
Seal Signature of the response message

The concatenated string is structured as follows:

redirectionStatusCode | redirectionStatusMessage | merchantId | transactionReference | transactionId | transactionDate | transactionDateTime | amount | customerId | orderId | customerIpAddress

Here is an example of the Data field:

      redirectionStatusCode=12|redirectionStatusMessage=currencyCode contains invalid chars : [abc]|merchantId= 024729465300012|transactionReference= SIM20180118155728|transactionId=12345|transactionDate=20180412|transactionDateTime= 2018-04-12T10:14:31+02:00|amount=1000|customerId=CU-123|orderId=orderId1|customerIpAddress=127.0.0.1
    

This concatenated string is UTF-8 encoded before being hashed.

The authenticator ( Seal field) of both responses is hashed with the same algorithm as the one supplied as input in the sealAlgorithm field. If no value has been defined, SHA-256 is used by default.

Specifying the URL of the manual response to payment initialisation errors

The main aim of the manual response to initialisation errors is to redirect the customer to your website with the error cause, so you can make the right decision about him. For instance, in case of an error on data filled in by the customer, you may suggest to retry in a correct format. In case of an error beyond the customer's responsibility, you can invite him to contact you so as to solve the problem.

At the first step, a “Back” button is displayed on the WL Sips payment page, with a link that redirects the customer to your site. When the customer clicks on this link, the WL Sips server redirects them to the URL contained in the manualErrorResponseInitPOST field supplied in the request. The redirection is a HTTP(s) POST request that contains the response data as described above. It is your responsibility to retrieve these parameters and check the signature, thus ensuring the integrity of the response data. Besides, you must display relevant messages to your customer (i.e. messages pertaining to the details of the response).

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. Second, they might encounter connection issues that block the transmission of this response. Therefore, your business processes cannot be based only on it.

Specifying the URL of the automatic response to payment initialisation errors

The automatic response is sent only if the automaticErrorResponseInitPOST field was sent in the payment 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, it 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 that the fields of the response have not been tampered with, and update its back office.

Solving issues in receiving responses to initialisation errors

As with automatic and manual payment responses, you may face reception issues. The same tips apply to solving these issues (please refer to the 'Solving the response receipt issues' section).

Retrieving the fields of responses to initialisation errors

The content of automatic and manual responses sent by Sips Paypage in relation to initialisation errors is constant. Whatever the error encountered when initiating the payment, the response will include the following fields:

Field Comments
redirectionStatusCode
redirectionStatusMessage
merchantId
transactionReference
transactionId
transactionDate
transactionDateTime
amount
customerId
orderId
customerIpAddress

Populating the request fields

Generic fields

Field Presence As of Version Comments
amount Mandatory HP_ 2.0
automaticResponseUrl Optional HP_ 2.0
captureDay Optional HP_ 2.0
captureMode Optional HP_ 2.0
currencyCode Mandatory HP_ 2.0
customerEmail Optional HP_ 2.0
customerId Optional HP_ 2.0
customerLanguage Optional HP_ 2.0
fraudData Optional HP_ 2.0 See the Containers part
hashSalt1 Optional HP_ 2.0
hashSalt2 Optional HP_ 2.0
hashAlgorithm1 Optional HP_ 2.0
hashAlgorithm2 Optional HP_ 2.0
interfaceVersion Mandatory HP_ 2.0
merchantId Mandatory HP_ 2.0
merchantSessionId Optional HP_ 2.0
merchantTransactionDateTime Optional HP_ 2.0
merchantWalletId Optional HP_ 2.0
normalReturnUrl Mandatory HP_ 2.0
orderChannel Mandatory HP_ 2.0
orderId Optional HP_ 2.0
paymentMeanBrandList Optional HP_ 2.0
paymentMeanData Optional HP_ 2.0 See the Containers part
responseKeyVersion Optional HP_ 2.0
returnContext Optional HP_ 2.0
templateName Optional HP_ 2.0
transactionActors Optional HP_ 2.0
transactionReference Conditional HP_ 2.0 Mandatory if you do not use the s10TransactionReference or WL Sips does not calculate it for you, depending on your merchant configuration
transactionOrigin Optional HP_ 2.0
invoiceReference Optional HP_ 2.0
bypassReceiptPage Optional HP_ 2.0
customerIpAddress Optional HP_ 2.0
customerTimestampIpAddress Optional HP_ 2.26
bypassDcc Optional HP_ 2.0
instalmentData Optional HP_ 2.0 See the Containers part
billingAddress Optional HP_ 2.0 See the Containers part
billingContact Optional HP_ 2.0 See the Containers part
customerAddress Optional HP_ 2.0 See the Containers part
customerContact Optional HP_ 2.0 See the Containers part
deliveryAddress Optional HP_ 2.0 See the Containers part
deliveryContact Optional HP_ 2.0 See the Containers part
holderAddress Optional HP_ 2.0 See the Containers part
holderContact Optional HP_ 2.0 See the Containers part
customerData Optional HP_ 2.0 See the Containers part
paymentPattern Conditional HP_ 2.0
statementReference Optional HP_ 2.0
authenticationData Optional HP_ 2.0 See the Containers part
mandateId Optional HP_ 2.0
billingFirstDate Optional HP_ 2.0
customer3DSTransactionDate Optional HP_ 2.0
customerBillingNb Optional HP_ 2.0
customerDeliverySuccessFlag Optional HP_ 2.0
customerPhoneValidationMethod Optional HP_ 2.0
customerRegistrationDateOnline Optional HP_ 2.0
customerRegistrationDateProxi Optional HP_ 2.0
deliveryFirstDate Optional HP_ 2.0
evidenceAcquisitionDate Optional HP_ 2.0
evidenceNumber Optional HP_ 2.0
evidenceType Optional HP_ 2.0
valueDate Optional HP_ 2.0
deliveryData Optional HP_ 2.6 See the Containers part
shoppingCartDetail Optional HP_ 2.6 See the Containers part
holderData Optional HP_ 2.6 See the Containers part
s10TransactionReference Conditional HP_ 2.7 Mandatory if you do not use the transactionReference or WL Sips does not calculate it for you, depending on your merchant configuration. See the Containers part
holderAdditionalReference Optional HP_ 2.9
riskManagementCustomDataList Optional HP_ 2.9 List of container riskManagementCustomData . See the Containers part
intermediateServiceProviderId Optional HP_ 2.10
seal Mandatory HP_ 2.0
keyVersion Mandatory HP_ 2.0
sealAlgorithm Optional HP_ 2.10
paypageData Optional HP_ 2.11 See the Containers part
subMerchantId Optional HP_ 2.15
subMerchantShortName Optional HP_ 2.15
subMerchantCategoryCode Optional HP_ 2.15
subMerchantLegalId Optional HP_ 2.15
subMerchantAddress Optional HP_ 2.15 See the Containers part
orderContext Optional HP_ 2.16 See the Containers part
travelContext Optional HP_ 2.16 See the Containers part
responseEncoding Optional HP_ 2.19
subMerchantName Optional HP_ 2.20
subMerchantContractNumber Optional HP_ 2.20
customerAccountHistoric Optional HP_ 2.21 See the Containers part
merchantName Optional HP_ 2.23 Allow to change the name displayed on the 3-D Secure authentication page
merchantUrl Optional HP_ 2.29 Allow to change the merchant website url displayed on the 3-D Secure authentication page

Optional fields pertaining to the customer's billing address

Content of billingAddress

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

Content of billingContact

Field As of Version Comments
email HP_ 2.0
firstname HP_ 2.0
gender HP_ 2.0
lastname HP_ 2.0
mobile HP_ 2.0
phone HP_ 2.0
title HP_ 2.0
initials HP_ 2.11
legalId HP_ 2.17
positionOccupied HP_ 2.17
workPhone HP_ 2.21

Content of customerAccountHistoric

Field As of Version Comments
creationDate HP_ 2.21
numberOfAttemptsAddCard24Hours HP_ 2.21
numberOfPurchase HP_ 2.26
numberOfPurchase180Days HP_ 2.21
numberOfTransaction24Hours HP_ 2.21
suspiciousActivityIndicator HP_ 2.21
firstPurchaseDate HP_ 2.24
lastPurchaseDate HP_ 2.24
changeDate HP_ 2.27
passwordChangeDate HP_ 2.27
numberOfTransactionYear HP_ 2.27
addPaymentMeanDate HP_ 2.27
customerAccountId HP_ 2.27

Optional fields pertaining to the customer's address

Content of customerAddress

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

Content of customerContact

Field As of Version Comments
email HP_ 2.0
firstname HP_ 2.0
gender HP_ 2.0
lastname HP_ 2.0
mobile HP_ 2.0
phone HP_ 2.0
title HP_ 2.0
initials HP_ 2.11
legalId HP_ 2.17
positionOccupied HP_ 2.17
workPhone HP_ 2.21

Content of customerData

Field As of Version Comments
birthCity HP_ 2.0
birthCountry HP_ 2.0
birthDate HP_ 2.0
birthZipCode HP_ 2.0
nationalityCountry HP_ 2.0
newPassword HP_ 2.0
password HP_ 2.0
maidenName HP_ 2.18

Optional fields pertaining to the customer's delivery address

Content of deliveryAddress

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

Content of deliveryContact

Field As of Version Comments
email HP_ 2.0
firstname HP_ 2.0
gender HP_ 2.0
lastname HP_ 2.0
mobile HP_ 2.0
phone HP_ 2.0
title HP_ 2.0
initials HP_ 2.11
legalId HP_ 2.17
positionOccupied HP_ 2.17
workPhone HP_ 2.21

Content of deliveryData

Field As of Version Comments
deliveryChargeAmount HP_ 2.6
estimatedDeliveryDate HP_ 2.6
deliveryMode HP_ 2.6
deliveryMethod HP_ 2.6
deliveryOperator HP_ 2.6
estimatedDeliveryDelay HP_ 2.6
deliveryAddressCreationDate HP_ 2.21
electronicDeliveryIndicator HP_ 2.21
deliveryAddressStatus HP_ 2.26

Optional fields pertaining to fraud

Content of fraudData

Field As of Version Comments
bypassCtrlList HP_ 2.0
bypassInfoList HP_ 2.0
bypass3DS HP_ 2.0
allowedCardCountryList HP_ 2.0
deniedCardCountryList HP_ 2.0
allowedIpCountryList HP_ 2.0
deniedIpCountryList HP_ 2.0
allowedCardArea HP_ 2.0
deniedCardArea HP_ 2.0
allowedIpArea HP_ 2.0
deniedIpArea HP_ 2.0
riskManagementDynamicSettingList HP_ 2.0 List of container riskManagementDynamicSetting . See the Containers part
challengeMode3DS HP_ 2.21
addressDeliveryBillingMatchIndicator HP_ 2.21
nameDeliveryCustomerMatchIndicator HP_ 2.21
reorderProductIndicator HP_ 2.21
productAvailabilityIndicator HP_ 2.21
merchantCustomerAuthentMethod HP_ 2.23
merchantCustomerAuthentDateTime HP_ 2.27
merchantCustomerAuthentData HP_ 2.27
productAvailabilityDate HP_ 2.27

Content of riskManagementDynamicSetting

Field As of Version Comments
riskManagementDynamicParam HP_ 2.0
riskManagementDynamicValue HP_ 2.0

Optional fields pertaining to cardholder data

Content of holderAddress

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

Content of holderContact

Field As of Version Comments
email HP_ 2.0
firstname HP_ 2.0
gender HP_ 2.0
lastname HP_ 2.0
mobile HP_ 2.0
phone HP_ 2.0
title HP_ 2.0
initials HP_ 2.11
legalId HP_ 2.17
positionOccupied HP_ 2.17
workPhone HP_ 2.21

Content of holderData

Field As of Version Comments
birthCity HP_ 2.6
birthCountry HP_ 2.6
birthDate HP_ 2.6
birthZipCode HP_ 2.6
nationalityCountry HP_ 2.6
newPassword HP_ 2.6
password HP_ 2.6
maidenName HP_ 2.18

Optional fields pertaining to AMEX-EA (Enhanced authorization)

Content of orderContext

Field As of Version Comments
customerHostName HP_ 2.16
customerBrowserType HP_ 2.16
customerANI HP_ 2.16
customerANIInformationIdentifier HP_ 2.16

Content of travelContext

Field As of Version Comments
departureDate HP_ 2.16
passengerName HP_ 2.16
originAirport HP_ 2.16
numberOfRoutingCities HP_ 2.16
routingCityList HP_ 2.16
numberOfAirlineCarriers HP_ 2.16
airlineCarrierList HP_ 2.16
fareBasis HP_ 2.16
numberOfPassengers HP_ 2.16
destinationAirport HP_ 2.16
reservationCode HP_ 2.16

Optional fields pertaining to means of payment

Content of paymentMeanData

Field As of Version Comments
paypal HP_ 2.0 See the Containers part
sdd HP_ 2.0 See the Containers part
cofinoga3xcb HP_ 2.0 See the Containers part
passbe HP_ 2.0 See the Containers part
accord HP_ 2.0 See the Containers part
facilypay HP_ 2.0 See the Containers part
accordkdo HP_ 2.0 See the Containers part
presto HP_ 2.0 See the Containers part
cofidis3x HP_ 2.0 See the Containers part
unEuroCom HP_ 2.0 See the Containers part
cofidis4x HP_ 2.0 See the Containers part
cofinoga HP_ 2.14 See the Containers part
cetelem3x HP_ 2.15 See the Containers part
cetelem4x HP_ 2.15 See the Containers part
franfinance3xcb HP_ 2.18 See the Containers part
franfinance4xcb HP_ 2.18 See the Containers part
visaCheckout HP_ 2.21 See the Containers part
bcacb3X HP_ 2.24 See the Containers part
bcacb4X HP_ 2.24 See the Containers part
oney34x HP_ 2.29 See the Containers part

Content of paypal

Field As of Version Comments
landingPage HP_ 2.0
addrOverride HP_ 2.0
invoiceId HP_ 2.0
dupFlag HP_ 2.0
dupDesc HP_ 2.0
dupCustom HP_ 2.0
dupType HP_ 2.0
mobile HP_ 2.0
orderDescription HP_ 2.16

Content of sdd

Field As of Version Comments
mandateAuthentMethod HP_ 2.0
mandateUsage HP_ 2.0
mandateCertificationType HP_ 2.0

Content of cofinoga3xcb

Field As of Version Comments
creditIndicator HP_ 2.0

Content of passbe

Field As of Version Comments
settlementModeList HP_ 2.0

Content of accord

Field As of Version Comments
settlementMode HP_ 2.0
additionalAuthorisationNumber HP_ 2.0

Content of facilypay

Field As of Version Comments
settlementMode HP_ 2.0
settlementModeVersion HP_ 2.0
receiverType HP_ 2.0
depositRefundIndicator HP_ 2.0

Content of accordkdo

Field As of Version Comments
additionalAuthorisationNumber HP_ 2.0
blockAmountModification HP_ 2.18

Content of presto

Field As of Version Comments
paymentMeanCustomerId HP_ 2.0
financialProduct HP_ 2.0
prestoCardType HP_ 2.0

Content of cofidis3x

Field As of Version Comments
preScoreValue HP_ 2.0
cofidisDisplayCancelButton HP_ 2.0
cofidisPrivateData HP_ 2.0
basket HP_ 2.20

Content of unEuroCom

Field As of Version Comments
preScoreValue HP_ 2.0
cofidisPrivateData HP_ 2.0
basket HP_ 2.19

Content of cofidis4x

Field As of Version Comments
preScoreValue HP_ 2.0
cofidisDisplayCancelButton HP_ 2.0
cofidisPrivateData HP_ 2.0

Content of cofinoga

Field As of Version Comments
paymentMeanTradeOptionList HP_ 2.14 List of container paymentMeanTradeOption . See the Containers part

Content of paymentMeanTradeOption

Field As of Version Comments
paymentMeanTradingName HP_ 2.14
settlementModeList HP_ 2.14

Content of cetelem3x

Field As of Version Comments
cetelemPrivateMerchantData HP_ 2.15
cetelemPrivateData HP_ 2.15

Content of cetelem4x

Field As of Version Comments
cetelemPrivateMerchantData HP_ 2.15
cetelemPrivateData HP_ 2.15

Content of franfinance3xcb

Field As of Version Comments
authenticationKey HP_ 2.18
pageCustomizationCode HP_ 2.18
redirectionTimer HP_ 2.18
testEnvironment HP_ 2.18
birthPlaceCode HP_ 2.18
conversionCurrency HP_ 2.26
convertedAmount HP_ 2.26

Content of franfinance4xcb

Field As of Version Comments
authenticationKey HP_ 2.18
pageCustomizationCode HP_ 2.18
redirectionTimer HP_ 2.18
testEnvironment HP_ 2.18
birthPlaceCode HP_ 2.18
conversionCurrency HP_ 2.26
convertedAmount HP_ 2.26

Content of visaCheckout

Field As of Version Comments
visaCheckoutCallID HP_ 2.21

Content of bcacb3X

Field As of Version Comments
agencyCode HP_ 2.24
challengeMode3DS HP_ 2.24
numberOfCapturedTransaction HP_ 2.24
numberOfRejectedTransaction HP_ 2.24

Content of bcacb4X

Field As of Version Comments
agencyCode HP_ 2.24
challengeMode3DS HP_ 2.24
numberOfCapturedTransaction HP_ 2.24
numberOfRejectedTransaction HP_ 2.24

Content of oney34x

Field As of Version Comments
settlementMode HP_ 2.29

Optional fields pertaining to payment pages

Content of paypageData

Field As of Version Comments
bypassReceiptPage HP_ 2.11

Optional fields pertaining to the WL Sips 1.0 transactionId

Content of s10TransactionReference

Field As of Version Comments
s10TransactionId HP_ 2.7
s10TransactionIdDate HP_ 2.7 This field is computed by our server. There is no need to set a value in this field (as it will be ignored if set)

Optional fields pertaining to the shopping cart

Content of shoppingCartDetail

Field As of Version Comments
shoppingCartTotalAmount HP_ 2.6
shoppingCartTotalQuantity HP_ 2.6
shoppingCartTotalTaxAmount HP_ 2.6
mainProduct HP_ 2.6
shoppingCartItemList HP_ 2.6 List of container shoppingCartItem . See the Containers part
mainProductCategoryList HP_ 2.24
discountAmount HP_ 2.24
giftCardAmount HP_ 2.27
giftCardCurrencyCode HP_ 2.27
giftCardCount HP_ 2.27

Content of shoppingCartItem

Field As of Version Comments
productName HP_ 2.6
productDescription HP_ 2.6
productCode HP_ 2.6
productSKU HP_ 2.6
productUnitAmount HP_ 2.6
productQuantity HP_ 2.6
productTaxRate HP_ 2.6
productUnitTaxAmount HP_ 2.6
productCategory HP_ 2.6
productTaxCategory HP_ 2.6

Setting up the payment request

Here is an example of how to set up the payment request for each funtionality available in Sips Paypage POST (the details of these functionalities are described in the Functionality set-up guide).

Dynamic display of the means of payment

You need to use the paymentMeanBrandList field to filter the means of payment that will be displayed on the means of payment selection page:

      ..|paymentMeanBrandList=VISA,PAYPAL|..
    

Receipt display by WL Sips

The payment confirmation page that WL Sips displays by default can be deactivated using the paypageData.bypassReceiptPage field:

      ..|paypageData.bypassReceiptPage=Y|..
    

Payment channel

To choose your payment channel, you must fill in the orderChannel field in the payment request:

      …|orderChannel= INTERNET|..
    

End-of-day payment

For end-of-day payments, simply fill in the captureMode and captureDay fields:

      …|captureDay=0|captureMode=AUTHOR_CAPTURE|..
    

Deferred payment

For payments that must be captured N days after they were accepted online, simply fill in the captureMode and captureDay fields (3 days in the following example):

      …|captureDay=3|captureMode=AUTHOR_CAPTURE|..
    

Payment on despatch

For payments on despatch, the transaction is captured during your validation. You just need to fill in the captureMode and captureDay fields (in the following example, a period of up to 3 days before the validation is set):

      …|captureDay=3|captureMode=VALIDATION|..
    

Payment in instalments

For payments with instalments linked to a very same transaction, you need to populate the paymentPattern field with the INSTALMENT value and provide details about instalments in the instalmentData field (in the following example, €600 paid in 3 instalments) :

      …|amount=60000|…|transactionReference=tref1|…|paymentPattern=INSTALMENT|instalmentData.number
=3|instalmentData.datesList=20170412,20170512,20170612|instalmentData.transactionReferencesList
=tref1,tref2,tref3|instalmentData.amountsList=10000,30000,20000|..
    

Immediate payment

For immediate payment (available with certain means of payment only), the transaction is paid for during the online authorisation:

      …|captureMode=IMMEDIATE|..
    

Multicurrency acceptance

For multicurrency transactions, the currency code must be specified in the request. The payment currency is specified in the acquiring contract.

      …|currencyCode=840|..
    

Payment in foreign currencies

Acceptance and payment are carried out in the same currency, which must be specified in the request. Payment in foreign currencies is an option of the acquiring contract.

      …|currencyCode=826|..
    

Dynamic Currency Conversion (DCC)

If a Dynamic Currency Conversion (DCC) service is used, the reference currency code must be specified:

      …|currencyCode=978|..
    

3-D Secure dynamic deactivation

3-D Secure authentification can be deactivated dynamically using the fraudData.bypass3DS field:

      …|fraudData.bypass3DS=ALL|..
    

3-D Secure dynamic deactivation for OneClick payments

3-D Secure authentification can be deactivated dynamically for OneClick payments using the fraudData.bypass3DS field:

      …|fraudData.bypass3DS= MERCHANTWALLET|..
    

OneClick registration and payment

For OneClick payments, the customer's wallet ID must be provided in the merchantWalletId field.

      …|merchantWalletId=1205987|..
    

Provider acting on behalf of a merchant

The provider's ID must be passed in the intermediateServiceProvider field of the request, and the provider's secret key must be used to calculate the Seal field:

      ..|intermediateServiceProviderId=241591|..
    

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 with the result of the payment so you can make the right decision about it. For instance, if an error occurred, you may suggest to the customer to attempt the payment again. If the payment is successful, you can display a “thank you” message and start despatching the goods.

During the final step, a 'Continue' button is displayed on the WL Sips payment page, with a link that redirects the user to your site. When the customer clicks on this link, the WL Sips server redirects them to the URL contained in the normalReturnUrl field supplied in the request. The redirection is a HTTP(s) POST request that contains the data of the response as described above. It is your responsibility to retrieve these parameters 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.33 . Please refer to the 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 payment 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.33 . Please refer to the Data dictionary for a comprehensive description of the settings included in the response.
Attention: the automatic response is systematic, asynchronous and sent back through the network; it is inherently dependent on potential technical troubles on the various network elements and can now and then be received with a more or less substantial delay, or even never be received at all.

The automatic response is sent at the end of the payment. However, if your customer drops their purchase, for example by exiting their browser, the automatic response is sent when the user session expires (after 15 minutes of inactivity). Therefore, if your customer drops their purchase, you will only receive the automatic response (not the manual response), with an answer code set at 97, about 15 to 16 minutes after the customer has been redirected to the payment pages.

If an automatic response is not received after approximately 16 minutes, you can get the result of a payment by calling the getTransactionData method of the Sips Office interface, or by analysing the contents of the Transactions report. You may also search for a transaction and see its status using Sips Office Extranet .

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 payment 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 .
  • Context parameters cannot be added to the response URLs. However, some fields can still be used, e.g. the orderID or returnContext fields make it possible to provide extra parameters. You may also use the sessionId field to retrieve information about your customer at the end of the payment process.

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 the automatic and manual responses sent by Sips Paypage is identical. This content may vary according to the payment result (successful or other).

Note: in the responses, depending on the transaction status and the payment mean chosen, some fields can be null, empty or not returned. Please refer to the payment means documentations to know the fields present in the responses.
Field Version Comments
acceptanceSystemApplicationId HP_ 2.18
acquirerContractNumber HP_ 2.25
acquirerNativeResponseCode HP_ 2.12
acquirerResponseCode HP_ 2.0
acquirerResponseIdentifier HP_ 2.8
acquirerResponseMessage HP_ 2.8
additionalAuthorisationNumber HP_ 2.8
amount HP_ 1.0 Same as in the request
authentExemptionReasonList HP_ 2.31
authorisationId HP_ 1.0
authorisationTypeLabel HP_ 2.18
authorMessageReference HP_ 2.18
avsAddressResponseCode HP_ 2.17
avsPostcodeResponseCode HP_ 2.17
captureDay HP_ 1.0 Request field that WL Sips may override.
captureLimitDate HP_ 2.3
captureMode HP_ 1.0 Request field that WL Sips may override.
cardCSCResultCode HP_ 2.0
cardProductCode HP_ 2.12
cardProductName HP_ 2.12
cardProductProfile HP_ 2.12
cardProductUsageLabel HP_ 2.18
complementaryCode HP_ 1.0
complementaryInfo HP_ 2.0
creditorId HP_ 2.7
currencyCode HP_ 1.0 Same as in the request
customerBusinessName HP_ 2.17
customerCompanyName HP_ 2.17
customerEmail HP_ 2.0 Same as in the request
customerId HP_ 2.0 Same as in the request
customerIpAddress HP_ 2.0 Same as in the request, or recomputed by Sips Paypage if missing
customerLegalId HP_ 2.17
customerMobilePhone HP_ 2.1 Same as in the request
customerPositionOccupied HP_ 2.17
dccAmount HP_ 2.3
dccCurrencyCode HP_ 2.3
dccExchangeRate HP_ 2.3
dccExchangeRateValidity HP_ 2.3
dccProvider HP_ 2.3
dccStatus HP_ 2.3
dccResponseCode HP_ 2.3
dueDate HP_ 2.3
guaranteeIndicator HP_ 2.0
hashPan1 HP_ 2.0
hashPan2 HP_ 2.0
holderAuthentMethod HP_ 2.4
holderAuthentProgram HP_ 2.5
holderAuthentRelegation HP_ 2.0
holderContactEmail HP_ 2.20
holderAuthentStatus HP_ 2.0
holderAuthentType HP_ 2.24
instalmentAmountsList HP_ 2.6
instalmentDatesList HP_ 2.6
instalmentNumber* HP_ 2.6
instalmentTransactionReferencesList HP_ 2.6
interfaceVersion HP_ 1.0
intermediateServiceProviderOperationId HP_ 2.23
invoiceReference HP_ 2.10
issuerCode HP_ 2.12
issuerCountryCode HP_ 2.12
issuerEnrollementIndicator HP_ 2.0
issuerWalletInformation HP_ 2.9
keyVersion HP_ 1.0 Same as in the request
mandateAuthentMethod HP_ 2.2
mandateCertificationType HP_ 2.7
mandateId HP_ 2.3
mandateUsage HP_ 2.2
maskedPan HP_ 1.0
merchantId HP_ 1.0 Same as in the request
merchantSessionId HP_ 2.0 Same as in the request
merchantTransactionDateTime HP_ 2.0 Same as in the request
merchantWalletId HP_ 2.0 Same as in the request
orderChannel HP_ 2.0 Same as in the request
orderId HP_ 1.0 Same as in the request
panEntryMode HP_ 2.4
panExpiryDate HP_ 2.0
paymentAccountReference HP_ 2.31
paymentAttemptNumber HP_ 2.18
paymentMeanBrand HP_ 1.0
paymentMeanBrandSelectionStatus HP_ 2.14
paymentMeanData HP_ 2.2
paymentMeanId HP_ 2.6
paymentMeanTradingName HP_ 2.8
paymentMeanType HP_ 1.0
paymentPattern HP_ 2.0 Same as in the request
preAuthenticationColor HP_ 2.10
preAuthenticationInfo HP_ 2.10
preAuthenticationProfile HP_ 2.10
preAuthenticationProfileValue HP_ 2.14
preAuthenticationRuleResultList HP_ 2.14 List of preAuthenticationRuleResult objects.
Please see below for its content and format.
preAuthenticationThreshold HP_ 2.10
preAuthenticationValue HP_ 2.10
preAuthorisationProfile HP_ 2.14
preAuthorisationProfileValue HP_ 2.14
preAuthorisationRuleResultList HP_ 2.14 List of preAuthenticationRuleResult objects.
Please see below for its content and format.
responseCode HP_ 1.0
returnContext HP_ 1.0 Same as in the request.
s10TransactionId HP_ 2.9
s10TransactionIdDate HP_ 2.9
s10transactionIdsList HP_ 2.11
schemeTransactionIdentifier HP_ 2.31
scoreColor HP_ 2.0
scoreInfo HP_ 2.0
scoreProfile HP_ 2.0
scoreThreshold HP_ 2.0
scoreValue HP_ 2.0
secureReference HP_ 2.26
settlementMode HP_ 2.7
settlementModeComplement HP_ 2.13
statementReference HP_ 2.4
tokenPan HP_ 2.0
transactionActors HP_ 2.2 Same as in the request.
transactionDateTime HP_ 1.0
transactionOrigin HP_ 2.0 Same as in the request.
transactionPlatform HP_ 2.16 For future use (for now, its value is systematically set to ‘PROD’).
transactionReference HP_ 1.0
walletType HP_ 2.4

Optional fields pertaining to fraud checks

  • Content of preAuthenticationRuleResult
Field Version Comments
ruleCode HP_ 2.14
ruleType HP_ 2.14
ruleWeight HP_ 2.14
ruleSetting HP_ 2.14
ruleResultIndicator HP_ 2.14
ruleDetailedInfo HP_ 2.14
  • Content of preAuthorisationRuleResult
Field Version Comments
ruleCode HP_ 2.14
ruleType HP_ 2.14
ruleWeight HP_ 2.14
ruleSetting HP_ 2.14
ruleResultIndicator HP_ 2.14
ruleDetailedInfo HP_ 2.14

Syntax of lists of complex objects in responses

The format of a list of complex objects in automatic and manual responses is defined as follows ( bold text ):

      ..|amount=1000|currencyCode=978|      objectNameList=[{"field1":"value1a",
"field2":"value2a","field3":"value3a"…},{"field1":"value1b",
"field2":"value2b","field3":"value3b"}…]|transactionReference=1452687287828
|..
    
  • The content of the list is in square brackets [ ] .
  • Each entry of the list is in curly brackets { } .
  • Each field is represented as "fieldName" = "fieldValue" .
  • Please note that the name and the value of the field are both in double quotes "" .
  • Pairs of adjacent names/values are separated by a comma .

Sample preAuthorisationRuleResultList field

Breakdown of the fraud rules executed during preauthorisation (bold text):

      ..|amount=1000|currencyCode=978      |preAuthorisationRuleResultList=[
{”ruleCode”:"SC",”ruleType”:"NG",”ruleWeight”:"I",”ruleSetting”:"S",
”ruleResultIndicator”:"0",“ruleDetailedInfo”:"TRANS=1:5;
CUMUL=1000:99999900"},{”ruleCode”:"GC",”ruleType”:"NG",”ruleWeight”:
"D",”ruleSetting”:"N",”ruleResultIndicator”:"0",“ruleDetailedInfo”:
""},{”ruleCode”:"CR",”ruleType”:"NG",”ruleWeight”:"D",”ruleSetting”
:"S",”ruleResultIndicator”:"N",“ruleDetailedInfo”:"CARD_COUNTRY=USA"}]

|transactionReference=1452687287828|..
    

Payment response analysis

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 transaction status is considered unknown, please leave the transaction as it is, contact the support and do not re-execute the transaction in any automated way.

Status Response fields Actions to be carried out

Payment accepted

responseCode  = 00

acquirerResponseCode  = 00

garanteeIndicator  = Y,N,U, empty

You can deliver the order according to the guarantee level of your choosing ( garanteeIndicator field).

WL Sips fraud refusal

Go-No-Go

responseCode  = 05

complementaryCode  = XX

preAuthorisationRuleResultList

The payment has been refused by the WL Sips fraud engine that you configured.

Do not deliver the goods.

Analyse in detail the fraud rules executed by WL Sips to know the reason for the refusal ( preAuthorisationRuleResultList field).

WL Sips fraud refusal

Business Score

responseCode  = 05

scoreColor  = RED, BLACK

scoreValue  = X (transaction score)

scoreThreshold  = X,Y (orange threshold, green threshold)

The payment has been refused by the WL Sips fraud engine that you configured.

Do not deliver the goods.

Analyse in detail the fraud rules executed by WL Sips to know the reason for the refusal ( preAuthorisationRuleResultList field).

WL Sips fraud warning

Business Score

responseCode  = 05

scoreColor  = ORANGE

scoreValue  = X (transaction score)

scoreThreshold  = X,Y (orange threshold, green threshold)

The acquirer has authorised the payment, but the WL Sips fraud engine issued a warning due to the rules you configured.

Analyse in detail the fraud rules executed by WL Sips to know the reason for the warning ( preAuthorisationRuleResultList field).

If the transaction poses no risk, accept it using the acceptChallenge function.

If the transaction poses a risk, refuse it using the refuseChallenge function.

The acceptChallenge and refuseChallenge functions are available on the extranet and the Sips Office connectors.

3-D Secure refusal

reponseCode  = 05

holderAuthenStatus  = FAILURE

Customer authentication failed. This is not necessarily due to fraud. You can suggest to your customer to attempt the payment again with another means of payment, by generating a new request.

Banking refusal from the acquirer

responseCode  = 05

acquirerResponseCode  = XX

Authorisation refused for a reason not related to fraud.

You can suggest to your customer to attempt the payment again with another means of payment, by generating a new request.

Soft decline

responseCode  = 05

acquirerResponseCode  = A1

The payment has been refused by the acquirer because the 3-D Secure data is missing in the authorisation request.
Please try to pay again with a 3-D Secure payment process.

Fraud refusal from the acquirer

responseCode  = 34

acquirerResponseCode = XX

Authorisation refused because of fraud.

Do not deliver the order.

Refusal because the maximum number of attempts has been reached

responseCode  = 75

acquirerResponseCode  = XX

The customer made several failed attempts because the information entered was incorrect. There are two possibilities:

  • Your customer has difficulties entering their card information.
  • Carding attempt (search for possible card numbers).

Please contact your customer to define what to do next.

Refusal due to a technical issue

responseCode  = 90, 99

acquirerResponseCode  = 90 to 98

Temporary technical issue while processing the transaction.

Please tell your customer to attempt the payment again later.

Abandonment of payment responseCode = 97

acquirerResponseCode = not filled

Do not deliver the order.

Step 3: testing in the simulation environment

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

To do this test, you must use the credentials according to the transaction identification mode you wish to use:

Simulation server URL https://payment-webinit.simu.sips-services.com/paymentInit
transactionReference generated by the merchant

Merchant ID (merchantId)

Key version (keyVersion)

Secret key

002001000000001

1

002001000000001_KEY1

transactionReference generated by WL Sips

Merchant ID (merchantId)

Key version (keyVersion)

Secret key

002001000000002

1

002001000000002_KEY1

transactionId generated by the merchant

Merchant ID (merchantId)

Key version (keyVersion)

Secret key

002001000000003

1

002001000000003_KEY1

transactionId generated by WL Sips

Merchant ID (merchantId)

Key version (keyVersion)

Secret key

002001000000004

1

002001000000004_KEY1

This simulation server is not connected to the actual banking servers, because it serves to validate the connection between your website and the payment server.

Therefore, Sips Paypage simulates the call to the authorisation servers so you can test the various results of a payment.

Consequently, using actual cards is not necessary for tests.

Attention: since the merchantId is shared by all merchants and prospects, there might be transactionReference duplicates. This is why it is highly recommended to prefix all transactionReferences with the name of the future shop that will be used in the production environment. This also makes support easier if you call the technical support.

You use a generic shop without any payment page customisation. Step 4 will enable you to customise your payment pages.

Testing CB, VISA, MASTERCARD and AMEX transactions

The following simulation rules apply:

  • The PAN (Primary Account Number) must consist of 15 to 19 digits (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 begins 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
    MAESTRO 500000
    MASTERCARD 510000
    CB-MASTERCARD co-branded cards 520000
    CB-MAESTRO co-branded cards 530000
  • The WL Sips response code ( responseCode field) is computed from the last two digits of the card number.
  • The security code (CVV) consists of 3 or 4 digits. This value does not matter when it comes to the result of the simulation.

Example: if you use the card number 4100 00 00 0000 00 05 , the card will be identified as a VISA card and the payment will be refused ( WL Sips response code  05 ).

Note: if the computed WL Sips response code is not referenced, the transaction is accepted ( respondeCode  = 00).

Co-branded cards can be used with every brand defined in the table.

All cards are enrolled in the 3-D Secure programme. You will be redirected to the 3-D Secure simulation server on which you will choose the desired 3-D Secure authentication result.

Testing iDeal transactions

If you choose to test iDeal, you will be redirected to the simulation server that simulates iDeal transactions according to their amounts. You will then be taken back to the payment server that will display the receipt showing the transaction result.

Rules for simulating iDeal payments:

Transaction amount iDeal response
EUR2.00 Transaction cancelled
EUR3.00 Transaction expired
EUR4.00 Transaction not carried out
EUR5.00 Transaction failed
Other cases Transaction OK

Testing PayPal transactions

If you choose to test PayPal, you will be redirected to the simulation server that simulates PayPal transactions according to their payment result on PayPal’s side. You will then be taken back to the payment server that will display the receipt showing the result of the payment.

Step 4: validating the switch to the production environment

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

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-services.com/paymentInit
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 the proper functioning in the production environment

Immediately:

  • Make a transaction using a real payment card (your own, if possible). If the transaction is accepted, it will be sent to the bank to credit your merchant account and to debit the card account.
  • Check that your payment pages include your customisation settings.
  • Check the transaction via Sips Office Extranet , using the transactionReference.

The next day:

  • Make sure the transaction is in the Transactions report.
  • Check your account to make sure the operation was credited.
  • Refund the transaction via Sips Office Extranet (optional).

Two days later:

  • Check that the refund transaction is in the Operations report.
  • Make sure the debited amount has been refunded to your merchant account.

This validation process is also applicable to the PayPal means of payment.

Step 5: launching live operation

Once the validation for the transition to live operation has been carried out, make your site and/or application public so your customers can make purchases and payments.

On the same day:

  • Monitor acceptance rates (number of responseCode  00 per total number of transactions)
  • Check the nature of non-banking declines:
    • Technical issue: responseCode  90, 99
    • Fraud: responseCode  34
    • Max. number of payment attempts reached: responseCode  75
    • Abandonment: responseCode 97

The next day:

  • Check that all transactions processed (accepted and refused) are in the Transactions report.
  • Check the operations you have carried out and remittances (report option) in the Operations report.