Introduction

Who does this document target?

This document is intended for the merchants who want to integrate the WL Sips solution in a quick, simple way. It explains how you can start accepting payments with the connector Sips Paypage POST without payment pages customisation.

The options described in this guide are the most commonly used.

This guide explains how to accept payments:

  • in euros,
  • with the Visa, Vpay, Electron, Mastercard, Maestro, PayPal and Paylib means of payment ,
  • Secured by 3-D Secure.

You use Sips Office Extranet for cash management and receive the reports daily via e-mail.

This document is valid for the version 2.18 and later of the connector.

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.

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

WL Sips in a nutshell

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

You remain free to choose your banking institution as well as the accepted means of payment.

WL Sips sends activity reports via e-mail on a daily basis:

  • the transaction report, which lists all accepted or rejected transactions.
  • the operations report, which lists the cash management operations carried out by the merchant.
  • the reconciliation report, which provides a financial views of the payments credited to your accounts.
  • the chargebacks report, which reconciles the nonpayments of the banking institution (e.g. cardholder challenge) with the transactions that you accepted.

WL Sips provides the Sips Paypage interface for connecting your website to the payment platform.

Sips Paypage works as a direct payment interface with the customer through a Web browser or a mobile device. Therefore, Sips Paypage provides you with ready-to-use secure payment pages that customers can access.

Sips Paypage is complemented by a cash management web interface, Sips Office Extranet , which enables you to create and manage your transactions (validation, cancellation, refund, etc.).

How Sips Paypage works

Reference Name Frequency Description
a1 Sips Paypage payment request 24 hours a day Payment request sent by you to the WL Sips server
a2 Automatic response 24 hours a day Response sent by the WL Sips server to you once the payment has been made. This response is sent automatically regardless of what the customer does.
a3 Manual response 24 hours a day Response sent by the WL Sips server to you when the customer clicks on “Continue”. The transmission of this response depends on the customer’s action.
d1 Cardholder authentication 24 hours a day Request sent to the 3-D Secure authentication server of the cardholder’s bank
e1 Authorisation request 24 hours a day Authorisation request sent to your banking institution
e2 Payment remittance Once a day Payment remittance from WL Sips to the banking institution in order to credit your account
e3 Payment feedback 24 hours a day Banking institution’s feedback on the processing of payment acquiring operations
b Cash management 24 hours a day Cash management operation sent by you to the WL Sips server
c Reports Once a day Reports sent via e-mail

CB, VISA and MASTERCARD transaction process

The customer path consists of the following steps:

  • validation of the basket on your merchant page,
  • redirection of the customer to the WL Sips page for selecting the mean of payment,
  • card data entry,
  • customer authentication on a page of their bank (in the case of a 3-D Secure payment),
  • display of the sales receipt by WL Sips ,
  • acknowledgement of the placed order on your merchant page.

In this process the card data entry is handled by WL Sips , and you are not aware of these sensitive data.

PayPal transactions process

The customer path consists of the following steps:

  • validation of the basket on your merchant page,
  • redirection of the customer to the WL Sips page for selecting the mean of payment,
  • card data entry,
  • customer authentication on a PayPal page and means of payment validation,
  • display of the sales receipt by WL Sips ,
  • acknowledgement of the placed order on your merchant page.

Paylib transactions process

The customer path consists of the following steps:

  • validation of the basket on your merchant page,
  • redirection of the customer to the WL Sips page for selecting the mean of payment,
  • customer authentication on a Paylib page,
  • means of payment choice and validation on a Paylib page,
  • display of the sales receipt by WL Sips ,
  • acknowledgement of the placed order on your merchant page.

The customer can also make a mobile payment using the Paylib mobile application or the merchant’s mobile application. The customer path will be the same.

Transactions identification

The transactionReference field identifies the transactions of your store in a unique way.

WL Sips calculates or not this identifier during the creation of the transaction. The ( transactionReference , merchantId ) combination identifies the transaction in a unique way throughout the life of your store.

5 steps to getting started with Sips Paypage POST

To accept payments via WL Sips you must have signed the following documents beforehand:

  • A distance selling e-commerce/mail order contract with your bank
  • A acceptance contract with the reseller of the WL Sips solution.

Subscription to the 3-D Secure service of Visa and MasterCard, which secures Internet payments, is a mandatory clause of the distance selling contract with your bank.

