Sips Paypage POST - …€¦ · Web viewBasic knowledge of the standard ... These fields are designated with the word ... The payment request contains the transaction settings and

Sips Paypage POSTSips Payment Acceptance Solution

•••••• an atos company

Sips Paypage POST

Summary

Document history.................................................................................................31 Introduction...................................................................................................4

1.1 Who is this document for?..................................................................................41.2 Prerequisites.......................................................................................................41.3 Secret key management.....................................................................................41.4 Contacting the technical support department....................................................5

2 Understanding payment with Sips Paypage POST........................................63 Get started with Sips Paypage POST in 5 steps............................................8

3.1 Step 1: Registering your store............................................................................83.2 Step 2: Making a payment..................................................................................83.3 Step 3: Doing tests in the simulation environment...........................................403.4 Step 4: Validating the switch to production environment.................................423.5 Step 5: Release.................................................................................................42

Doc. No: 317.26.18R2.en© Worldline 2018

2 of 47

InitialsWorldline

Initials

Public

Sips Paypage POST

Document history

Date(yyyy/mm/dd)

Version Description

2018/01/1130 26

New interface version HP_2.20Add new fields

- subMerchantName- subMerchantContractNumber- basket in cofidis3x container

Add sealAlgorithm use for the payment initialization errors responseAdded a new field, holderContactEmail, in manual and automatic responses

2018/01/09 25 Remove fields version for payment initialization errors response

2017/11/14 24

New interface version HP_2.19Add new fields

- automaticErrorResponseInitPOST- manualErrorResponseInitPOST- blockAmountModification

Automatic and manual responses in case of error on payment initializationCorrection in test cards

2017/05/19 23 Full revision of document


3 of 47

InitialsWorldline

Initials

Public

Sips Paypage POST

1 Introduction

Sips is a secure, multichannel e-commerce payment solution that complies with the PCI DSS standard. Sips enables all merchants to accept and manage payment transactions while taking into the account the rules specific to merchants’ businesses (payment upon delivery, deferred payment, recurring payment, installment payment...).

This document explains how to implement the Sips Paypage POST solution until its release.

1.1 Who is this document for?

This document is intended for the merchants who want to subscribe to the Sips offering and use a connector based on HTTPS exchanges in POST mode between their websites and Sips Paypage POST payment servers.

It is an implementation guide intended for your technical team.

We recommend you to read the following documents to get an overview of the Sips solution: WLSIPS 003 Functional presentation WLSIPS 004 Feature implementation guide

1.2 Prerequisites

Basic knowledge of the standard web programming languages used today, such as Java, PHP or .Net, is necessary to develop the connection to Sips Paypage POST.

All the code samples contained in this document are provided as mere examples. To make the most of them, you must adapt them to your website.

1.3 Secret key managementDuring your registration, Worldline provides, via the Sips Download extranet, a secret key that makes it possible to secure exchanges between your site and the Sips Server.You are responsible for preserving this key and taking all the required measures to

restrict access to it, save it in an encrypted form, never copy it to a non-secure disk, never send it (e-mail, postal mail) in a non-secure way.

The compromise of the secret key and its use by a malevolent third party would disrupt the normal functioning of the store and could notably generate unjustified transactions and cash management operations (e.g. refunds). Therefore, if the secret key is compromised, you must request its revocation and then its renewal as fast as possible, using the Sips Download extranet.


4 of 47

InitialsWorldline

Initials

Public

Sips Paypage POST

The same secret key is used with the various Paypage, Office and Walletpage connectors.

1.4 Contacting the technical support department

For any technical question or request for support, you can contact our teams:

by telephone: +33 (0) 811 10 70 33, by email: [email protected]

You will be asked to give your merchant ID (15-digit number) so we can process your requests more easily.


5 of 47

InitialsWorldline

Initials

Public

Sips Paypage POST

2 Understanding payment with Sips Paypage POST

The general principle for a payment process is as follows:

Site commerçantConnecteur

Sips PaypagePOST

Moteur Sipset pages de paiement.

Le client saisit lescoordonnées de sa

carte; le paiement est effectué.

Le client procède au paiement

(finalisation de la commande)

Le connecteur redirige le client vers la page de

paiement

Site commerçant

Page de finalisation de la commande

Page de retour vers le site

Web

Site commerçant

Service de réponse

automatique

Le client revient à votre site Web (réponse manuelle)

Le moteur Sips envoie une réponse automatique vers

votre site Web

When the customer proceeds to payment, a payment request must be sent to the Sips Paypage POST connector. Worldline provides you with the URL for this connector. The request is then verified, and quantified if it is valid (it is called RedirectionData in the system). The request is sent using a form in POST mode via HTTPS. Any other solution capable of sending a request of this type will operate similarly.

Sips Paypage POST redirects the calling application to the Sips payment pages. The customer must enter the details for the payment method so that the Sips payment server can process the transaction. Please note that the details of the payment may be entered directly on the server offering the payment method (for example, in the case of PayPal or a SEPA instruction). At the end of the payment process, whether or not it is successful, two responses are created and sent to the URL address specified during workflow stage 1.

There are two independent response notifications:

The payment server sends the Manual responses in the 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 which the user is redirected to at the end of the payment. Nothing guarantees that the customer will click on


6 of 47

InitialsWorldline

Initials

Public

Sips Paypage POST

this link; therefore, the receipt of the manual response cannot be guaranteed either.

Automatic responses and manual responses are sent independently. Automatic responses also use the HTTP(S) POST requests sent by the Sips payment servers, but this time, they use the automatic response URL specified in the payment request. This means that you receive the response as soon as the payment is made on the Sips payment pages.

If the payment has failed and the customer is redirected to your website, it is no longer possible to return to the payment pages to attempt another payment or correct card data. Your website must initialize a new payment request by calling the Sips Paypage connector.


7 of 47

InitialsWorldline

Initials

Public

Sips Paypage POST

3 Get started with Sips Paypage POST in 5 steps

3.1 Step 1: Registering your store

To register your store so it can run in the production environment, you must fill in the registration form sent by Worldline and return it to the latter.

When filling in the form, you appoint an administrative contact and a technical contact so Worldline can send you the information that you need to launch your store.

