sips paypage post - …€¦ · web viewbasic knowledge of the standard ... these fields are...
TRANSCRIPT
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
Doc. No: 317.26.18R2.en© Worldline 2018
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.
Doc. No: 317.26.18R2.en© Worldline 2018
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.
Doc. No: 317.26.18R2.en© Worldline 2018
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
Doc. No: 317.26.18R2.en© Worldline 2018
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.
Doc. No: 317.26.18R2.en© Worldline 2018
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
Doc. No: 317.26.18R2.en© Worldline 2018
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>|……
Doc. No: 317.26.18R2.en© Worldline 2018
9 of 47
InitialsWorldline
Initials
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.
Doc. No: 317.26.18R2.en© Worldline 2018
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 ) )
Doc. No: 317.26.18R2.en© Worldline 2018
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);
Doc. No: 317.26.18R2.en© Worldline 2018
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(); }
Doc. No: 317.26.18R2.en© Worldline 2018
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.
Doc. No: 317.26.18R2.en© Worldline 2018
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();
}}
}
Doc. No: 317.26.18R2.en© Worldline 2018
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>
Doc. No: 317.26.18R2.en© Worldline 2018
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.
Doc. No: 317.26.18R2.en© Worldline 2018
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.
Doc. No: 317.26.18R2.en© Worldline 2018
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
Doc. No: 317.26.18R2.en© Worldline 2018
19 of 47
InitialsWorldline
Initials
Public
Sips Paypage POST
3.2.4 Filling in request fields
Generic fields
Doc. No: 317.26.18R2.en© Worldline 2018
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
Doc. No: 317.26.18R2.en© Worldline 2018
21 of 47
InitialsWorldline
Initials
Public
Sips Paypage POST
Field name PresenceVersio
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
Doc. No: 317.26.18R2.en© Worldline 2018
22 of 47
InitialsWorldline
Initials
Public
Sips Paypage POST
Field name PresenceVersio
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
Doc. No: 317.26.18R2.en© Worldline 2018
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
Doc. No: 317.26.18R2.en© Worldline 2018
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
Doc. No: 317.26.18R2.en© Worldline 2018
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
Doc. No: 317.26.18R2.en© Worldline 2018
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
Doc. No: 317.26.18R2.en© Worldline 2018
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
Doc. No: 317.26.18R2.en© Worldline 2018
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
Doc. No: 317.26.18R2.en© Worldline 2018
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
Doc. No: 317.26.18R2.en© Worldline 2018
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
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 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
Field Presence Version Comments
birthDate Optional HP_2.6
Doc. No: 317.26.18R2.en© Worldline 2018
31 of 47
InitialsWorldline
Initials
Public
Sips Paypage POST
Optional fields pertaining to shopping cart
Content of shoppingCartDetail
Field Presence Version Comments
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
Field Presence Version Comments
s10TransactionId Optional HP_2.7s10TransactionIdDate Optional HP_2.7
Doc. No: 317.26.18R2.en© Worldline 2018
32 of 47
InitialsWorldline
Initials
Public
Sips Paypage POST
Optional fields pertaining to risk management
Content of riskManagementCustomData
Field Presence Version Comments
riskManagementCustomSequence Optional HP_2.9riskManagementCustomValue Optional HP_2.9
Optional fields pertaining to seller data (for marketplaces)
Content of subMerchantAddress
Field Presence Version CommentsaddressAdditional1 Optional HP_2.15addressAdditional2 Optional HP_2.15addressAdditional3 Optional HP_2.15city Optional HP_2.15company Optional HP_2.15country Optional HP_2.15postBox Optional HP_2.15state Optional HP_2.15street Optional HP_2.15streetNumber Optional HP_2.15zipCode Optional HP_2.15
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
Doc. No: 317.26.18R2.en© Worldline 2018
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|..
Doc. No: 317.26.18R2.en© Worldline 2018
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.
…|currencyCode=826|..
Dynamic currency conversion (DCC)If a Dynamic Currency Conversion (DCC) service is used, the reference currency code must be specified:
Doc. No: 317.26.18R2.en© Worldline 2018
35 of 47
InitialsWorldline
Initials
Public
Sips Paypage POST
…|currencyCode=978|..
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.
Doc. No: 317.26.18R2.en© Worldline 2018
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
Doc. No: 317.26.18R2.en© Worldline 2018
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
Doc. No: 317.26.18R2.en© Worldline 2018
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
Doc. No: 317.26.18R2.en© Worldline 2018
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
Doc. No: 317.26.18R2.en© Worldline 2018
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
Doc. No: 317.26.18R2.en© Worldline 2018
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).
Doc. No: 317.26.18R2.en© Worldline 2018
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
responseCode = 34acquirerResponseCode = XX
Authorisation refused due to fraud.Do not supply the order.
Declined – max. number of attempts reached
responseCode = 75acquirerResponseCode = XX
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.
Doc. No: 317.26.18R2.en© Worldline 2018
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.
Doc. No: 317.26.18R2.en© Worldline 2018
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
Doc. No: 317.26.18R2.en© Worldline 2018
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.
Doc. No: 317.26.18R2.en© Worldline 2018
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
Doc. No: 317.26.18R2.en© Worldline 2018
47 of 47
InitialsWorldline
Initials