To be able to accept PayPal payments, you must also have signed a contract with PayPal. Your PayPal merchant account must also be configured to authorise the call to WL Sips (see the “Configuration of the PayPal account” appendix).

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 - Connecting your site to Sips Paypage

To connect your merchant site to the WL Sips payment server, you must integrate the Sips Paypage POST connector.

Therefore, you must set up the links called a1 (payment request), a2 and a3 (payment response) on this diagram:

Attention: although the automatic response is not mandatory, it is strongly recommended to implement it.

If the customer does not click on “Return to shop”, the manual response will not be sent, and no WL Sips response will confirm to you that the transaction has been processed.

Generating the payment request

The payment request is sent from a page of your website to the WL Sips server via a Web form with the POST method. This form must point to the URL of the WL Sips payment server and contain the following fields:

Form data Presence Description
Data Mandatory Fields of the payment request (which are described below in the section entitled “Building the payment request: Data field”)
InterfaceVersion Mandatory The interface version describes the version of the request and the response exchanged with the payment server. The fields described below correspond to interfaceVersion HP_ 2.32 . If you use an earlier version of the connector, some fields might be unavailable and therefore unusable.
Seal Mandatory Signature of the Data field that guarantees the security of the payment request.
Encode Optional If the Data field contains special characters, you must change the encoding. The value of the Encode field specifies the encoding method used for the Data field. If encoding is used, the seal is calculated for the encoded Data field.

Value:

  • Base64 : Base 64 encoding for the Data field
  • Base64URL: Base64URL encoding for the Data field
SealAlgorithm Optional Algorithm for calculating the hash of the Data field

Value:

  • HMAC-SHA-256: The HMAC-SHA-256 algorithm is used.
  • HMAC-SHA-512: The HMAC-SHA-512 algorithm is used.
  • SHA-256: The SHA-256 algorithm is used.
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”.

Building the payment request: Data field

The Data field consists of several fields and contains all the data pertaining to the transaction.

It is supplied as a character string that complies with the following syntax :

      <nomChamp1>=<valeurChamp1>|<nomChamp2>=<valeurChamp2>|… |<nomChampN>=<valeurChampN>
    

The Data field must consist of the following fields :

  • Mandatory fields
Fields Format Description
amount N12 Transaction amount. This amount must be sent in the smallest unit of the currency. Example for euros: an amount of 10.50 euros must be sent as 1050.
currencyCode N3 (restricted values / ISO4217) Transaction currency code. This code is compatible with the ISO-IS 4217 standard. Example: the code for Euro is 978.
keyVersion N10 Version of the merchant secret key used to compute the seal of the message. E.g. KeyVersion=1 for the first key generated during the registration of the store.
merchantId N15 Store identifier supplied by WL Sips to the merchant when the latter registers their store.
normalReturnUrl ANS512 (URL) URL of the merchant used to return to the store if the transaction is accepted. E.g: https://www.monsite.fr/RetourPaiement
automaticResponseUrl ANS512 (URL) URL supplied by the merchant and used by the payment server to notify the merchant of the transaction result online and automatically (automatic response).

NB : although this field is not mandatory, it is strongly recommended to implement it so you can receive the payment response even if the customer does not click on “Continue”.

  • Main optional business fields that makes communication easier between your information system and the WL Sips payment server.
Fields Format Description
customerId ANS19 (restrictedString) Customer ID
customerEmail ANS128 (email) Customer's e-mail address
orderId ANS32 Order number associated with the payment transaction.
returnContext ANSU255 (extendedString) Order context sent in the payment request and reproduced without any change in the response and in the transaction report. You can store in it all the information that will make the response easier to process.
  • CB, Visa, Mastecard, Vpay, Electron, Maestro and Paylib fields: No specific fields.
  • PayPal fields (fields available since version HP_2.18).
Fields Format Description
addrOverride ANS20 (restricted values) This indicator enables you to:
  • display the delivery address on PayPal pages,
  • know whether the address to display is the one that you provide or the address stored by PayPal,
  • determine whether you can modify the address stored by PayPal.