Worldline then registers the store and e-mails you your Merchant ID, your Sips Download credentials (to retrieve the secret key), and your Sips Extranet credentials (for transaction management).

The Sips Extranet credentials are sent to the administrative contact. For Sips Download, the username is sent to the administrative contact and the password to the technical contact.

The store does not have to be registered for you to start integrating the connector and testing the connection to the simulation environment. You can submit your store registration request only at the time of doing the tests in the production environment.

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

3.2.1 Generating the payment requestThree 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 Sips

server.Seal Used to validate the integrity of the data exchanged. The Seal element is

calculated using the Data data element and the secret key.

The InterfaceVersion element should be set to HP_2.2019.

Additional optional data elements are available:

Data element Description


8 of 47

InitialsWorldline

Initials

Public

Sips Paypage POST

nameEncode Specifies the method used to encode the Data field elementSealAlgorithm Specifies the algorithm used to calculate the Seal field element

Data data element syntaxThe Data data element is constructed using the following format:

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

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

Example of a payment request for EUR 55:

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

It is possible to have a list of values for the same field:..|nomChamp=valeur1,valeur2, … ,valeurX|…

Example for the field paymentMeanBrandList with specified values for VISA and MASTERCARD:

…|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.nomChamp1=valeurChamp1|container.nomChamp2=valeurChamp2|……

Example for the field customerContact containing the email [email protected] [email protected] and the first name and surname Jean Dupont for the customer:

…|[email protected]|customerContact.firstname=Jean|customerContact.lastname=Dupont|…

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

..|<champ1>=<valeur1>|<nomObjet>.<nomItem={<nomChampA1>=<valeurChampA1>,<nomChampA2>=<valeurChampA2>},{<nomChampB1>=<valeurChampB1>,<nomChampB2>=<valeurChampB2>},{<nomChampC1>=<valeurChampC1>,<nomChampC2>=<valeurChampC2>}|<nomChamp2>=<valeurChamp2>|……


9 of 47

InitialsWorldline

Initials

mailto:[email protected]

mailto:[email protected]

Public

Sips Paypage POST

Example of a payment request with a list of complex objects for the field shoppingCartDetail containing three products called 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 elementIf the Data field element contains special characters (such as accented characters), then it should be encoded using base64 or base64Url

Because the signature is calculated using the Data field element, it is important to note that it is the encoded Data value which is used for the request signature

Request fields presenceSome fields of the payment request are only required:

When using certain payment means, please consult the payment means guide concerned to know which fields are required

Depending on the configuration of your store, please consult the feature configuration guide to find out which fields are required

In certain cases of use (e.g. recurring payment), please consult the configuration guide of the functionalities to know which fields are mandatory

These fields are designated with the word "conditional".

Request securityThe payment request contains the transaction settings and is sent through the customer’s Web browser. It is theoretically possible for a hacker to intercept the request and modify its content before the data reach the payment server.Therefore, security must be reinforced to ensure the integrity of the transaction settings sent. The Sips solution meets this need by means of a signature exchange.An effective signature check consists of two elements:

- the integrity of the request and the response. No alterations must have been made during the exchange.

- the authentication of the sender and recipient, since they share the same secret key.

If your secret key is compromised, or if you suppose it has been, it is imperative that you request its renewal by connecting to Sips Download.


10 of 47

InitialsWorldline

Initials

Public

Sips Paypage POST

How to make requests secureThe security of the request is based on the calculation of the value “hashed” in accordance with the transaction parameters (Data field element). Next, the secret key is added to it. All character strings are converted to UTF-8 before being hashed.

The hashing algorithm produces an irreversible result. When the recipient receives the message, they must recalculate the hashed value and compare it to the value received. Any difference indicates that the exchanged data have been falsified, or that the sender and the recipient do not share the same secret key.

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

Seal data calculationThe value of the Seal data is calculated 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 element 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 today):

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 the bytes obtained

This procedure can be summarised as follows:

SHA256( UTF-8(Data+secretKey ) )


11 of 47

InitialsWorldline

Initials

Public

Sips Paypage POST

Examples of code Hmac Sha256 encoding in Php5<?php…echo hash_hmac('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 function utf8_encode.

Example of Hmac Sha256 encoding in Javaimport 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);


12 of 47

InitialsWorldline

Initials

Public

Sips Paypage POST

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

}}

}

Example of Hmac Sha256 encoding in .netCompleted using a simple form called “Form 1” containing two text fields to be filled in: txtSips, txtSecretKey and another 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 = txtSips.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(); }


13 of 47

InitialsWorldline

Initials

Public

Sips Paypage POST

}}

Example of Sha256 encoding in Php 5<?phpecho 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 function utf8_encode.


14 of 47

InitialsWorldline

Initials

Public

Sips Paypage POST

Example of Sha256 encoding in Javaimport 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();

}}

}


15 of 47

InitialsWorldline

Initials

Public

Sips Paypage POST

Example of Sha256 encoding in .NETCompleted using a simple form called “Form 1” containing two text fields to be filled in: txtSips, txtSecretKey and another 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 = txtSips.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(); }

}}

Example of a payment requestBelow is an example of the 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.18"> <input type="hidden" name="Seal" value="21a57f2fe765e1ae4a8bf15d73fc1bf2a533f547f2343d12a499d9c0592044d4"> <input type="submit" value="Payer"> </form>


16 of 47

InitialsWorldline

Initials

Public

Sips Paypage POST

3.2.2 Payment initialization errors messagesAll fields received by Sips Paypage POST via the connector are subject to individual verification. The table below shows a list of error messages that may be displayed during this verification stage, as well as the solutions to be implemented.

The messages are displayed on the simulation platform to assist you in validating the integration of your website. For security reasons, simpler error messages are displayed on the live platform. E.g. “Error processing payment request. Please contact the merchant.”

Message Cause SolutionUnknown version interface: <version>

The <version> value in the InterfaceVersion field is not recognised

Check the interface version in this user guide (the current version is version HP_2.18)

Invalid keyword: <nomChamp>=<valeur Champ>

The <nomChamp> field is not shown in the payment request

Check the field names in the chapter below and in the data dictionary

Invalid field size: <nomChamp>=<valeur Champ>

