sips paypage json€¦ · web view2018-06-04 · these fields are designated with the word...

Sips Paypage JSON

Sips Payment Acceptance Solution

•••••• an atos company

Sips Paypage JSON

Contents

Change log ............................................................................................................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 payments with SIPS Paypage JSON .....................................63 Get started with Sips Paypage JSON 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 ...................................353.4 Step 4: Validating the switch to the production environment ...................373.5 Step 5: Release .........................................................................................38

Change log ............................................................................................................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 payments with SIPS Paypage JSON .....................................63 Get started with Sips Paypage JSON 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 ...................................343.4 Step 4: Validating the switch to the production environment ...................363.5 Step 5: Release .........................................................................................37

Doc. No: WLSIPS.316.19.18R2.en© Worldline 2018

2 of 39

Sips Paypage JSON

Change log

Date(yyyy/mm/dd)

Version Description

20178/1201/1430 19

Add new fields subMerchantName and subMerchantContractNumberAdd new field basket in cofidis3x containerAdded explanation of redirection towards Paypages of the initialization requestAdding explanation on the calculation of the Seal of the automatic and manual responsesAdded a new field, holderContactEmail, in manual and automatic responses

2017/09/21 18 Add new field responseEncodingCorrection in test cards

2017/08/04 17 Complete overhaul


3 of 39

Sips Paypage JSON

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 JSON 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 JSON mode between their websites and the Sips Paypage JSON 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 - Functionality implementation manual

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

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.

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


4 of 39

Sips Paypage JSON

1.4 Contacting the technical support departmentFor any technical question or request for support, you can contact our teams:

by phone at this number: +33 (0) 811 10 70 33 via e-mail: [email protected]

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


5 of 39

Sips Paypage JSON

2 Understanding payments with SIPS Paypage JSON

The payment process works as follows:

Merchant site Sips engineand payment pages.The customer enters

his card data; payment is performed.

The customer proceed the payment (finalization of

the order)

The merchant site redirect the customer to the payment

page

Merchant site

Page of order finalization

Return page to the website

Merchant site

Automatic response service

The customer comes back to your Website (manual

response)

Sips engine send an automatic response to your Web site

Sips PaypageConnector

JSON

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

The Merchant site redirects the calling application to the Sips payment pages. The customer must enter the information of the means of payment so the Sips payment server processes the transaction. It must be noted that payment details can be entered directly on the server that provides the means of payment (e.g. PayPal or SEPA mandate). At the end of the payment process, whether it has succeeded or failed, two responses are created and sent to the URL addresses specified as part of workflow n°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 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


6 of 39

Sips Paypage JSON

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 39

Sips Paypage JSON

3 Get started with Sips Paypage JSON 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 consists in a call from a REST (JSON) web service to the connector of the payment gateway.