Value:

  • NO_OVERRIDE : PayPal displays the address that the customer saved in their PayPal account.
  • OVERRIDE : PayPal displays the address given by the merchant. The address saved by the merchant in their PayPal account is deleted.
  • NO_DISPLAY (Default value): No address is displayed. PayPal disregards the address sent by the merchant.
invoiceId AN127 Order number. It is equivalent to the orderId but must be unique at PayPal. It is mandatory for PayPal to be used.
landingPage AN5 (restricted values) Indicator that enables you to hide the subscription form on PayPal pages.

Value:

  • true: The device used is a mobile device.
  • false: The subscription page is not displayed, PayPal displays the login page directly.
mobile AN5 (restricted values) Indicator that enables you to specify if the terminal used by the customer is the mobile.

Value:

  • true: The device used is a mobile device.
  • false: The device used is not a mobile device.
orderDescription ANS127 Order description
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.
Signing the hash of the payment request

The request is secured through the calculation of the hashed value in accordance with the transaction settings ( Data field). The secret key is then added to it. All character strings are converted to UTF-8 before the hashing operation.

The hashing algorithm produces an irreversible result that must be sent in hexadecimal form in the POST field named Seal.

When the recipient receives the message, they must recalculate the hashed value and compare it to the value received. Any discrepancy indicates that the exchanged data have been tampered with.

2 methods can be used to sign the hash of the Data field:

For the HMAC-SHA256 algorithm :

  • Only the Data field is used (encoded if the relevant option has been selected).
  • The secret key is used to generate the HMAC variant of the message.
  • The data resulting from previous operation are encoded in UTF-8.
  • The bytes obtained are hashed using the HMAC-SHA256 algorithm.
Table 1. Summary
HMAC-SHA256( UTF-8(Data), UTF-8(secreteKey))

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

  • The Data field (encoded if this option has been selected) and the secret key are concatenated.
  • The data resulting from the previous operation are encoded in UTF-8.
  • The bytes obtained are hashed using the SHA256 algorithm.
Table 2. Summary
SHA256( UTF-8(Data+secretKey))
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();
            }
    
        }
    }
          
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();
        }

    }
}
    

Sending the request to WL Sips

The payment request is a HTTPS POST request sent to Sips Paypage POST .

Example of a request in the web form (Data field not encoded. The sealAlgotrihm and encode optional fields are not filled in).

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

Error processing

Here is a list of the errors that you might encounter and relevant messages for each. If the error persists, contact the support team.

Status Example of an error message Action to perform
MerchantId does not exist Merchant ID (merchantId) not found: findMerchantPoi [220555555550002] is not found [5c62b84e3ae83d] Compare the merchantId used with the one returned by WL Sips after the registration.
Incorrect hashing algorithm Invalid field value: Invalid sealAlgorithm value (SHA-257) [609eac90a8ee1e]] Check the seal algorithm used.
Secret key error Invalid signature: rge7gesgd86g556dgv4r89g4d6 [609aec21985569] The signature that WL Sips calculated upon receiving the request is not identical to the signature that you sent.
  • During the simulation tests, compare the value of the key used with the one provided later in this document (see Step 4).
  • On the production server, compare the key used with the one that you retrieved from Sips Download .
Invalid key version Invalid field value : Unable to find a valid key for the following keyVersion=0 [609aec2b60b1d0] WL Sips does not find the key version that you have specified ( keyVersion field).
  • During the simulation tests, compare the version of the key used with the one provided later in this document (see Step 3).
  • On the production server, compare the version of the key used with the one that you retrieved from Sips Download .
Invalid Encode field Invalid keyword : ENCODE [609aecdee11d52] Make sure that the encoding algorithm that you use is correctly specified in the encode field.
Incorrect return URL Technical problem : code=30 message=normalReturnUrl is invalid https:// [609aec31b00b94] Check the syntax of the URL that you specify in the normaReturnUrl field.
Note: the 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; e.g. “Error while processing the payment request. Contact the merchant.”

Processing the payment response

When the payment is over:

  • WL Sips displays the sales receipt.
  • An automatic response is sent to the URL contained in the autoResponseUrl field of the request (this is optional but strongly recommended).
  • WL Sips invites the customer to return to your site thanks to the URL specified in the normalReturnUrl field of the request.

WL Sips returns these four fields in responses (automatic and manual):