The <nomChamp> field has an incorrect length

Check field length in the data dictionary

Invalid field value: <nomChamp >=<valeur Champ>

The <nomChamp> value is incorrect Check possible field values in the data dictionary

Mandatory field missing: <nomChamp>

The <nomChamp> field is missing in the payment request

Check the mandatory fields for the payment request in the chapter below

Unknown security version: <version>

The value <version> in the keyVersion field is not recognised

Check the versions of the available keys in Sips Download

Invalid signature Verification of the Seal for the payment request has failed. This can be caused by incorrect calculation of the Seal data element or may indicate falsification of certain fields after the signature has been calculated.

Check that the Seal calculation has been performed as indicated in the previous chapter. If that is the case, request a change to the secret key via Sips Download, because the request has been falsified

Transaction already processed: <référence de la transaction>

A payment request with the same transactionReference has already been received and handled by the Sips servers

Check if the transactionReference field value is unique to the transaction in question

<Autres messages> In the event of technical errors, various other messages may be displayed

Contact the technical support department

3.2.3 Payment initialization errors response processingAutomatic and manual responses in case of payment initialization errors can be activated through merchant Paypages settings.


17 of 47

InitialsWorldline

Initials

Public

Sips Paypage POST

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.

Payment responses are HTTP(S) POST responses sent to the manualErrorResponseInitPOST (optional) and automaticErrorResponseInitPOST (optional) URLs specified in the request.

You must set up the system that decodes these responses so you can know the result of the payment.

Field name Comments/Rules

Data Concatenation of fields in the responseSeal Signature of the response message

The concatenated string is structured as follows: redirectionStatusCode=value1| redirectionStatusMessage=value2This string is UTF-8 encoded before 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.The authenticator (Seal field) of both responses is hashed with the algorithm SHA-256.

Specifying the manual initialization error response URLThe main objective of the manual initialization error response is to redirect the customer to your website with the error cause, so you can make the right decision about it. For instance, in case of an error on data filled by the customer, you may suggest to retry with a correct format. In case of an error beyond the customer responsibility, you can invite him to contact you to solve the problem.

At the first step, a “Back” button is displayed on the Sips payment page, with a link that redirects the user to your site. When the Internet user clicks on this link, the 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 data of the response as described above.

It is the your responsibility to retrieve these settings 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 problems that block the transmission of this response. Therefore, your business processes cannot be based only on it.

Specifying the automatic initialization error response URL

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


18 of 47

InitialsWorldline

Initials

Public

Sips Paypage POST

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 Sips server and does not go through the customer’s Web browser. Therefore, it is much more reliable since it is always sent. The Sips server does not expect any response after the automatic response has been sent.

It is the 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 initialization error response receipt problemsAs automatic and manual payment responses, you can have troubles with the reception. To avoid them, common advises can help you (please see chapter [Solving response receipt problems]).

Retrieving initialization error response fieldsThe content of the automatic and manual initialization error responses sent by Sips Paypage is constant. This content can vary according to the error, the response will contain:

Field Comments

redirectionStatusCoderedirectionStatusMessage


19 of 47

InitialsWorldline

Initials

Public

Sips Paypage POST

3.2.4 Filling in request fields

Generic fields


20 of 47

InitialsWorldline

Initials

Public

Sips Paypage POST

Field name PresenceVersio

n Comments

amount Mandatory HP_1.0currencyCode Mandatory HP_1.0keyVersion Mandatory HP_1.0merchantId Mandatory HP_1.0normalReturnUrl Mandatory HP_1.0transactionReference Mandatory HP_1.0 Optional if using

S10TransactionReferences10TransactionReference Mandatory HP_2.2 Optional if using

transactionReference. See below

automaticResponseUrl Optional HP_1.0billingFirstDate Optional HP_2.5bypassDcc Optional HP_2.1

1captureDay Optional HP_1.0captureMode Optional HP_1.0customer3DSTransactionDate Optional HP_2.5customerBillingNb Optional HP_2.5customerDeliverySuccessFlag Optional HP_2.5customerId Optional HP_2.0customerIpAddress Optional HP_2.1customerLanguage Optional HP_1.0customerPhoneValidationMethod Optional HP_2.5customerRegistrationDateOnline Optional HP_2.5customerRegistrationDateProxi Optional HP_2.5deliveryFirstDate Optional HP_2.5evidenceAcquisitionDate Optional HP_2.5evidenceNumber Optional HP_2.5evidenceType Optional HP_2.5expirationDate Optional HP_1.0hashAlgorithm1 Optional HP_2.3hashAlgorithm2 Optional HP_2.3hashSalt1 Optional HP_2.1hashSalt2 Optional HP_2.1holderAdditionalReference Optional HP_2.9intermediateServiceProviderId Optional HP_2.1

2invoiceReference Optional HP_2.0mandateId Optional HP_2.5merchantSessionId Optional HP_2.0merchantTransactionDateTime Optional HP_2.0merchantWalletID Optional HP_2.2orderChannel Optional HP_2.1orderId Optional HP_1.0


21 of 47

InitialsWorldline

Initials

Public

Sips Paypage POST


n CommentspaymentMeanBrandList Optional HP_1.0paymentPattern Optiona

lConditionalHP_2.1 This field is mandatory for

certain payment methods. Please consult the guide for implementing the payment method in question for further detail.

returnContext Optional HP_2.0riskManagementCustomDataList Optional HP_2.9 A list of

riskManagementCustomData objects

statementReference Optional HP_2.3subMerchantCategoryCode Optional HP_2.1

5subMerchantId Optional HP_2.1

5subMerchantLegalId Optional HP_2.1

5subMerchantShortName Optional HP_2.1

5templateName Optional HP_2.1transactionActors Optional HP_2.2transactionOrigin Optional HP_2.0valueDate Optional HP_2.5automaticErrorResponseInitPOST Optional HP_2.1

9manualErrorResponseInitPOST Optional HP_2.1

9fraudData Optional HP_2.1 See belowriskManagementDynamicSetting. Optional HP_2.1

0See below