3.2.1 Generating the payment requestAll the fields that the transaction requires must be supplied (see the “Filling in the fields of the request” section for details.

The value of interfaceVersion must be set to IR_WS_2.2019.

Request syntaxThe construction of the request complies with the JSON format.

{“<field name>” : ”<value name>”, “<field name>” : “<value name>”, “field name” : “value name” etc., “seal” : seal value” }

Example of a payment request with an amount of 10 euros:

{"amount" : "1000","automaticResponseUrl" : "https://responseurl.com","currencyCode" : "978","interfaceVersion" : "IR_WS_2.18","keyVersion" : "1","merchantId" : "000000000000012","normalReturnUrl" : "https://responseurl2.com","orderChannel" : "INTERNET","transactionReference" : "1232015021717313","seal" : "858005903b91ae3b3a076e29aca7dc6314c05aa6f929c439ecfce1de17ea7e39"}

The syntax used to create a JSON list complies with the standard. Here is a summary of this structure for the two main types of lists: lists of simple fields (e.g. character strings), and object lists.


8 of 39

Sips Paypage JSON

A field can have several values:…,"field name" : ["value1","value2"],…

Example with the paymentMeanBrandList field whose value is VISA and MASTERCARD:

…,"paymentMeanBrandList" : ["VISA","MASTERCARD"],…

If a field contains a list of complex objects, its representation complies with the following format:

…,“field name” : [{“name of subfield1”:”value1”,“name of subfield2”:”value2”},{“name of subfield1”:”value3”, name of subfield2”:”value4”}],…

Example of a payment request with a list of complex objects for the shoppingCartDetail field, which contains two products called apple et mango:

{"amount" : "1000","automaticResponseUrl" : "https://responseurl.com","currencyCode" : "978","interfaceVersion" : "IR_WS_2.8","keyVersion" : "1","merchantId" : "000000000000012","normalReturnUrl" : "https://responseurl2.com","orderChannel" : "INTERNET","shoppingCartDetail" : {"shoppingCartItemList" : [{"productCode" : "123","productName" : "apple"},{"productCode" : "456","productName" : "mango"}],"shoppingCartTotalAmount" : "1000"},"transactionReference" : "1232015021717313","seal" : "fac5bc8e5396d77a8b31a2a79a38750feea71b22106a2cec88efa3641a947345"}

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.


9 of 39

Sips Paypage JSON

How to make requests secureThe security of the request is based on the calculation of the value “hashed” in accordance with the transaction settings. The secret key is then added to it. All character strings are converted to UTF-8 before the hashing operation.

The hashing algorithm produces an irreversible result. 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 data called Seal.

Seal data calculationThe value of the Seal data is calculated as follows:

For the HMAC-SHA algorithm

The values of data fields are concatenated in the alphabetical order of field names except for the keyVersion and sealAlgorithm fields.

The data resulting from the previous operation are encoded in the UTF-8 format. The bytes obtained with the secret key are hashed using the HMAC-SHA256 algorithm.

This procedure can be summarized as follows:

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

Code samples Hmac Sha256 encoding in Php 5<?php

…

// Seal computation thanks to hash sorted data hash with merchant key$data_to_send=$amount.$captureDay.$captureMode.$cardCSCValue.$cardExpiryDate.$cardNumber.$cardSeqNumber.$currency_code.$pb.$customerId.$customerIpAddress.$ivers.$mid.$merchantTransactionDateTime.$orderChannel.$orderId.$returnContext.$opeorig.$tref;

$data_to_send= utf8_encode($data_to_send)

$seal=hash_hmac('sha256', $data_to_send, $secretKey);

……

?>

“data_to_send” and “secretKey” must use a UTF-8 character set. Refer to the utf8_encode function to convert ISO-8859-1 characters to UTF-8.

Hmac Sha256 encoding in Java

import java.security.InvalidKeyException;import java.security.NoSuchAlgorithmException;

import javax.crypto.Mac;


10 of 39

Sips Paypage JSON

import javax.crypto.spec.SecretKeySpec;

public class ExampleHMACSHA256 {

/** * table to convert a nibble to a hex char. */static final char[] hexChar = { '0' , '1' , '2' , '3' , '4' , '5' , '6' , '7' , '8' , '9' , 'a' , 'b' , 'c' , 'd' , 'e' , 'f'};

/** * Fast convert a byte array to a hex string * with possible leading zero. * @param b array of bytes to convert to string * @return hex representation, two chars per byte. */public static String encodeHexString ( byte[] b ) { StringBuffer sb = new StringBuffer( b.length * 2 ); for ( int i=0; i<b.length; i++ ) { // look up high nibble char sb.append( hexChar [( b[i] & 0xf0 ) >>> 4] );

// look up low nibble char sb.append( hexChar [b[i] & 0x0f] ); } return sb.toString(); }

/** * Computes the seal * @param Data the parameters to cipher * @param secretKey the secret key to append to the parameters * @return hex representation of the seal, two chars per byte. */public static String computeSeal(String data, String secretKey) throws Exception{ Mac hmacSHA256 = Mac.getInstance("HmacSHA256"); SecretKeySpec keySpec = new SecretKeySpec(secretKey.getBytes(), "HmacSHA256"); hmacSHA256.init(keySpec);

return encodeHexString(hmacSHA256.doFinal(data.getBytes()));}

/** * @param args */public static void main(String[] args) {

try {System.out.println (computeSeal("parameters", "key"));

} catch (Exception e) {e.printStackTrace();

}}

}

Example of Hmac Sha256 encoding in .net

(Done using a simple form called "Form 1" containing two text fields for entering txtSips and txtSecretKey, and another for displaying lblHEX)

using System;using System.Collections.Generic;using System.ComponentModel;using System.Data;


11 of 39

Sips Paypage JSON

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

}}

Example of payment requestHere is an example of request in JSON format:

{"amount":"1000","automaticResponseUrl":"https://www.automaticresponse.com","currencyCode":"978","interfaceVersion":"IR_WS_2.2019","keyVersion":"1","merchantId":"011223744550001","normalReturnUrl":" www.normalreturnurl.com","orderChannel":"INTERNET","transactionOrigin":"SITE","transactionReference":"OID20180103","seal":"814b3bb48f8db567cbbe2c2c17afc288a263c21db60f2cbf2538070c3ba3d51d"}

Example of redirect form to PaypageIn return to this request, you must receive an answer (also in JSON) containing lesthe following fields:

Field name Description

redirectionData Request token to provide during the redirection to the payment pages

redirectionStatusCode Possible response codes listredirectionStatusMessage Short message giving the iniatialization status.


12 of 39

Sips Paypage JSON

Field name Description

redirectionUrl UrlURL of the payment pages to which you have to redirect the client.

redirectionVersion Redirection version.seal Output sealreponseEncoding Encoding types used for answers

If the initialization of the payment succeeded, the field redirectionStatusCode must be valued with “00”. The fields redirectionData, redirectionVersion and redirectionUrl will also been valued to allow the redirection to Sips payment pages.

To redirect the client to the payment pages, you must implement a POST form sending the two following fields: redirectionData and redirectionVersion. The POST form will have to redirect the client to the URL provided in the field « redirectionUrl ».

Here is an example of a form which haves to be submitted automatically:

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

[3.2.2] Processing payment initialization errorsAll the fields that Sips Paypage JSON receives through the connector are verified individually. The table below lists the error messages that might be displayed during this step, and how to solve them.

redirectionStatusCode Description

00 Normal situation followed by the normal process used to display payment pages

03 merchantId or acquirer contract is invalid.

12 Transaction settings are invalid. Check request settings.

30 Request format is invalid.

34 Security problem e.g. the calculated seal is incorrect.

94 The transaction already exists.

99 Service temporarily unavailable

There are four possible situations: redirectionStatusCode = 00The user must be redirected to the payment page. redirectionStatusCode = 03, 12, 30, 34


13 of 39

Sips Paypage JSON

These error codes indicate that the request has a problem that must be solved. The payment process must be stopped. redirectionStatusCode = 94The transaction reference has already been used. The merchant must try again with another transaction reference. redirectionStatusCode = 99The payment service is unavailable. The merchant must try to submit the request again. A new transaction reference must be used to prevent response code 94 from being returned.

3.2.2[3.2.3] Filling in the fields of the request

Generic fields

Field Presence Version Commentsamount Mandatory WS_1.0currencyCode Mandatory WS_1.0interfaceVersion Mandatory WS_1.0keyVersion Mandatory WS_2.2merchantId Mandatory WS_1.0normalReturnUrl Mandatory WS_1.0orderChannel Mandatory WS_2.1transactionReference Mandatory WS_1.0 Optional if you use

S10TransactionReferences10TransactionReference Mandatory WS_2.7 Optional if you use

transactionReference; see below.

seal Mandatory WS_2.0authenticationData Optional WS_2.2automaticResponseUrl Optional WS_1.0billingAddress Optional WS_2.2 See below.billingContact Optional WS_2.2 See below.billingFirstDate Optional WS_2.5bypassReceiptPage Optional WS_2.0 See below.bypassDcc Optional WS_2.11captureDay Optional WS_1.0captureMode Optional WS_1.0customer3DSTransactionDate Optional WS_2.5customerAddress Optional WS_2.2 See below.customerContact Optional WS_2.2 See below.customerData Optional WS_2.2 See below.customerBillingNb Optional WS_2.5customerDeliverySuccessFlag Optional WS_2.5customerEmail Optional WS_1.0 Only available in WS_1.0 and

WS_2.0customerId Optional WS_2.0customerIpAddress Optional WS_2.1customerLanguage Optional WS_1.0customerPhoneValidationMethod Optional WS_2.5customerRegistrationDateOnline Optional WS_2.5


14 of 39

Sips Paypage JSON

Field Presence Version CommentscustomerRegistrationDateProxi Optional WS_2.5deliveryAddress Optional WS_2.2 See below.deliveryContact Optional WS_2.2 See below.deliveryData Optional WS_2.6 See below.deliveryFirstDate Optional WS_2.5evidenceAcquisitionDate Optional WS_2.5evidenceNumber Optional WS_2.5evidenceType Optional WS_2.5fraudData Optional WS_2.1 See below.hashAlgorithm1 Optional WS_2.1hashAlgorithm2 Optional WS_2.1hashSalt1 Optional WS_2.1hashSalt2 Optional WS_2.1holderAdditionalReference Optional WS_2.9holderAddress Optional WS_2.2 See below.holderContact Optional WS_2.2 See below.holderData Optional WS_2.2 See below.InstalmentData Optional WS_2.6 See below.intermediateServiceProviderId Optional WS_2.11invoiceReference Optional WS_2.0mandateId Optional WS_2.5merchantSessionId Optional WS_2.0merchantTransactionDateTime Optional WS_2.0merchantWalletID Optional WS_2.2orderContext Optional WS_2.16 See below.orderId Optional WS_1.0paymentMeanBrandList Optional WS_1.0 This field is a JSON list.paymentMeanData Optional WS_2.2 See below.paymentPattern Optiona

lConditionalWS_2.1 This field is mandatory for

certain means of payment. For further information, refer to the implementation manual of the means of payment concerned.

paypageData Optional WS_2.0 See below.responseEncoding Optional WS_2.19 This field allows choosing the

encoding to use in responses.responseKeyVersion Optional WS_2.0returnContext Optional WS_2.0riskManagementCustomDataList Optional WS_2.9 This field is a JSON list of

riskManagementCustomData objects.See below.

sealAlgorithm Optional WS_2.9shoppingCartDetail Optional WS_2.6 See below.statementReference Optional WS_2.1subMerchantAddress Optional WS_2.15 See below.subMerchantCategoryCode Optional WS_2.15subMerchantId Optional WS_2.15subMerchantLegalId Optional WS_2.15subMerchantShortName Optional WS_2.15


15 of 39

Sips Paypage JSON

Field Presence Version CommentstemplateName Optional WS_2.1transactionActors Optional WS_2.2transactionOrigin Optional WS_2.0travelContext Optional WS_2.16 See below.valueDate Optional WS_2.5subMerchantName Optional WS_2.20subMerchantContractNumber Optional WS_2.20

Optional fields pertaining to fraud Content of fraudData

Field Presence Version CommentsallowedCardArea Optional WS_2.1allowedCardCountryList Optional WS_2.1 This field is a JSON list.allowedIpArea Optional WS_2.1allowedIpCountryList Optional WS_2.1 This field is a JSON list.bypass3DS Optional WS_2.1bypassCtrlList Optional WS_2.1 This field is a JSON list.bypassInfoList Optional WS_2.1 This field is a JSON list.deniedCardArea Optional WS_2.1deniedCardCountryList Optional WS_2.1 This field is a JSON list.deniedIpArea Optional WS_2.1deniedIpCountryList Optional WS_2.1 This field is a JSON list.riskManagementDynamicSettingList

Optional WS_2.10 This field is a JSON list of riskManagementDynamicSetting objects.

Content of riskManagementDynamicSetting

Field Presence Version CommentsriskManagementDynamicParam Mandator

yConditionalWS_2.10

riskManagementDynamicValue MandatoryConditional

WS_2.10

Optional fields pertaining to payment pages Content of paypageData

Field Presence Version CommentsbypassReceiptPage Optional WS_2.0

Optional fields pertaining to cardholder authentication Content of authenticationData


16 of 39

Sips Paypage JSON

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

Content of issuerWalletPolicy

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

Content of cardAuthPolicy

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

Optional fields pertaining to means of payment Content of paymentMeandData

Field Presence Version Commentspaypal Optional WS_2.2 See belowsdd Optional WS_2.2 See belowcofinoga3xcb Optional WS_2.2 See belowpassbe Optional WS_2.5 See belowaccord Optional WS_2.6 See belowfacilypay Optional WS_2.6 See belowcetelemNxcb Optional WS_2.9 See belowpresto Optional WS_2.10 See belowcofidis3x Optional WS_2.11 See belowcofidis4x Optional WS_2.12 See belowunEuroCom Optional WS_2.11 See belowcofinoga Optional WS_2.15 See belowcetelem3x Optional WS_2.16 See belowcetelem4x Optional WS_2.16 See belowfranfinance3xcb Optional WS_2.18 See belowfranfinance4xcb Optional WS_2.18 See below

Content of paypal

Field Presence Version CommentslandingPage Optional WS_2.2addrOverride Optional WS_2.2invoiceId Optional WS_2.2dupFlag Optional WS_2.2dupDesc Optional WS_2.2dupCustom Optional WS_2.2dupType Optional WS_2.2mobile Optional WS_2.2


17 of 39

Sips Paypage JSON

Field Presence Version CommentsorderDescription Optional WS_2.16

Content of sdd

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

Content of cofinoga3xcb

Field Presence Version CommentscreditIndicator Optional WS_2.2

Content of passBe

Field Presence Version CommentssettlementModeList Optional WS_2.5

Content of facilypay

Field Presence Version CommentssettlementMode Optional WS_2.6settlementModeVersion Optional WS_2.6receiverType Optional WS_2.6depositRefundIndicator Optional WS_2.6

Content of accord

Field Presence Version CommentssettlementMode Optional WS_2.6

Content of cetelemNxcb

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

Content of presto

Field Presence Version CommentsfinancialProduct Conditiona

lMandatoryWS_2.10 Only mandatory

for Presto transactions

paymentMeanCustomerId ConditionalMandatory

WS_2.10 Only mandatory for Presto transactions

prestoCardType Optional WS_2.10


18 of 39

Sips Paypage JSON

Content of cofidis3x

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

Content of cofidis4x

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

Content of unEuroCom

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

Content of cofinoga

Field Presence Version CommentspaymentMeanTradeOptionList Optional WS_2.15 paymentMean

TradeOption is a container described below.

Content of paymentMeanTradeOption

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

Content of cetelem3x

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

Content of cetelem4x

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


19 of 39

Sips Paypage JSON

Content of franfinance3xcb

Field Presence Version CommentsauthenticationKey Conditiona

lMandatoryWS_2.18 Only mandatory for

franfinance Franfinance transactions

pageCustomizationCode Optional WS_2.18redirectionTimer Optional WS_2.18testEnvironment Optional WS_2.18birthPlaceCode Optional WS_2.18

Content of franfinance4xcb

Field Presence Version CommentsauthenticationKey Conditiona

lMandatoryWS_2.18 Only mandatory for

franfinance Franfinance transactions

pageCustomizationCode Optional WS_2.18redirectionTimer Optional WS_2.18testEnvironment Optional WS_2.18birthPlaceCode Optional WS_2.18

Optional fields pertaining to installment payments Content of instalmentData

Field Presence Version Comments

number Optional WS_2.2datesList Optional WS_2.2 This field is a JSON list.

transactionReferencesListOptiona

lConditionalMandatory

l

WS_2.2 This field is a JSON list. Optional if you use s10transactionIdsList.

s10transactionIdsListOptiona

lConditionalMandatory

WS_2.7 This field is a JSON list. Optional if you use transactionReferencesList.

amountsList Optional WS_2.2 This field is a JSON list.

Optional fields pertaining to the customer’s billing address Content of billingAddress


addressAdditional1 Optional WS_2.2addressAdditional2 Optional WS_2.2addressAdditional3 Optional WS_2.2city Optional WS_2.2company Optional WS_2.2country Optional WS_2.2


20 of 39

Sips Paypage JSON


postBox Optional WS_2.2state Optional WS_2.2street Optional WS_2.2streetNumber Optional WS_2.2zipCode Optional WS_2.2

Content of billingContact


email Optional WS_2.2firstname Optional WS_2.2gender Optional WS_2.2lastname Optional WS_2.2mobile Optional WS_2.2phone Optional WS_2.2title Optional WS_2.2

Optional fields pertaining to the customer’s address Content of customerAddress


addressAdditional1 Optional WS_2.2addressAdditional2 Optional WS_2.2addressAdditional3 Optional WS_2.2city Optional WS_2.2company Optional WS_2.2country Optional WS_2.2postBox Optional WS_2.2state Optional WS_2.2street Optional WS_2.2streetNumber Optional WS_2.2zipCode Optional WS_2.2businessName Optional WS_2.17

Content of customerContact


email Optional WS_2.2firstname Optional WS_2.2gender Optional WS_2.2lastname Optional WS_2.2mobile Optional WS_2.2


21 of 39

Sips Paypage JSON

phone Optional WS_2.2title Optional WS_2.2

intials Optional WS_2.12legalId Optional WS_2.17positionOccupied Optional WS_2.17

Content of customerData


birthCity Optional WS_2.2birthCountry Optional WS_2.2birthDate Optional WS_2.2birthZipCode Optional WS_2.2nationalityCountry Optional WS_2.2newPwd Optional WS_2.2pwd Optional WS_2.2maidenName Optional WS_2.18

Optional fields pertaining to the customer’s delivery address Content of deliveryAddress


addressAdditional1 Optional WS_2.2addressAdditional2 Optional WS_2.2addressAdditional3 Optional WS_2.2city Optional WS_2.2company Optional WS_2.2country Optional WS_2.2postBox Optional WS_2.2state Optional WS_2.2street Optional WS_2.2streetNumber Optional WS_2.2zipCode Optional WS_2.2

Content of deliveryContact


22 of 39

Sips Paypage JSON



Content of deliveryData


deliveryChargeAmount Optional WS_2.6estimatedDeliveryDate Optional WS_2.6estimatedDeliveryDelay Optional WS_2.7deliveryMode Optional WS_2.6deliveryMethod Optional WS_2.6deliveryOperator Optional WS_2.6

Optional fields pertaining to cardholder data Content of holderAddress



Content of holderContact


23 of 39

Sips Paypage JSON



Content of holderData


birthDate Optional WS_2.6

Optional fields pertaining to the shopping cart Content of shoppingCartDetail


shoppingCartTotalAmount Optional WS_2.6shoppingCartTotalQuantity Optional WS_2.6shoppingCartTotalTaxAmount Optional WS_2.7mainProduct Optional WS_2.6

shoppingCartItemListOptional WS_2.6 This field is a JSON

list of shoppingCartItem objects.

Content of shoppingCartItem


productName Optional WS_2.6productDescription Optional WS_2.6productCode Optional WS_2.6productSKU Optional WS_2.6productUnitAmount Optional WS_2.6productQuantity Optional WS_2.6productTaxRate Optional WS_2.6productUnitTaxAmount Optional WS_2.6productCategory Optional WS_2.6productTaxCategory Optional WS_2.11 For future use

Optional fields pertaining to the Sips 1.0 transactionId Content of s10TransactionReference


24 of 39

Sips Paypage JSON


s10TransactionId Optional WS_2.7s10TransactionIdDate Optional WS_2.7

Optional fields relating to risk management Content of riskManagementCustomData


riskManagementCustomSequence Optional WS_2.9riskManagementCustomValue Optional WS_2.9

Optional fields pertaining to seller data (for marketplaces) Content of subMerchantAddress



Optional fields pertaining to AMEX-EA Content of orderContext

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

Content of travelContext

Field Presence Version CommentsdepartureDate Optional WS_2.16passengerName Optional WS_2.16originAirport Optional WS_2.16


25 of 39

Sips Paypage JSON

Field Presence Version CommentsnumberOfRoutingCities Optional WS_2.16routingCityList Optional WS_2.16 This field is a

JSON list.numberOfAirlineCarriers Optional WS_2.16airlineCarrierList Optional WS_2.16 This field is a

JSON list.fareBasis Optional WS_2.16numberOfPassengers Optional WS_2.16destinationAirport Optional WS_2.16reservationCode Optional WS_2.16

3.2.3[3.2.4] Configuring the payment requestHere is an example of a payment configuration request for every functionality available in Sips Paypage JSON (functionalities are described in detail in the Functionalities manual.).

Dynamic display of means of payment

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":"true"},..

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

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


26 of 39

Sips Paypage JSON

Payment upon dispatch of the goods For 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",..

Installment payment For 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",..,"instalmentData":{"amountsList":["10000","20000","30000"],"datesList":["20170504","20170603","20170703"],"number":"3","transactionReferencesList":["tref1","tref2","tref3"]},..,"paymentPattern":"INSTALMENT",…

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:

....,"currencyCode":"978",..

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

..,{"bypass3DS":"ALL"},..

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


27 of 39

Sips Paypage JSON

..,{"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.4[3.2.5] 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 data, see

responseEncoding fieldSeal Signature of the response messageInterfaceVersion Version of the connector interface.

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.

For a seal to be computed with the HMAC-SHA-256 algorithm, the field sealAlgorithm has to be filled in with the value “HMAC-SHA-256” in your request.

Seal data calculationThe value of the Seal data is calculated as follows:

For the HMAC-SHA algorithm:


28 of 39

Sips Paypage JSON

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

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.


29 of 39

Sips Paypage JSON

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

acceptanceSystemApplicationId* HP_2.18acquirerNativeResponseCode* HP_2.12acquirerResponseCode* HP_2.0acquirerResponseIdentifier* HP_2.8acquirerResponseMessage* HP_2.8additionalAuthorisationNumber* HP_2.8amount HP_1.0 Same as in the request


30 of 39

Sips Paypage JSON

Field version Comments

authorisationId* HP_1.0authorisationTypeLabel* HP_2.18authorMessageReference* HP_2.18avsAddressResponseCode* HP_2.17avsPostcodeResponseCode* HP_2.17captureDay HP_1.0 Request field that Sips may overridecaptureLimiteDate* HP_2.3captureMode HP_1.0 Request field that Sips may overridecardCSCResultCode* HP_2.0cardProductCode* HP_2.12cardProductName* HP_2.12cardProductUsageLabel * HP_2.18cardProductProfile* HP_2.12complementaryCode** HP_1.0complementaryInfo* HP_2.0creditorId* HP_2.7currencyCode HP_1.0 Same as in the requestcustomerBusinessName HP_2.17customerCompanyName HP_2.17customerEmail HP_2.0 Same as in the requestcustomerId HP_2.0 Same as in the requestcustomerIpAddress HP_2.0 Same as in the request or

recalculated by Sips Paypage if missing

customerLegalId HP_2.17customerMobilePhone HP_2.1 Same as in the requestcustomerPositionOccupied 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.10issuerCode* HP_2.12


31 of 39

Sips Paypage JSON

Field version CommentsissuerCountryCode* HP_2.12issuerEnrollementIndicator* HP_2.0issuerWalletInformation HP_2.9keyVersion* HP_1.0 Same as in the requestmandateAuthentMethod* HP_2.2mandateCertificationType* HP_2.7mandateId* HP_2.3mandateUsage* HP_2.2maskedPan** HP_1.0merchantId HP_1.0 Same as in the requestmerchantSessionId HP_2.0 Same as in the requestmerchantTransactionDateTime HP_2.0 Same as in the requestmerchantWalletId HP_2.0 Same as in the requestorderChannel HP_2.0 Same as in the requestorderId HP_1.0 Same as in the requestpanEntryMode* HP_2.4panExpiryDate* HP_2.0paymentAttemptNumber HP_2.18paymentMeanBrand* HP_1.0paymentMeanBrandSelectionStatus* HP_2.14paymentMeanData* HP_2.2paymentMeanId* HP_2.6paymentMeanTradingName* HP_2.8paymentMeanType* HP_1.0paymentPattern* HP_2.0 Same as in the requestpreAuthenticationColor HP_2.10preAuthenticationInfo HP_2.10preAuthenticationProfile HP_2.10preAuthenticationProfileValue* HP_2.14

preAuthenticationRuleResultList*HP_2.14 List of preAuthenticationRuleResult

objects See below for its content 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 its content and format.

responseCode HP_1.0returnContext HP_1.0 Same as in the requests10TransactionId HP_2.9s10TransactionIdDate HP_2.9s10transactionIdsList* HP_2.11scoreColor* HP_2.0scoreInfo* HP_2.0scoreProfile* HP_2.0scoreThreshold* HP_2.0


32 of 39

Sips Paypage JSON

Field version CommentsscoreValue* HP_2.0settlementMode HP_2.7settlementModeComplement HP_2.13statementReference* HP_2.4tokenPan* HP_2.0transactionActors* HP_2.2 Same as in the requesttransactionDateTime* HP_1.0transactionOrigin* HP_2.0 Same as in the requesttransactionPlatform HP_2.16 For future use (for now, its value is

systematically set to ‘PROD’.)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

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


33 of 39

Sips Paypage JSON

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.5[3.2.6] Payment response analysisStatus Response fields Action to perform

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

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

Sips fraud refusalGONOGO

responseCode = 05complementaryCode = XXpreAuthorisationRuleResultList

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

- Do not deliver the goods.- Analyze the details of the fraud

rules executed by Sips to know the reason for the refusal (preAuthorisationRuleResultList field).

Sips fraud refusalBUSINESS SCORE

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

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

- Do not deliver the goods.- Analyze the details of the fraud

rules executed by Sips to know the reason for the refusal (preAuthorisationRuleResultList field).


34 of 39

Sips Paypage JSON

Status Response fields Action to perform

Sips fraud warning

BUSINESS SCORE

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

- The acquirer has authorized the payment, but the Sips fraud engine issued a warning due to the rules that you configured.

- Analyze the details of the fraud rules executed by Sips to know the reason for the warning (preAuthorisationRuleResultList field).

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

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

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

3D Secure refusal responseCode = 05holderAuthenStatus = FAILURE

Buyer authentication failed. This is not necessarily due to fraud.

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

Banking refusal from the acquirer

responseCode = 05acquirerResponseCode = XX

The authorization is refused for a reason that is not related to fraud.

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

Fraud refusal from the acquirer


The authorization has been refused because of fraud.

Do not deliver the order.

Refusal because the maximum number of attempts has been reached


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

- Your customer has difficulties entering their card information.

- Carding attempt (search for possible card numbers)

Contact your customer to define what to do next.

Refusal due to technical problem

responseCode = 90, 99acquirerResponseCode = 90 to 98

Temporary technical problem while processing the transaction.

Tell your customer to attempt the payment again later.


35 of 39

Sips Paypage JSON

3.3 Step 3: Doing tests in the simulation environmentOnce 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:

Simulation server URL https://payment-webinit.simu.sips-atos.com/rs-services/v2/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.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 consist of 16 to 19 digits. The first six digits of the PAN determine the type of card as per the table below:


36 of 39

Sips Paypage JSON

Type of card Card number begins withAMEX 340000VPAY 400000VISA 410000CB 420000

CB-VISA co-branded cards 430000CB-VPAY co-branded cards 440000

CB-VISA_ELECTRON co-branded cards 450000VISA-MASTERCARD co-branded cards 460000

MAESTRO 500000MASTERCARD 510000

CB-MASTERCARD co-branded cards 520000CB-MAESTRO co-branded cards 530000

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

The security code (CVV) consists of 3 or 4 digits. This value does not matter when it comes to the result of the simulation.

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

Co-branded cards can be used with every brand defined in the table.Moreover, all cards are enrolled in the 3D Secure program. You are redirected to the 3D Secure simulation server on which you choose the result you want for 3D 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 response2.00 EUR Transaction cancelled3.00 EUR Transaction expired4.00 EUR Transaction not carried out5.00 EUR Transaction failed

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


37 of 39

Sips Paypage JSON

3.4 Step 4: Validating the switch to the production environment

Once 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/rs-services/v2/paymentInit

merchantId Store identifier sent via e-mail

SecretKey Secret key that your retrieve from the Sips Download extranet

KeyVersion Version of the secret key retrieved from Sips Download (logically 1 for the first 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. 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: Release

Once 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, 99


38 of 39

Sips Paypage JSON

o 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. U DOCUMENT

END OF DOCUMENT


39 of 39

sips paypage json€¦ · web view2018-06-04 · these fields are designated with the word...

Documents