Fields Description
Data Contains the response fields. Complies with the same syntax as the Data field of the payment request.
Encode Type of encoding used. If the value is base64 or base64url, the Data field must be decoded using Base64/Base64Url to find the string of concatenated fields.
Seal Signature of the Data field that guarantees the security of the payment response.
InterfaceVersion Value and version number of the interface used.

Checking the security of the response

First, you must check the security of the returned message by recalculating the Seal using the same method as the one used for the request. Then, compare the calculated Seal field with the one in the WL Sips response.

If they are identical, process the payment response contained in the Data field.

Otherwise, you must stop processing: check the secret key and the algorithm used, and contact the technical support team if need be.

Analysing the payment response

The payment request contained in the Data field consists of:

  • Generic fields
Fields Format Description
amount N12 Transaction amount. The amount is sent in the smallest unit of the currency. Example for euros: an amount of 10.50 euros must be sent as 1050.
currencyCode N3 (restricted value / ISO4217) Transaction currency code. This code is compatible with the ISO-IS 4217 standard.
customerId AN19 (restrictedString) Customer ID
customerEmail ANS128 (email) Contact's e-mail address
transactionReference AN35 Transaction identifier unique to each merchant
guaranteeIndicator A1 (restricted values) Transaction guarantee level (see values in the table below).
orderId ANS32 Order number associated with the payment transaction.
responseCode N2 (restricted values) Response code returned by the WL Sips server (see values in the table below).
acquirerResponseCode AN2 (restricted values) Code returned by the acquirer during an authorisation request (see values in the table below).
authorisationId AN10/ANS32 Authorisation identifier returned by the authorisation server of the customer bank if the transaction is approved (Not specified if the transaction is refused).
maskedPAN ANS19 Masked PAN number
panExpiryDate N6 (YYYYMM) PAN expiry date
paymentMeanBrand ANS20 (restricted values) Name of the means of payment used by the customer. Values:
  • CB
  • VISA
  • MASTERCARD
  • ELECTRON
  • VPAY
  • MAESTRO
  • PAYPAL
returnContext ANSU255 (extendedString) Order context sent in the payment request and reproduced without any change in the response and in the transaction report.
  • Fields for card payments
Fields Format Description
holderAuthenStatus ANS20 (restricted values) Result of the cardholder authentication process (see values in the table below).
cardProductCode AN5 Card product code
cardProductName ANS70 Card product wording
issuerCode AN6 Card issuer code
issuerCountryCode A3 (restricted values) Card issuer country code
  • Fields for PayPal payments

    No specific fields
  • Values of the fields to analyse

The responseCode field indicates the acceptance result.

If the value the field responseCode is 00, the payment is accepted.

If the payment is refused ( responseCode is different from 00), the acquirerReponseCode field specifies the nature of the bank’s refusal (for a card payment) or the PayPal server’s refusal (for a PayPal payment).

responseCode Description Refusal type
00 Transaction accepted
05 Transaction refused Banking
34 Suspected fraud (erroneous seal) Fraud
75 Maximum number of attempts reached Means of payment
90 Service temporarily unavailable Technical
97 Session expired (no action from the user during 15 min), transaction refused. Technical
99 Temporary problem with the WL Sips server Technical
holderAuthentStatus Description 3-D value
ATTEMPT The customer did not have to authenticate themselves. D_ATTEMPT
CANCEL The customer cancelled the authentication process. 3D_ABORT
ERROR Technical problem during the 3-D Secure authentication 3D_ERROR
FAILURE The customer could not authenticate themselves (password error). 3D_FAILURE
NOT_ENROLLED The card used is not enrolled in the 3-D Secure program. 3D_NOTENROLLED
NOT_PARTICIPATING The customer did not authenticate himself because:
  • the type of card is not supported by the 3-D Secure.
  • you are not enrolled in the 3-D Secure programme.