paypageData Optional HP_2.0 See belowauthenticationData Optional HP_2.2 See belowpaymentMeanData Optional HP_2.2 See belowinstalmentData Optional HP_2.2 See belowbillingAddress Optional HP_2.2 See belowbillingContact Optional HP_2.2 See belowcustomerAddress Optional HP_2.2 See belowcustomerContact Optional HP_2.2 See belowcustomerData Optional HP_2.2 See belowdeliveryAddress Optional HP_2.2 See belowdeliveryContact Optional HP_2.2 See belowdeliveryData Optional HP_2.2 See belowholderAddress Optional HP_2.2 See belowholderContact Optional HP_2.2 See belowshoppingCartDetail Optional HP_2.2 See below


22 of 47

InitialsWorldline

Initials

Public

Sips Paypage POST


n CommentsshoppingCartItem Optional HP_2.2 See belowriskManagementCustomData Optional HP_2.2 See belowsubMerchantAddress Optional HP_2.2 See beloworderContext Optional HP_2.2 See belowtravelContext Optional HP_2.2 See belowsubMerchantName Optional HP_2.2

0subMerchantContractNumber Optional HP_2.2

0Table 1 Generic payment request fields

Optional fields pertaining to fraud

Content of fraudData

FieldPresenc

eVersio

n CommentsallowedCardArea Optional HP_2.1allowedCardCountryList Optional HP_2.1allowedIpArea Optional HP_2.1allowedIpCountryList Optional HP_2.1bypass3DS Optional HP_2.1bypassCtrlList Optional HP_2.1bypassInfoList Optional HP_2.1deniedCardArea Optional HP_2.1deniedCardCountryList Optional HP_2.1deniedIpArea Optional HP_2.1deniedIpCountryList Optional HP_2.1riskManagementDynamicSettingList Optional HP_2.10 A list of

riskManagementDynamicSetting objects

Content of riskManagementDynamicSetting

Field Presence Version CommentsriskManagementDynamicParam Conditiona

lMandatory

HP_2.10

riskManagementDynamicValue ConditionalMandator

y

HP_2.10


23 of 47

InitialsWorldline

Initials

Public

Sips Paypage POST

Optional field pertaining to payment pages

Content of paypageData

Field Presence Version CommentsbypassReceiptPage Optional HP_2.0

Optional fields pertaining to cardholder authentication Content of authenticationData

Field Presence Version CommentsissuerWalletPolicy Optional HP_2.2 See belowcardAuthPolicy Optional HP_2.8 See below

Content of issuerWalletPolicy

Field Presence Version Commentscheck3DS Optional HP_2.2checkCSC Optional HP_2.2

Content of cardAuthPolicy

Field Presence Version CommentscheckAVS Optional HP_2.8ignoreAddressCheckResult Optional HP_2.8ignorePostcodeCheckResult Optional HP_2.8ignoreCSCCheckResult Optional HP_2.17

Optional fields pertaining to payment methods Content of paymentMeandData

Field Presence Version Commentspaypal Optional HP_2.2 See belowsdd Optional HP_2.2 See belowcofinoga3xcb Optional HP_2.2 See belowpassbe Optional HP_2.5 See belowaccord Optional HP_2.6 See belowfacilypay Optional HP_2.6 See belowcetelemNxcb Optional HP_2.9 See belowpresto Optional HP_2.10 See below


24 of 47

InitialsWorldline

Initials

Public

Sips Paypage POST

Field Presence Version Commentscofidis3x Optional HP_2.11 See belowcofidis4x Optional HP_2.12 See belowunEuroCom Optional HP_2.11 See belowcofinoga Optional HP_2.15 See belowcetelem3x Optional HP_2.16 See belowcetelem4x Optional HP_2.16 See belowfranfinance3xcb Optional HP_2.18 See belowfranfinance4xcb Optional HP_2.18 See belowAccordkdo Optional HP_2.18 See below

Content of paypal

Field Presence Version CommentsaddrOverride Optional HP_2.2dupCustom Optional HP_2.2dupDesc Optional HP_2.2dupFlag Optional HP_2.2dupType Optional HP_2.2invoiceId Optional HP_2.2landingPage Optional HP_2.2mobile Optional HP_2.2orderDescription Optional HP_2.16

Content of sdd

Field Presence Version CommentsmandateAuthentMethod Optional HP_2.2mandateCertificationType Optional HP_2.5mandateUsage Optional HP_2.2

Content of cofinoga3xcb

Field Presence Version CommentscreditIndicator Optional HP_2.4

Content of passBe

Field Presence Version CommentssettlementModeList Optional HP_2.5

Content of accord

Field Presence Version CommentssettlementMode Optional HP_2.6


25 of 47

InitialsWorldline

Initials

Public

Sips Paypage POST

Content of facilypay

Field Presence Version CommentsdepositRefundIndicator Optional HP_2.6receiverType Optional HP_2.6settlementMode Optional HP_2.6settlementModeVersion Optional HP_2.6

Content of cetelemNxcb

Field Presence Version CommentsnxcbTransactionReference1 Optional HP_2.9nxcbTransactionReference2 Optional HP_2.9s10NxcbTransactionId1 Optional HP_2.9s10NxcbTransactionId2 Optional HP_2.9

Content of presto

Field Presence Version CommentsfinancialProduct Conditiona

lMandatoryHP_2.10

paymentMeanCustomerId ConditionalMandatory

HP_2.10

prestoCardType Optional HP_2.10

Content of cofidis3x

Field Presence Version Commentsbasket Optional HP_2.20preScoreValue Optional HP_2.11cofidisDisplayCancelButton Optional HP_2.11cofidisPrivateData Optional HP_2.11basket Optional HP_2.20preScoreValue Optional HP_2.11

Content of cofidis4x

Field Presence Version CommentspreScoreValue Optional HP_2.12cofidisDisplayCancelButton Optional HP_2.12cofidisPrivateData Optional HP_2.12preScoreValue Optional HP_2.12

Content of unEuroCom


26 of 47

InitialsWorldline

Initials

Public

Sips Paypage POST

Field Presence Version CommentspreScoreValue Optional HP_2.11cofidisPrivateData Optional HP_2.11preScoreValue Optional HP_2.11

Content of cofinoga

Field Presence Version Comments

paymentMeanTradeOptionList Optional HP_2.15 A list of paymentMeanTradeOption

objects

Content of paymentMeanTradeOption

Field Presence Version CommentspaymentMeanTradingName Optional HP_2.15settlementModeList Optional HP_2.15

Content of cetelem3x

Field Presence Version CommentscetelemPrivateMerchantData Optional HP_2.16cetelemPrivateData Optional HP_2.16

Content of cetelem4x

Field Presence Version CommentscetelemPrivateMerchantData Optional HP_2.16cetelemPrivateData Optional HP_2.16

Content of franfinance3xcb

Field Presence Version CommentsauthenticationKey Conditiona

lMandatoryHP_2.18 Mandatory only for a

franfinance transactionpageCustomizationCode Optional HP_2.18redirectionTimer Optional HP_2.18testEnvironment Optional HP_2.18birthPlaceCode Optional HP_2.18

Content of franfinance4xcb


27 of 47

InitialsWorldline

Initials

Public

Sips Paypage POST

Field Presence Version CommentsauthenticationKey Conditiona

lMandatoryHP_2.18 Mandatory only for a

franfinance transactionpageCustomizationCode Optional HP_2.18redirectionTimer Optional HP_2.18testEnvironment Optional HP_2.18birthPlaceCode Optional HP_2.18

Content of accordkdo

Field Presence Version CommentsblockAmountModification Optional HP_2.18

Optional fields pertaining to payment by instalment

Content of instalmentData

Field Presence Version Commentsnumber Optional HP_2.2datesList Optional HP_2.2

transactionReferencesListOptiona

lConditionalMandatory

HP_2.2 Optional if you use s10transactionIdsList

s10TransactionIdsListOptiona

lConditionalMandatory

HP_2.7 Optional if you use transactionReferencesList

amountsList Optional HP_2.2

Optional fields pertaining to the customer billing address

Content of billingAddress

Field Presence Version CommentsaddressAdditional1 Optional HP_2.2addressAdditional2 Optional HP_2.2addressAdditional3 Optional HP_2.2city Optional HP_2.2company Optional HP_2.2country Optional HP_2.2postBox Optional HP_2.2state Optional HP_2.2street Optional HP_2.2streetNumber Optional HP_2.2


28 of 47

InitialsWorldline

Initials

Public

Sips Paypage POST

Field Presence Version CommentszipCode Optional HP_2.2

Content of billingContact

Field Presence Version Commentsemail Optional HP_2.2firstname Optional HP_2.2gender Optional HP_2.2lastname Optional HP_2.2mobile Optional HP_2.2phone Optional HP_2.2title Optional HP_2.2

Optional fields pertaining to the customer address

Content of customerAddress

Field Presence Version CommentsaddressAdditional1 Optional HP_2.2addressAdditional2 Optional HP_2.2addressAdditional3 Optional HP_2.2city Optional HP_2.2company Optional HP_2.2country Optional HP_2.2postBox Optional HP_2.2state Optional HP_2.2street Optional HP_2.2streetNumber Optional HP_2.2zipCode Optional HP_2.2businessName Optional HP_2.17

Content of customerContact

Field Presence Version Commentsemail Optional HP_2.2firstname Optional HP_2.2gender Optional HP_2.2lastname Optional HP_2.2mobile Optional HP_2.2phone Optional HP_2.2title Optional HP_2.2legalId Optional HP_2.17positionOccupied Optional HP_2.17

Content of customerData


29 of 47

InitialsWorldline

Initials

Public

Sips Paypage POST

Field Presence Version CommentsbirthCity Optional HP_2.2birthCountry Optional HP_2.2birthDate Optional HP_2.2birthZipCode Optional HP_2.2nationalityCountry Optional HP_2.2newPwd Optional HP_2.2pwd Optional HP_2.2

Optional fields pertaining to the customer delivery address Content of deliveryAddress

Field Presence Version CommentsaddressAdditional1 Optional HP_2.2addressAdditional2 Optional HP_2.2addressAdditional3 Optional HP_2.2city Optional HP_2.2company Optional HP_2.2country Optional HP_2.2postBox Optional HP_2.2state Optional HP_2.2street Optional HP_2.2streetNumber Optional HP_2.2zipCode Optional HP_2.2

Content of deliveryContact

Field Presence Version Commentsemail Optional HP_2.2firstname Optional HP_2.2gender Optional HP_2.2lastname Optional HP_2.2mobile Optional HP_2.2phone Optional HP_2.2Title Optional HP_2.2

Content of deliveryData


30 of 47

InitialsWorldline

Initials

Public

Sips Paypage POST

Field Presence Version CommentsdeliveryChargeAmount Optional HP_2.6deliveryMethod Optional HP_2.6deliveryMode Optional HP_2.6deliveryOperator Optional HP_2.6estimatedDeliveryDate Optional HP_2.6estimatedDeliveryDelay Optional HP_2.7

Optional fields pertaining to cardholder data Content of holderAddress


Content of holderContact

Field Presence Version Commentsemail Optional HP_2.2firstname Optional HP_2.2gender Optional HP_2.2lastname Optional HP_2.2mobile Optional HP_2.2phone Optional HP_2.2title Optional HP_2.2

Content of holderData


birthDate Optional HP_2.6


31 of 47

InitialsWorldline

Initials

Public

Sips Paypage POST

Optional fields pertaining to shopping cart

Content of shoppingCartDetail


mainProduct Optional HP_2.6shoppingCartTotalAmount Optional HP_2.6shoppingCartTotalQuantity Optional HP_2.6shoppingCartTotalTaxAmount Optional HP_2.7shoppingCartItemList Optional HP_2.6 shoppingCartItem list

Content of shoppingCartItem

Field Presence Version CommentsproductCategory Optional HP_2.6productCode Optional HP_2.6productDescription Optional HP_2.6productName Optional HP_2.6productQuantity Optional HP_2.6productSKU Optional HP_2.6productTaxCategory Optional HP_2.11productTaxRate Optional HP_2.6productUnitAmount Optional HP_2.6productUnitTaxAmount Optional HP_2.6

Optional fields pertaining to the Sips 1.0 transactionId

Content of s10TransactionReference


s10TransactionId Optional HP_2.7s10TransactionIdDate Optional HP_2.7


32 of 47

InitialsWorldline

Initials

Public