SSL
SUCCESS Cardholder authentication successful 3D_SUCCESS
guaranteeIndicator Description
Y Guaranteed 3-D payment
N Non-guaranteed 3-D payment
U Undefined 3-D guarantee
Non-3-D payment
acquirerResponseCode Description Matching with responseCode
00 Transaction approved or processed successfully 00
02 Contact the issuer of the means of payment 02
03 Invalid receiver 03
04 Keep the medium of the means of payment. 05
05 Do not honour 05
07 Keep the medium of the means of payment, special conditions 05
08 Honour with ID 05
12 Invalid transaction 12
13 Invalid amount 05
14 Invalid means of payment details 14
15 Unknown issuer 05
17 Customer cancellation 17
24 Operation impossible 05
25 Unknown transaction 05
30 Format error 30
31 Id of unknown acquisition organization 05
33 Expired means of payment 05
34 Suspected fraud 34
40 Function not supported 05
41 Lost card 05
43 Stolen card 34
51 Insufficient funds 05
54 Expired card 05
56 No card record 05
57 Transaction not permitted to cardholder 05
58 Transaction not permitted to terminal 05
59 Suspected fraud 05
60 The mean of payment receiver has to contact the acquirer. 05
61 Exceeds withdrawal limit 05
62 Transaction with pending payment confirmation 05
63 Security violation 05
65 Exceeds withdrawal limit 05
68 Response not received or received too late 05
75 Number of attempts to enter the details of the means of payment exceeded 75
87 Unknown terminal 05
90 Momentary shutdown of the system 90
91 Issuer inoperative 90
92 The transaction does not contain sufficient information to be redirected to the duplicate Transaction authorisation agency. 90
94 Duplicate transaction 90
96 System malfunction 90
97 Timeout, transaction refused 90
98 Server unavailable 90
99 Technical incident 99
A1 Payment refused by the acquirer (3-D Secure data missing in the authorisation request). 05

Payment response processing

Status Response fields Action to perform
3-D Secure payment accepted

responseCode = 00

acquirerResponseCode = 00

garanteeIndicator = Y,N,U, empty

You can deliver the order according to the guarantee level of your choice ( guaranteeIndicator ).
3-D Secure decline

reponseCode = 05

holderAuthenStatus = FAILURE

Customer authentication failed. This is not necessarily due to fraud. You can suggest your customer to pay with another means of payment and generate a new request.
Banking decline responseCode = 05 Authorisation refused for a reason not related to fraud. You can suggest your customer to pay with another means of payment and generate 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-related decline responseCode = 34 Authorisation refused because of fraud Do not deliver the order.
Decline because of maximum number of attempts reached responseCode = 75 The customer has made several attempts, all of which failed because the information entered was incorrect. There are two possibilities:
  • difficulty for the customer to enter the card information.
  • carding attempt (i.e. search for possible card numbers).
Contact your customer to discuss what should be done next.
Decline because of a technical issue

responseCode = 90, 99

acquirerResponseCode = 90 à 98

Temporary technical issue while processing the transaction. Suggest your customer to make another payment later.

Step 3 - Testing the connection to Sips Paypage

When the connection to Sips Paypage has been developed, you can perform a test on the Sips Paypage simulation server.

You will need the following data:

Simulation server: https://payment-webinit.simu.sips-atos.com/paymentInit

Merchant identifier (merchantId) : 002001000000002

Key version (keyVersion) : 1

Secret key (secretKey) : 002001000000002_KEY1

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

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

Therefore, it is not necessary to use real cards to do the tests.

Testing CB, Visa and Mastercard transactions

  • The card number (PAN) must consist of 16 to 19 digits.
  • The first six digits of the PAN determine the type of card in accordance with this table:

    Card type Card number beginning
    VPAY 400000
    VISA 410000
    CB 420000
    CB and VISA co-branded cards 430000
    CB and VPAY co-branded cards 440000
    CB and VISA_ELECTRON co-branded cards 450000
    VISA and MASTERCARD co-branded cards 460000
    MAESTRO 500000
    MASTERCARD 510000
    CB and MASTERCARD co-branded cards 520000
    CB and MAESTRO co-branded cards 530000
  • The WL Sips response code ( responseCode field) is calculated from the last two digits of the card number.
  • The security code (CVV) consists of 3 or 4 digits. This value does not matter for the result of the simulation.

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

Note: If the calculated WL Sips response code is not specified, the transaction is accepted (respondeCode = 00).

The co-branded cards can be used with all the brands defined in the table.

All cards are 3-D Secure cards. You are redirected to the 3-D Secure simulation server on which you choose the 3-D Secure authentication result that you want.

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.

Testing Paylib transactions

Paylib transactions cannot be simulated.

Step 4 - Validating the connection to the production