Sips Paypage POST

Optional fields pertaining to risk management

Content of riskManagementCustomData


riskManagementCustomSequence Optional HP_2.9riskManagementCustomValue Optional HP_2.9

Optional fields pertaining to seller data (for marketplaces)

Content of subMerchantAddress


Table 2: Fields provided for element subMerchantAddress

Optional fields pertaining to AMEX-EA

Content of orderContext

Field Presence Version CommentscustomerHostName Optional HP_2.16customerBrowserType Optional HP_2.16customerANI Optional HP_2.16customerANIInformationIdentifier Optional HP_2.16


33 of 47

InitialsWorldline

Initials

Public

Sips Paypage POST

Content of travelContext

Field Presence Version CommentsdepartureDate Optional HP_2.16passengerName Optional HP_2.16originAirport Optional HP_2.16numberOfRoutingCities Optional HP_2.16routingCityList Optional HP_2.16numberOfAirlineCarriers Optional HP_2.16airlineCarrierList Optional HP_2.16fareBasis Optional HP_2.16numberOfPassengers Optional HP_2.16destinationAirport Optional HP_2.16reservationCode Optional HP_2.16

3.2.5 Configuring the payment requestThis is an example of the payment request configuration for each feature available in Sips Paypage POST (details of these features are provided in the features guide).

Dynamic display of payment methods

The paymentMeanBrandList field must be used to filter the means of payment that will be displayed on the page used to select means of payment:

..|paymentMeanBrandList=VISA,PAYPAL|..

Display of the receipt by SipsThe payment confirmation page that 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|..

Payment at the end of the day

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

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


34 of 47

InitialsWorldline

Initials

Public

Sips Paypage POST

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 this example):

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

Payment upon dispatch of the goodsFor payment upon dispatch of the goods, the transaction is captured during your validation. You must simply fill the captureMode and captureDay fields (in this example, a period of up to 3 days before the validation is set):

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

Instalments paymentFor payments whose installments are associated with the same transaction, the value of the paymentPattern field must be set to INSTALMENT, and the breakdown of installments must be supplied in the instalmentData field (in this example, €600 paid in 3 installments):

…|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 (which is only available with certain means of payment), the transaction is paid for during the online authorization:

…|captureMode=IMMEDIATE|..

Multicurrency acceptanceFor 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 currenciesAcceptance 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.


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


35 of 47

InitialsWorldline

Initials

Public

Sips Paypage POST


Disabling 3D Secure dynamically3D Secure authentication can be deactivated dynamically using the fraudData.bypass3DS field:

…|fraudData.bypass3DS=ALL|..

Disabling 3D Secure for Oneclick payments 3D Secure authentication 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 specified 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|..

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

Payment 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 decodes these responses so you can know the result of the payment.

Field name Comments/Rules

Data Concatenation of fields in the responseEncode Type of encoding used to encode the Data fieldSeal Signature of the response messageInterfaceVersion Version of the connector interface.


36 of 47

InitialsWorldline

Initials

Public

Sips Paypage POST

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…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 manual response URLThe main objective of the manual response is to redirect the customer 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 dispatching the goods.

At the last step, a “Continue” button is displayed on the Sips payment page, with a link that redirects the user to your site. When the Internet user clicks on this link, the 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 the Merchant's responsibility to retrieve these settings 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).

This field normalReturnUrl is also used for all case of payment result (cancellation, refusal…) to redirect 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. Second, they might encounter connection problems that block the transmission of this response. Therefore, your business processes cannot be based only on it.

The current version of InterfaceVersion is HP_2.2019. Please refer to the Sips data dictionary for a comprehensive description of the settings included in the response.

Specifying the automatic response URL

The automatic response is sent only if the automaticResponseUrl was sent in the payment request. If that is the case, the 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 SIPS server and does not go through the customer’s Web browser. Therefore, it is much more reliable since it is always sent. The 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


37 of 47

InitialsWorldline

Initials

Public

Sips Paypage POST

tampered with, and - update your back office.

The current version of InterfaceVersion is HP_2.2019. Please refer to the Sips data dictionary for a comprehensive description of the settings included in the response.

Solving response receipt problemsBelow is a list of the commonest issues that block the receipt of automatic and manual responses. Make sure you have checked them before you call the technical support department.

Make sure the response URLs are provided in the payment request and are valid. To do so, simply copy and paste them into your browser’s address bar.

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 make your server impossible to access.

Access to response URLs must be confirmed in your Web server’s event log. If you use a non-standard port, it must be within the 80 to 9999 range to be compatible

with Sips. Context parameters cannot be added to the response URLs. Nevertheless, some fields can

still be used e.g. orderId or returnContext 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 certain error cases, the Sips server is unable to sign the response message. This applies, for instance, to the “Unknown merchantID” error and to the situation where Sips does not know the secret key. For these particular reasons, the payment server will send a response without a signature in the Seal field.

Retrieving response fieldsThe 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).

Field Version CommentsacceptanceSystemApplicationId* HP_2.18acquirerNativeResponseCode* HP_2.12acquirerResponseCode* HP_2.0acquirerResponseIdentifier* HP_2.8acquirerResponseMessage* HP_2.8additionalAuthorisationNumber* HP_2.8amount HP_1.0 same request as aboveauthorisationId* HP_1.0authorisationTypeLabel* HP_2.18authorMessageReference* HP_2.18avsAddressResponseCode* HP_2.17


38 of 47

InitialsWorldline

Initials

Public

Sips Paypage POST

Field Version CommentsavsPostcodeResponseCode* HP_2.17captureDay HP_1.0 Request field that can be overwritten by

SipscaptureLimiteDate* HP_2.3

captureMode HP_1.0 Request field that can be overwritten by Sips

cardCSCResultCode* HP_2.0cardProductCode* HP_2.12cardProductName* HP_2.12cardProductProfile* HP_2.12cardProductUsageLabel * HP_2.18complementaryCode** HP_1.0complementaryInfo* HP_2.0creditorId* HP_2.7currencyCode HP_1.0 same request as abovecustomerBusinessName HP_2.17customerCompanyName HP_2.17customerEmail HP_2.0 same request as abovecustomerId HP_2.0 same request as abovecustomerIpAddress HP_2.0 same request or recalculated by Sips

Paypage if missingcustomerLegalId HP_2.17customerMobilePhone HP_2.1 same request as abovecustomerPositionOccupied HP_2.17dccAmount* HP_2.3dccCurrencyCode* HP_2.3dccExchangeRate* HP_2.3dccExchangeRateValidity* HP_2.3dccProvider* HP_2.3dccStatus* HP_2.3dccResponseCode* HP_2.3dueDate HP_2.3guarantheeIndicator* HP_2.0hashPan1* HP_2.0hashPan2* HP_2.0holderAuthentMethod** HP_2.4holderAuthentProgram* HP_2.5holderAuthentRelegation* HP_2.0holderAuthentStatus* HP_2.0holderContactEmail* HP_2.20instalmentAmountsList* HP_2.6instalmentDatesList* HP_2.6instalmentNumber* HP_2.6instalmentTransactionReferencesList* HP_2.6interfaceVersion* HP_1.0invoiceReference HP_2.10


39 of 47

InitialsWorldline

Initials

Public

Sips Paypage POST

Field Version CommentsissuerCode* HP_2.12issuerCountryCode* HP_2.12issuerEnrollementIndicator* HP_2.0issuerWalletInformation HP_2.9keyVersion* HP_1.0 same request as abovemandateAuthentMethod* HP_2.2mandateCertificationType* HP_2.7mandateId* HP_2.3mandateUsage* HP_2.2maskedPan** HP_1.0merchantId HP_1.0 same request as abovemerchantSessionId HP_2.0 same request as abovemerchantTransactionDateTime HP_2.0 same request as abovemerchantWalletId HP_2.0 same request as aboveorderChannel HP_2.0 same request as above.orderId HP_1.0 same request as abovepanEntryMode* HP_2.4panExpiryDate* HP_2.0paymentMeanBrand* HP_1.0paymentMeanBrandSelectionStatus* HP_2.14paymentMeanData* HP_2.2paymentMeanId* HP_2.6paymentMeanTradingName* HP_2.8paymentMeanType* HP_1.0paymentPattern* HP_2.0 same request as abovepreAuthenticationColor HP_2.10preAuthenticationInfo HP_2.10preAuthenticationProfile HP_2.10preAuthenticationProfileValue* HP_2.14

preAuthenticationRuleResultList*HP_2.14 List of preAuthenticationRuleResult

objects. See below for contents and format

preAuthenticationThreshold HP_2.10preAuthenticationValue HP_2.10preAuthorisationProfile* HP_2.14preAuthorisationProfileValue* HP_2.14

preAuthorisationRuleResultList* HP_2.14 List of preAuthorisationRuleResult objects. See below for contents and format

responseCode HP_1.0returnContext HP_1.0 same request as aboves10TransactionId HP_2.9s10TransactionIdDate HP_2.9s10transactionIdsList* HP_2.11scoreColor* HP_2.0scoreInfo* HP_2.0


40 of 47

InitialsWorldline

Initials

Public

Sips Paypage POST

Field Version CommentsscoreProfile* HP_2.0scoreThreshold* HP_2.0scoreValue* HP_2.0settlementMode HP_2.7settlementModeComplement HP_2.13statementReference* HP_2.4tokenPan* HP_2.0transactionActors* HP_2.2 same request as abovetransactionDateTime* HP_1.0transactionOrigin* HP_2.0 same request as abovetransactionPlatform HP_2.16 Future usage (systematically set to ‘PROD’

currently)transactionReference HP_1.0walletType* HP_2.4

*: these fields are filled in if they are available, which depends on the status of the transaction and on the selected means of payment.

Optional fields pertaining to fraud checks

Content of preAuthenticationRuleResult

Field Version CommentsruleCode HP_2.14ruleType HP_2.14ruleWeight HP_2.14ruleSetting HP_2.14ruleResultIndicator HP_2.14ruleDetailedInfo HP_2.14

Content of preAuthorisationRuleResult

Field Version CommentsruleCode HP_2.14ruleType HP_2.14ruleWeight HP_2.14ruleSetting HP_2.14ruleResultIndicator HP_2.14ruleDetailedInfo HP_2.14


41 of 47

InitialsWorldline

Initials

Public

Sips Paypage POST

Syntax of lists of complex objects in responsesThe format of a list of complex objects in automatic and manual responses is defined as follows (yellow highlighting):

..|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 surrounded by a pair of square brackets [ ].Each entry of the list is surrounded by a pair of curly brackets { }.Each field is represented as "fieldName" = "fieldValue". Note that the name and the value of the field are both surrounded by double quotes "". Pairs of adjacent names/values are separated by a comma.

Example of a preAuthorisationRuleResultList field Breakdown of the fraud rules executed during preauthorization (yellow highlighting):

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

3.2.7 Payment response analysisStatus Response fields Action to be performed

Payment acceptedresponseCode = 00acquirerResponseCode = 00garanteeIndicator = Y,N,U, empty

You can deliver the order depending on the level of guarantee you require (guaranteeIndicator field).

Declined – Sips fraudGONOGO

responseCode = 05complementaryCode = XXpreAuthorisationRuleResultList

The payment has been declined by the Sips fraud engine you have configured.Do not supply the merchandise.Analyse the detail of the fraud rules executed by Sips to understand the reason for declining (field preAuthorisationRuleResultList).

Declined – Sips fraudGONOGO

responseCode = 05complementaryCode = XXpreAuthorisationRuleResultList

The payment has been declined by the Sips fraud engine you have configured.Do not supply the merchandise.Analyse the detail of the fraud rules executed by Sips to understand the reason for declining (field preAuthorisationRuleResultList).


42 of 47

InitialsWorldline

Initials

Public

Sips Paypage POST

Status Response fields Action to be performed

Declined – Sips fraudBUSINESS SCORE

responseCode = 05scoreColor = RED, BLACKscoreValue = X (transaction score)scoreThreshold = X,Y (threshold orange, threshold green)

The payment has been refused by the Sips fraud engine you have configuredDo not supply the merchandise.Analyse the detail of the fraud rules executed by Sips to understand the reason for declining (field preAuthorisationRuleResultList).

Sips Fraud WarningBUSINESS SCORE