Once the connection of your website to has been tested, you can validate the connection to the Sips Paypage POST production platform.

To do so, you must change the URL to connect to the WL Sips production server using the credentials received during the registration phase ( merchantId , secretKey and keyVersion ).

URL WL Sips : https://payment-webinit.sips-atos.com/paymentInit

merchantId: Store identifier received via e-mail

SecretKey: Secret key that your retrieve from the Sips Download extranet

KeyVersion: Secret key version retrieved from Sips Download (logically 1 for the first key)

Note: a common mistake is to forget one of these four parameters, which systematically results in an error.

We recommend you to isolate your website from the general public beforehand so customers cannot make transactions during this validation phase.

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.

Appendices

Creating your PayPal account

You must have a PayPal account in order to use the PayPal mean of payment on your website. It must be a Business account (the type of account is chosen when you register at http://www.paypal.com ).

If you have several active shops, we suggest you create a PayPal account for each one.

Setting your PayPal account

On your PayPal account, you as a merchant have to authorise the payment service provider (PSP) to call PayPal API.

Attention: the screenshots of the PayPal pages are provided here for information only. PayPal may edit their pages.

In your PayPal Business account, go to Preferences , My selling tool s , then API access :

Click on the Grant API permission link.

The Add new third-party grant window opens . In the text field, enter the WL Sips technical account dlfr-sipspaypal_api1.atosorigin.com and click on Search .

Select the following options:

  • use PayPal Option+ to process your payments
  • complete a refund for a specific transaction
  • authorise and collect your PayPal transactions

After that, click on the Add button.

Secret key

Secret key downloading

Log into Sips Download thanks to the credentials that were returned to you by WL Sips when your shop was registered:

Go to the "Keys management" tab:

You can now download your secret key:

Payment regulation

The WL Sips solution complies with the regulation in force defined by CB, Visa and Mastercard.

Payment security (PCI)

PCI DSS is an international security standard that aims to guarantee the confidentiality and integrity of cardholders data, thus protecting card and transaction data. You and payment service providers must comply with it at varying degrees according to the importance of their business. The WL Sips solution receives the PCI DSS certification since 2006.

When using Sips Paypage , you do not have access to cardholders data and you do not need to have the PCI DSS certification. Card data are managed by Worldline .

Brand selection during payment (MIF)

The WL Sips 2.0 solution is subjected to the MIF European regulation (European Official Journal 2015/751 L123 of 19/05/2015). One of its rules, “Brand selection”, requires that you allow holders of co-badged cards to choose the brand that they want to use at the time of payment, which has consequences on the payment page.

A co-branded card supports at least two brands. Most of the cards issued in France are co-badged with CB (CB/VISA, CB/MASTERCARD, CB/MAESTRO, etc.).

You must thus allow the customers who hold such cards to choose the brand to use. The screen below shows an example a CB + Visa co-badged card with CB as the default brand. The customer can change brands by clicking on the link at the bottom of the screen.

Note: brand selection is not available for non-co-badged cards.

For further information

If you want to implement other means of payment or options, please refer to the associated documents.

This non-exhaustive list presents additional documents that will help you implement more WL Sips features.

Manual Why read it?
Data dictionary This manual provides the definitions and the values of all the fields of connectors and logs.
Functional presentation This manual provides an overview of WL Sips functionalities and the available options which you can subscribe to.
Functionality Set-up guide This manual explains how to implement WL Sips functionalities.
Reports description This manual describes the content of the logs sent by WL Sips .
Sips Paypage customisation for e-shop This manual explains how to customise payment pages so their graphic charter is the same as that of your site.
OneClick This manual describes the OneClick solution, which enables your customers to pay with one click without having to enter their card data again.
Sips Message This manual explains how to implement the WL Sips message solution, which enables you to send e-mail or SMS payment notifications to your customers.
Sips Download This manual explains how to download the documentation and your secret key via the Sips Download extranet.
Sips Office Extranet This manual describes all the cash management operations that can be carried out using Sips Office Extranet .
Fraud risk management– GO-no-Go This manual explains the functioning, configuration and use of the Go-No-Go fraud prevention engine. It enables you to define the fraud-related acceptance rules that you want to implement during payments.
Sips Paypage POST This guide describes and explains how to implement all the options of the connector.
American Express integration This manual explains how to integrate American Express cards.