responseCode = 05scoreColor = ORANGEscoreValue = X (transaction score)scoreThreshold = X,Y (threshold orange, threshold green)

The payment has been authorised by the purchaser but the Sips fraud engine is issuing a warning in relation to the rules you have configured.Analyse the detail of the fraud rules executed by Sips to understand the reason for the warning (field preAuthorisationRuleResultList).If there is no risk in the transaction, accept it using the acceptChallenge function.If there is risk in the transaction, decline it using the refuseChallenge function.The acceptChallenge and refuseChallenge functions are available on the extranet and office connectors.

Declined – 3D Secure

reponseCode = 05holderAuthenStatus = FAILURE

Purchaser authentication has failed, which is not necessarily an instance of fraud.You can suggest that your customer pays with a different payment method by generating a new request.

Declined – purchaser’s bank

responseCode = 05acquirerResponseCode = XX

Authorisation has been declined for a reason not associated with fraud.You can suggest your customer pays with a different payment method by generating a new request.

Declined – purchaser fraud


Authorisation refused due to fraud.Do not supply the order.

Declined – max. number of attempts reached


The purchaser has made several attempts, all of which have failed because the information entered was incorrect. Two possibilities:Your customer is having difficulty in filling in the card informationCarding attempt (looking for possible card numbers)Contact your customer to determine what follow-up is required.


43 of 47

InitialsWorldline

Initials

Public

Sips Paypage POST

Status Response fields Action to be performed

Declined following a technical problem

responseCode = 90, 99acquirerResponseCode = 90 to 98

Temporary technical problem when the transaction was processed.Suggest that your customer attempts to pay again later.

3.3 Step 3: Doing tests 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 that you wish to use:

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

transactionReference generated by the merchant

Merchant ID (merchantId)Key version (keyVersion)Secret key

0020010000000011002001000000001_KEY1

transactionReference generated by SipsMerchant ID (merchantId)Key version (keyVersion)Secret key

0020010000000021002001000000002_KEY1

transactionId generated by the merchantMerchant ID (merchantId)Key version (keyVersion)Secret key

0020010000000031002001000000003_KEY1

transactionId generated by SipsMerchant ID (merchantId)Key version (keyVersion)Secret key

0020010000000041002001000000004_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 authorization servers so you can test the various results of a payment.Consequently, using actual cards is not necessary for tests.

Since the Merchant ID 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 store that will be used in the production environment. This also makes support easier if you call the technical support department.

You use a generic store without any customization of the payment page.


44 of 47

InitialsWorldline

Initials

Public

Sips Paypage POST

Step 4 will enable you to customize your payment pages.

3.3.1 Testing CB, Visa, MASTERCARD and AMEX transactionsThe following simulation rules apply to all cards:

The PAN must comprise between 16 and 19 digits. The first six digits of the PAN determine the type of card, as shown in the table below:

Card type First digits of the card numberAMEX 340000VPAY 400000VISA 410000CB 420000

Co-badged CB and VISA cards 430000Co-badged CB and VPAY cards 440000

Co-badged CB and VISA_ELECTRON cards 450000Co-badged VISA and MASTERCARD cards 460000

MAESTRO 500000MASTERCARD 510000

Co-badged CB and MASTERCARD cards 520000Co-badged CB and MAESTRO cards 530000

The Sips response code (responseCode field) is calculated using the last two digits of the card number.

The security code (CVV) comprises 3 or 4 digits. This value is not important for the result of the simulation.

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

Co-badged cards can be used with each of the brands defined in the table.Moreover, all cards are registered with 3D Secure, and you will be redirected to the 3D Secure simulation server where you can select the desired outcome from 3D Secure authentication.

3.3.2 Testing iDeal transactionsIf 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 result of the transaction.

Rules for simulating iDeal payment

Transaction amount iDeal responseEUR 2.00 Transaction cancelled


45 of 47

InitialsWorldline

Initials

Public

Sips Paypage POST

EUR 3.00 Transaction expiredEUR 4.00 Transaction not completedEUR 5.00 Transaction failed

Other amounts Transaction OK

3.3.3 Testing PayPal transactionsIf 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.

3.4 Step 4: Validating the switch to production environmentOnce you have tested the connection of your website to Sips Paypage, you can now validate the connection to the production version of Sips Paypage.

If you want to customize your payment pages, you can use our tool CustomPages, in order to test and view the rendering on payment pages. For this, please refer to the CustomPages documentation to use the tool.

We recommend you to isolate your website from the general public beforehand to prevent customers from carrying out transactions during this validation phase.

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

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

merchantId Shop ID received by email

SecretKey: Secret key that you retrieve via the Sips Download extranet

KeyVersion: Version of the secret key retrieved from Sips Download (logically 1 for the 1st key)

Forgetting one of these 4 settings is a frequent mistake that systematically results in an error.

How to validate proper functioning in the production environmentImmediately Carry out a transaction with an actual payment card (yours if possible).

If the transaction is accepted, it will be captured so your merchant account is credited and the card account is debited.

Make sure your payment pages include your customization settings. Use Sips Office Extranet to view the transaction from its transactionReference.

On the next day Make sure the transaction appears in the transaction logs.


46 of 47

InitialsWorldline

Initials

Public

Sips Paypage POST

Make sure your account has been credited with the amount of the operation. Refund the transaction via Sips Office Extranet (optional).

Two days later Make sure the refund operation appears in the operation log. Make sure the debited amount has been refunded to your merchant account.

3.5 Step 5: ReleaseOnce you have validated the switch to the production environment, open your site to the public so your customers can make purchases and payments.

During the day Monitor the acceptance rate (number of responseCode 00/total number of transactions). Check the nature of non-banking refusals

o Technical problem: responseCode 90, 97, 99o Fraud: responseCode 34o Maximum number of payment attempts reached: responseCode 75

On the next day Check the transaction log to make sure all processed transactions (accepted and refused) are

present. Check the operation log to view the operations and the remittances (log option) that you

carried out.

END OF DOCUMENT


47 of 47

InitialsWorldline

Initials

Documents

Sips Paypage POST - …€¦ · Web viewBasic knowledge of the standard ... These fields are designated with the word ... The payment request contains the transaction settings and