Introduction

WL Sips is a secure multi-channel e-commerce payment solution that complies with the PCI DSS standard. It allows you to accept and manage payment transactions by taking into account business rules related to your activity (payment on despatch, deferred payment, recurring payment, payment in instalments, etc.).

The purpose of this document is to explain the implementation steps of the Sips Office JSON solution up to live operations.

Who does this document target?

This document is intended for merchants wishing to subscribe to the WL Sips offer and use a connector based on JSON exchanges via the REST protocol, in machine-to-machine mode.

It is an implementation guide for your technical team.

To get an overview of the WL Sips solution, we advise you to consult the following documents:

  • Functional presentation
  • Functionality set-up guide

Prerequisites

Knowledge of standards related to web programming languages used today, such as Java, PHP or .Net, is necessary to develop a connection to Sips Office JSON .

Note: all code sections in this document are provided as samples, you will need to adapt them to your website for them to be fully operable.

Secret key management

Upon your subscription, Worldline provides a secret key on the Sips Download extranet that will allow you to secure exchanges between your website and the WL Sips server.

You are responsible for looking after this key and should take all measures to:

  • Restrict access to the key
  • Safeguard it by encrypting it
  • Never copy it onto a non-secure disc or device
  • Never send it (via e-mail or regular mail) in a non-secure method.

A secret key compromised (and used by a malicious third party) might disrupt the regular operation of your shop and might in particular generate unauthorised sales or cash transactions (e.g. refunds).

IMPORTANT: in the event that a secret key is compromised, you are required to ask as quickly as possible for its revocation then for its renewal via the Sips Download extranet (please refer to the "Secret key revocation and renewal" section in the Quick start guide).

The very same secret key is used on the various Sips Paypage , Sips Office , Sips In-App and Sips Walletpage connectors.

IMPORTANT: a secret key is associated with a version. After getting a new secret key, you must modify your request and populate the keyVersion field with the new version, otherwise you will get an answer code 34 (suspected fraud).

Understanding payment using Sips Office JSON

The general principle for a payment process is as follows:

1. Customers must enter means of payment information when they make payments on your site.

2. You send the payment information to the WL Sips payment server so that it processes the transaction. The server sends a response so that you can display the payment result.

3. You display the ticket containing the payment result.

Getting started with Sips Office in 6 steps

Step 1: registering the shop

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

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

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

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

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

Step 2: using available functions

The various possible functions are the subject of specific requests.

Tip: before using a function, make sure you have the rights to use this function on your shop by contacting the WL Sips technical support.

A request is made up of generic fields and container fields.

A container is a structure used to functionally group data.

If the field is a container, this specification is indicated in the comment column which refers you to the dedicated chapter detailing the contents of all the fields of this type.

A request is a call to a REST (JSON) web service located on the WL Sips payment platform. All of the necessary fields must be provided for each request.

Attention: please remember you need to indicate in your message header that the data to be processed is of JSON type. To do this, you need to specify the 'Content-Type: application/json' header in your JSON message. Otherwise you might receive an error message similar to the following:
        <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
<html>
    <head>
        <title>415 Unsupported Media Type</title>
    </head>
    <body>
        <h1>Unsupported Media Type</h1>
        <p>The supplied request data is not in a format
acceptable for processing by this resource.</p>
    </body>
</html>
      
Note: in the responses, depending on the transaction status and the means of payment chosen, some fields can be null, empty or not returned. Please refer to the means of payment documentations to know the fields present in the responses.

Request syntax

The request is structured in line with the JSON format:

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

Sample payment request with an amount of 10 euros:

      {"amount" : "1000","automaticResponseUrl" : "https://responseurl.com","currencyCode" : "978","interfaceVersion" : "IR_WS_2.19","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 list types: simple field lists (e.g. character strings) and object lists.

A field can have several values:

      …,"field name" : ["value1","value2"],…
    

Sample paymentMeanBrandList field with VISA and MASTERCARD as values:

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

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

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

Sample payment request with a list of complex objects for the shoppingCartDetail field, containing two products, apple and 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 presence

Some fields of the payment request are required:

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

Those fields are marked as "conditional".

Securing the request

The request includes the transaction parameters and is sent by the customer's web browser. Theoretically, a third party can intercept the request and modify its content before the data reaches the payment server.

Therefore it is necessary to strengthen security so as to ensure the integrity of the parameters of the transaction sent. The WL Sips solution meets this challenge by exchanging signatures. An effective signature control comprises two elements:

  • The integrity of the request and response messages.
  • The issuer and recipient authentication, as they share the same secret key.
IMPORTANT: if your secret key is compromised, or if you suspect this might be the case, you should always go to Sips Download to request a new one.

How to secure the request

The request is secured by calculating the hash value in line with the transaction parameters. Then, the secret key is added to it. All character strings are converted to UTF-8 before being hashed.

The hashing algorithm generates an irreversible result. When such a message is received, the recipient needs to recalculate the hash value and compare it with the one received. Any difference indicates that the data exchanged was falsified, or that the recipient and the issuer do not share the same secret key.

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

Calculating the Seal data element

HMAC-SHA algorithm

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

  • Concatenation of data field values in the alphabetical order of field names (in accordance with ASCII character codes), without integrating the keyVersion and sealAlgorithm fields. Giving the field data , mentioned in the examples below.
    • as an example, a field that would be named authorMessageReference must be positioned before another field named authorisationId
  • Obtaining the UTF-8 encoding of the data from the previous result
  • HMAC with SHA256 encryption of bytes obtained with the secret key

This procedure can be summarised as follows:

      HMAC-SHA256( UTF-8(sortedDataValues), UTF-8(secretKey))
    
Note: by default, the seal is calculated with the HMAC-SHA-256 algorithm. For a seal to be computed with the SHA-256 algorithm, the input parameters of the request must include the sealAlgorithm field populated with the following value: “SHA-256”.

Hmac Sha256 sample code

  • Sample Hmac Sha256 encoding in Php 5
            
    <?php
    
    …
    
    // Seal computation thanks to hash sorted data hash with merchant key
    
    $data_to_send= utf8_encode($data)
    
    $seal=hash_hmac('sha256', $data_to_send, $secretKey);
    
    …
    …
    
    ?> 
          

    data_to_send and secretKey must use a UTF-8 character set. Please refer to the utf8_encode function for the conversion of ISO-8859-1 characters in UTF-8.

  • Sample Hmac Sha256 encoding in Java
            
    import java.security.InvalidKeyException;
    import java.security.NoSuchAlgorithmException;
    
    import javax.crypto.Mac;
    import javax.crypto.spec.SecretKeySpec;
    
    public class ExampleHMACSHA256 {
    
    /**
     * table to convert a nibble to a hex char.
     */
    static final char[] hexChar = {
       '0' , '1' , '2' , '3' ,
       '4' , '5' , '6' , '7' ,
       '8' , '9' , 'a' , 'b' ,
       'c' , 'd' , 'e' , 'f'};
    
    /**
     * Fast convert a byte array to a hex string
     * with possible leading zero.
     * @param b array of bytes to convert to string
     * @return hex representation, two chars per byte.
     */
    public static String encodeHexString ( byte[] b )
       {
       StringBuffer sb = new StringBuffer( b.length * 2 );
       for ( int i=0; i<b.length; i++ )
          {
          // look up high nibble char
          sb.append( hexChar [( b[i] & 0xf0 ) >>> 4] );
    
          // look up low nibble char
          sb.append( hexChar [b[i] & 0x0f] );
          }
       return sb.toString();
       }
    
    /**
     * Computes the seal
     * @param Data the parameters to cipher
     * @param secretKey the secret key to append to the parameters 
     * @return hex representation of the seal, two chars per byte.
     */
    public static String computeSeal(String data, String secretKey) throws Exception
    {
      Mac hmacSHA256 = Mac.getInstance("HmacSHA256");
      SecretKeySpec keySpec = new SecretKeySpec(secretKey.getBytes(), "HmacSHA256");
      hmacSHA256.init(keySpec);
    
      return encodeHexString(hmacSHA256.doFinal(data.getBytes()));
    }
    
    /**
     * @param args
     */
    public static void main(String[] args) {
    try {
    System.out.println (computeSeal("parameters", "key"));
    } catch (Exception e) {
    e.printStackTrace();
    }
    }
    
    }
          
  • Sample Hmac Sha256 encoding in .net

    (Carried out using a simple form called "Form1" containing two text fields to enter data and txtSecretKey , and another field to display  lblHEX ).

            
    using System;
    using System.Collections.Generic;
    using System.ComponentModel;
    using System.Data;
    using System.Drawing;
    using System.Text;
    using System.Windows.Forms;
    using System.Security.Cryptography;
    
    namespace ExampleDotNET
    {
        public partial class Form1 : Form
        {
            public Form1()
            {
                InitializeComponent();
            }
    
            private void cmdGO_Click(object sender, EventArgs e)
            {
                String sChaine = data.Text;
                UTF8Encoding utf8 = new UTF8Encoding();
                Byte[] encodedBytes = utf8.GetBytes(sChaine);
            
                byte[] shaResult;
                
                HMAC hmac = new HMAC.Create("HMACSHA256");
                var key = "YourSecretKey";
                hmac.Key = utf8.GetBytes(key); 
                hmac.Initialize();
    
                shaResult = hmac.ComputeHash(encodedBytes);
    
                lblHEX.Text = ByteArrayToHEX(shaResult);
            }
    
            private string ByteArrayToHEX(byte[] ba)
            {
                StringBuilder hex = new StringBuilder(ba.Length * 2);
                foreach (byte b in ba)
                    hex.AppendFormat("{0:x2}", b);
                return hex.ToString();
            }
    
        }
    }
          

Seal calculation validation

Once you have set up your seal calculation, here is a sample request to help you verify that you find the correct seal:

      {
  "amount": "2500",
  "captureDay": "0",
  "captureMode": "AUTHOR_CAPTURE",
  "cardCSCValue": "000",
  "cardExpiryDate": "201612",
  "cardNumber": "1234123412341234",
  "currencyCode": "978",
  "customerContact":{
    "email":"customer@email.com"
  },
  "interfaceVersion": "IR_WS_2.3",
  "keyVersion": "1",
  "merchantId": "011223344550000",
  "orderChannel": "INTERNET",
  "orderId": "ORD101",
  "returnContext": "ReturnContext",
  "transactionOrigin": "SO_WEBAPPLI",
  "transactionReference": "TREFEXA2012",
  "seal": "f1772faa4b73c0fc5a9810ad7fcaf91458d6174b2178a0a0a2bea2d860b404f5"
}
    

For the above request, the concatenated string which must be calculated is:

      25000AUTHOR_CAPTURE0002016121234123412341234978customer@email.comIR_WS_2.3
011223344550000INTERNETORD101ReturnContextSO_WEBAPPLITREFEXA2012
    

With a HMAC-SHA-256 hash algorithm and the following secret key:

      secret123
    

The expected seal is:

      f1772faa4b73c0fc5a9810ad7fcaf91458d6174b2178a0a0a2bea2d860b404f5
    

Function "CardOrder" of service "checkout"

Requests for payment orders via card include the bellow elements.

Sensitive information (card number, card security code) can be handled in three ways, via the panType field:

  • encryption via the CSE mode (see the relevant documentation)
  • card number tokenisation
  • card number in plain text (significant PCI constraint)

The URL is : https://office-server.sips-atos.com /rs-services/v2/checkout/cardOrder

cardOrder request format

Field Presence As of Version Comments
amount Mandatory WS_2.0
captureDay Optional WS_2.0
captureMode Optional WS_2.0
cardCSCValue Optional WS_2.0
cardEffectiveDate Optional WS_2.0
cardExpiryDate Optional WS_2.0
cardNumber Mandatory WS_2.0
cardSeqNumber Optional WS_2.0
currencyCode Mandatory WS_2.0
customerId Optional WS_2.0
customerIpAddress Optional WS_2.0
fraudData Optional WS_2.0 See the Containers part
merchantId Mandatory WS_2.0
merchantTransactionDateTime Optional WS_2.0
orderChannel Conditional WS_2.0 Optional for AccordKdo Card, mandatory for all other payment means
orderId Optional WS_2.0
interfaceVersion Mandatory WS_2.0 The recommended value is IR_WS_ 2.32 in order to take advantage of the latest features
returnContext Optional WS_2.0
transactionReference Conditional WS_2.0 Mandatory if you do not use the s10TransactionReference, depending on your merchant configuration
transactionOrigin Optional WS_2.0
billingAddress Optional WS_2.0 See the Containers part
billingContact Optional WS_2.0 See the Containers part
customerAddress Optional WS_2.0 See the Containers part
customerContact Optional WS_2.0 See the Containers part
deliveryAddress Optional WS_2.0 See the Containers part
deliveryContact Optional WS_2.0 See the Containers part
deliveryData Optional WS_2.19 See the Containers part
holderAddress Optional WS_2.0 See the Containers part
holderContact Optional WS_2.0 See the Containers part
customerData Optional WS_2.0 See the Containers part
authenticationData Optional WS_2.0 See the Containers part
invoiceReference Optional WS_2.0
statementReference Optional WS_2.2
paymentPattern Conditional WS_2.2 This field is mandatory for certain payment means. Please refer to the respective payment mean implementation guide for details
panType Optional WS_2.4
paymentMeanBrand Optional WS_2.2
paymentMeanData Optional WS_2.5 See the Containers part
holderData Optional WS_2.5 See the Containers part
s10TransactionReference Conditional WS_2.6 Mandatory if you do not use the transactionReference, depending on your merchant configuration. See the Containers part
riskManagementCustomDataList Optional WS_2.8 List of container riskManagementCustomData . See the Containers part
shoppingCartDetail Optional WS_2.8 See the Containers part
intermediateServiceProviderId Optional WS_2.12
seal Mandatory WS_2.0
keyVersion Mandatory WS_2.0
sealAlgorithm Optional WS_2.12
paymentMeanBrandSelectionStatus Optional WS_2.13 If this field is given in the input the paymentMeanBrand is mandatory
subMerchantId Optional WS_2.14
subMerchantShortName Optional WS_2.14
subMerchantCategoryCode Optional WS_2.14
subMerchantLegalId Optional WS_2.14
subMerchantAddress Optional WS_2.14 See the Containers part
customerLanguage Optional WS_2.15
travelContext Optional WS_2.19 See the Containers part
orderContext Optional WS_2.19 See the Containers part
paymentMeanDataProvider Optional WS_2.31
panEntryMode Optional WS_2.31

Example of request for cardOrder

      {
  "amount": "2500",
  "captureDay": "0",
  "captureMode": "AUTHOR_CAPTURE",
  "cardCSCValue": "0000",
  "cardExpiryDate": "201612",
  "cardNumber": "1234123412341234",
  "currencyCode": "978",
  "interfaceVersion": " IR_WS_2.3",
  "keyVersion": "1",
  "merchantId": "011223344550000",
  "orderChannel": "INTERNET",
  "orderId": " ORD101",
  "returnContext": " ReturnContext",
  "transactionOrigin": " SO_WEBAPPLI",
  "transactionReference": "TREFEXA2012",
  "seal": "2205f0636dc500c4f3ef536075895b8baba3a60c7087e06cd9d330c50a50c53e"
}

    

cardOrder response format

Field As of Version Comments
acquirerResponseCode WS_2.0 Only if refused during the pre-authorisation check
authorisationId WS_2.0
cardScheme WS_2.0
complementaryCode WS_2.0
complementaryInfo WS_2.0
guaranteeIndicator WS_2.0
holderAuthentRelegationCode WS_2.0
holderAuthentStatus WS_2.0
maskedPan WS_2.0
responseCode WS_2.0
returnContext WS_2.0 Value transferred to the payment request
scoreColor WS_2.0
scoreInfo WS_2.0
scoreProfile WS_2.0
scoreThreshold WS_2.0
scoreValue WS_2.0
transactionDateTime WS_2.0
tokenPan WS_2.0
cardCSCResultCode WS_2.2
avsPostcodeResponseCode WS_2.2
avsAddressResponseCode WS_2.2
recurringResponseCode WS_2.2
acquirerResponseIdentifier WS_2.5 Returned only if the interfaceVersion is less than 2.19.
acquirerResponseMessage WS_2.5
paymentMeanTradingName WS_2.5
paymentMeanData WS_2.5 See the Containers part
s10TransactionReference WS_2.6 See the Containers part
transactionReference WS_2.6
cardData WS_2.9 See the Containers part
seal WS_2.0
preAuthorisationProfile WS_2.13
preAuthorisationProfileValue WS_2.13
preAuthorisationRuleResultList WS_2.13 List of container preAuthorisationRuleResult . See the Containers part
paymentMeanBrandSelectionStatus WS_2.13
captureDay WS_2.15
captureMode WS_2.15
transactionPlatform WS_2.17 Always filled with « PROD »
authorMessageReference WS_2.19 Replace acquirerResponseIdentifier
authorisationTypeLabel WS_2.19
acceptanceSystemApplicationId WS_2.20
errorFieldName WS_2.21
panEntryMode WS_2.22
walletType WS_2.22
issuerWalletInformation WS_2.22
paymentMeanBrand WS_2.22
intermediateServiceProviderOperationId WS_2.24
orderId WS_2.24
paymentMeanDataProvider WS_2.31
schemeTransactionIdentifier WS_2.31
paymentAccountReference WS_2.31
guaranteeLimitDateTime WS_2.32

Example of response for cardOrder

      {
  "acquirerResponseCode": "00",
  "authorisationId": "123456789102",
  "cardScheme": "MASTERCARD",
  "complementaryCode": "",
  "complementaryInfo": "",
  "maskedPan": "5219##########00",
  "responseCode": "00",
  "returnContext": "ReturnContext",
  "transactionDateTime": "2012-10-16T23:50:44-12:00",
  "seal": "7ca065ebba90762e3286ee16d6a2d2da0eea8bae6b46592058933881d96d0c3d",
  "transactionPlatform": "PROD"
}

    

Function "Refund" of service "cashManagement"

This function makes it possible to re-credit the buyer\'s account.

Note : please read the set-up guide ('cash management > refund' section), to find out in which cases you can perform a refund operation.

The URL is : https://office-server.sips-atos.com /rs-services/v2/cashManagement/refund

refund request format

Field Presence As of Version Comments
operationAmount Mandatory WS_2.0
currencyCode Mandatory WS_2.0
merchantId Mandatory WS_2.0
interfaceVersion Mandatory WS_2.0 The recommended value is CR_WS_ 2.32 in order to take advantage of the latest features
transactionReference Conditional WS_2.0 Mandatory if you do not use the s10TransactionReference, depending on your merchant configuration
operationOrigin Optional WS_2.0
paymentMeanData Optional WS_2.5 See the Containers part
s10TransactionReference Conditional WS_2.6 Mandatory if you do not use the transactionReference, depending on your merchant configuration. See the Containers part
shoppingCartDetail Optional WS_2.11 See the Containers part
intermediateServiceProviderId Optional WS_2.12
seal Mandatory WS_2.0
keyVersion Mandatory WS_2.0
sealAlgorithm Optional WS_2.12
customerContact Optional WS_2.20 See the Containers part

Example of request for refund

      {
  "currencyCode": "978",
  "interfaceVersion": "CR_WS_2.3",
  "merchantId": "011223344550000",
  "operationAmount": "1000",
  "operationOrigin": "SO_BATCH",
  "transactionReference": "TREFEXA2012",
  "keyVersion": "1",
  "seal": "bed2f99d4137d402fde0c86a182f7d4f01c68e57d8a073fe5e920c57d06da1b5"
}

    

refund response format

Field As of Version Comments
acquirerResponseCode WS_2.0
authorisationId WS_2.0
newAmount WS_2.0
newStatus WS_2.0
operationDateTime WS_2.0
responseCode WS_2.0
seal WS_2.0
errorFieldName WS_2.21

Example of response for refund

      {
  "acquirerResponseCode": "00",
  "authorisationId": "123456789102",
  "newAmount": 0,
  "operationDateTime": "2012-10-16T23:45:34-12:00",
  "responseCode": "00",
  "newStatus": "TO_CREDIT",
  "seal": "919b544bfb60539c8979992bc469e0b4229030ee2462a51f62c9cbd3510b3647"
}

    

Function "Validate" of service "cashManagement"

This function makes it possible to trigger the transmission of a transaction to a bank.

Note : please read the set-up guide ('cash management > validation' section), to find out in which cases you can perform a validation operation.

The URL is : https://office-server.sips-atos.com /rs-services/v2/cashManagement/validate

validate request format

Field Presence As of Version Comments
operationAmount Mandatory WS_2.0
currencyCode Mandatory WS_2.0
merchantId Mandatory WS_2.0
interfaceVersion Mandatory WS_2.0 The recommended value is CR_WS_ 2.32 in order to take advantage of the latest features
transactionReference Conditional WS_2.0 Mandatory if you do not use the s10TransactionReference, depending on your merchant configuration
operationOrigin Optional WS_2.0
lastRecoveryIndicator Optional WS_2.16
s10TransactionReference Conditional WS_2.6 Mandatory if you do not use the transactionReference, depending on your merchant configuration. See the Containers part
intermediateServiceProviderId Optional WS_2.12
seal Mandatory WS_2.0
keyVersion Mandatory WS_2.0
sealAlgorithm Optional WS_2.12
subMerchantId Optional WS_2.14
subMerchantShortName Optional WS_2.14
subMerchantCategoryCode Optional WS_2.14
subMerchantLegalId Optional WS_2.14
subMerchantAddress Optional WS_2.14 See the Containers part

Example of request for validate

      {
  "currencyCode": "978",
  "interfaceVersion": "CR_WS_2.3",
  "merchantId": "011223344550000",
  "operationAmount": "1200",
  "operationOrigin": "SO_BATCH",
  "transactionReference": "TREFEXA2012",
  "keyVersion": "1",
  "seal": "bed2f99d4137d402fde0c86a182f7d4f01c68e57d8a073fe5e920c57d06da1b5"
}

    

validate response format

Field As of Version Comments
acquirerResponseCode WS_2.0
authorisationId WS_2.0
newAmount WS_2.0
newStatus WS_2.0
operationDateTime WS_2.0
responseCode WS_2.0
captureLimitDate WS_2.1
seal WS_2.0
errorFieldName WS_2.21
schemeTransactionIdentifier WS_2.31
paymentAccountReference WS_2.31
guaranteeIndicator WS_2.32
secureReference WS_2.32

Example of response for validate

      {
  "acquirerResponseCode": "00",
  "authorisationId": "123456789102",
  "newAmount": 1000,
  "operationDateTime": "2012-10-16T23:53:19-12:00",
  "responseCode": "00",
  "newStatus": "TO_CAPTURE",
  "seal": "919b544bfb60539c8979992bc469e0b4229030ee2462a51f62c9cbd3510b3647"
}

    

Function "Duplicate" of service "cashManagement"

This function makes it possible to create a new transaction using the bank details of an existing transaction.

Note : please read the set-up guide ('cash management > duplication' section), to find out in which cases you can perform a duplication operation.

The URL is : https://office-server.sips-atos.com /rs-services/v2/cashManagement/duplicate

duplicate request format

Field Presence As of Version Comments
amount Mandatory WS_2.0
captureDay Optional WS_2.0
captureMode Optional WS_2.0
currencyCode Mandatory WS_2.0
customerEmail Optional WS_2.0
customerId Optional WS_2.0
customerIpAddress Optional WS_2.0
fraudData Optional WS_2.0 See the Containers part
fromTransactionReference Optional WS_2.0
merchantId Mandatory WS_2.0
merchantTransactionDateTime Optional WS_2.0
orderChannel Optional WS_2.0
orderId Optional WS_2.0
interfaceVersion Mandatory WS_2.0 The recommended value is CR_WS_ 2.32 in order to take advantage of the latest features
returnContext Optional WS_2.0
transactionReference Conditional WS_2.0 Mandatory if you do not use the s10TransactionReference, depending on your merchant configuration
transactionOrigin Optional WS_2.0
fromMerchantId Optional WS_2.1
deliveryAddress Optional WS_2.1 See the Containers part
deliveryContact Optional WS_2.1 See the Containers part
billingAddress Optional WS_2.19 See the Containers part
billingContact Optional WS_2.19 See the Containers part
customerAddress Optional WS_2.19 See the Containers part
customerContact Optional WS_2.19 See the Containers part
customerData Optional WS_2.19 See the Containers part
statementReference Optional WS_2.2
deliveryData Optional WS_2.5 See the Containers part
shoppingCartDetail Optional WS_2.5 See the Containers part
s10TransactionReference Conditional WS_2.6 Mandatory if you do not use the transactionReference, depending on your merchant configuration. See the Containers part
s10FromTransactionReference Optional WS_2.6 See the Containers part
paymentMeanData Optional WS_2.12 See the Containers part
intermediateServiceProviderId Optional WS_2.12
seal Mandatory WS_2.0
keyVersion Mandatory WS_2.0
sealAlgorithm Optional WS_2.12
subMerchantId Optional WS_2.14
subMerchantShortName Optional WS_2.14
subMerchantCategoryCode Optional WS_2.14
subMerchantLegalId Optional WS_2.14
subMerchantAddress Optional WS_2.14 See the Containers part
holderAddress Optional WS_2.17 See the Containers part
holderContact Optional WS_2.19 See the Containers part
authenticationData Optional WS_2.17 See the Containers part
travelContext Optional WS_2.19 See the Containers part
orderContext Optional WS_2.19 See the Containers part

Example of request for duplicate

      {
  "amount": "1000",
  "currencyCode": "978",
  "captureDay": "0",
  "captureMode": "AUTHOR_CAPTURE",
  "customerEmail": "customer@email.com",
  "customerId": "654321",
  "customerIpAddress": "127.0.0.1",
  "interfaceVersion": " CR_WS_2.3",
  "merchantId": "011223344550000",
  "orderChannel": "INTERNET",
  "orderId": "123456",
  "returnContext": "ReturnContext",
  "transactionOrigin": "SO_BATCH",
  "fromTransactionReference": "TREFEXA20122",
  "transactionReference": "TREFEXA20121",
  "keyVersion": "1",
  "seal": "db2bbdd9550b5b7dc316d4b2859a0c45189aeaaf46b899cd90d5bde272e6ae24"
}

    

duplicate response format

Field As of Version Comments
acquirerResponseCode WS_2.0
authorisationId WS_2.0
complementaryCode WS_2.0
complementaryInfo WS_2.0
maskedPan WS_2.3
panExpiryDate WS_2.3
paymentMeanBrand WS_2.3
scoreValue WS_2.0
scoreColor WS_2.0
scoreInfo WS_2.0
scoreProfile WS_2.0
scoreThreshold WS_2.0
responseCode WS_2.0
transactionDateTime WS_2.0
s10TransactionReference WS_2.6 See the Containers part
transactionReference WS_2.6
cardData WS_2.9 See the Containers part
seal WS_2.0
paymentMeanBrandSelectionStatus WS_2.13
preAuthorisationProfile WS_2.13
preAuthorisationProfileValue WS_2.13
preAuthorisationRuleResultList WS_2.13 List of container preAuthorisationRuleResult . See the Containers part
transactionPlatform WS_2.17 Always filled with « PROD »
avsPostcodeResponseCode WS_2.17
avsAddressResponseCode WS_2.17
errorFieldName WS_2.21
schemeTransactionIdentifier WS_2.31
paymentAccountReference WS_2.31

Example of response for duplicate

      {
  "acquirerResponseCode": "00",
  "authorisationId": "069308",
  "responseCode": "00",
  "transactionDateTime": "2012-10-16T23:48:14-12:00",
  "seal": "0fdd9a35319712a9feff14eee0f68bbd35bd8fb6000819b2d5cd17b2704d6b6f",
  "transactionPlatform": "PROD"
}

    

Function "Cancel" of service "cashManagement"

This function makes it possible to edit the amount of a transaction or to cancel a transaction to be sent to a bank.

You cannot cancel a cancelled operation and you cannot cancel an amount higher than the original one.

Note : please read the set-up guide ('cash management > cancellation' section), to find out in which cases you can perform a cancellation operation.

The URL is : https://office-server.sips-atos.com /rs-services/v2/cashManagement/cancel

cancel request format

Field Presence As of Version Comments
operationAmount Mandatory WS_2.0
currencyCode Mandatory WS_2.0
merchantId Mandatory WS_2.0
interfaceVersion Mandatory WS_2.0 The recommended value is CR_WS_ 2.32 in order to take advantage of the latest features
transactionReference Conditional WS_2.0 Mandatory if you do not use the s10TransactionReference, depending on your merchant configuration
operationOrigin Optional WS_2.0
s10TransactionReference Conditional WS_2.6 Mandatory if you do not use the transactionReference, depending on your merchant configuration. See the Containers part
intermediateServiceProviderId Optional WS_2.12
seal Mandatory WS_2.0
keyVersion Mandatory WS_2.0
sealAlgorithm Optional WS_2.12
customerContact Optional WS_2.20 See the Containers part

Example of request for cancel

      {
  "currencyCode": "978",
  "interfaceVersion": "CR_WS_2.3",
  "merchantId": "011223344550000",
  "operationAmount": "120",
  "operationOrigin": "SO_BATCH",
  "transactionReference": "TREFEXA2012",
  "keyVersion": "1",
  "seal": "bed2f99d4137d402fde0c86a182f7d4f01c68e57d8a073fe5e920c57d06da1b5"
}

    

cancel response format

Field As of Version Comments
newAmount WS_2.0
operationDateTime WS_2.0
responseCode WS_2.0
newStatus WS_2.0
seal WS_2.0
acquirerResponseCode WS_2.20
errorFieldName WS_2.21

Example of response for cancel

      {
  "newAmount": 0,
  "operationDateTime": "2012-10-16T23:51:42-12:00",
  "responseCode": "00",
  "newStatus": "CANCELLED",
  "seal": "919b544bfb60539c8979992bc469e0b4229030ee2462a51f62c9cbd3510b3647"
}

    

Function "GetTransactionData" of service "diagnostic"

This function makes it possible to recover information regarding a specific transaction previously set up using WL Sips which is stored in the WL Sips database.

The URL is : https://office-server.sips-atos.com /rs-services/v2/diagnostic/getTransactionData

getTransactionData request format

Field Presence As of Version Comments
merchantId Mandatory WS_2.0
interfaceVersion Mandatory WS_2.0 The recommended value is DR_WS_ 2.32 in order to take advantage of the latest features
transactionReference Conditional WS_2.0 Mandatory if you do not use the s10TransactionReference, depending on your merchant configuration
s10TransactionReference Conditional WS_2.6 Mandatory if you do not use the transactionReference, depending on your merchant configuration. See the Containers part
intermediateServiceProviderId Optional WS_2.12
seal Mandatory WS_2.0
keyVersion Mandatory WS_2.0
sealAlgorithm Optional WS_2.12

Example of request for getTransactionData

      {
  "interfaceVersion": "DR_WS_2.3",
  "merchantId": "011223344550000",
  "transactionReference": "TREFEXA2012",
  "keyVersion": "1",
  "seal": "112a4b079ece08a0a55511cd5469fc47051d6ddb1404623170ba3873668e5c58"
}

    

getTransactionData response format

Field As of Version Comments
automaticResponseStatus WS_2.0
authorisationId WS_2.0
captureLimitDate WS_2.0
paymentMeanType WS_2.0
paymentMeanBrand WS_2.0
currencyCode WS_2.0
currentAmount WS_2.0
customerId WS_2.0
customerIpAddress WS_2.0
lastOperationDateTime WS_2.0
lastOperationName WS_2.0
orderId WS_2.0
originAmount WS_2.0
transactionDateTime WS_2.0
responseCode WS_2.0 Response code associated to the transaction
tokenPan WS_2.0
transactionStatus WS_2.0
orderChannel WS_2.0
paymentPattern WS_2.0
merchantId WS_2.0
panEntryMode WS_2.1
walletType WS_2.1
holderAuthentMethod WS_2.1
holderAuthentStatus WS_2.1
holderAuthentProgram WS_2.1
dccStatus WS_2.1
remainingAmount WS_2.2
fromTransactionReference WS_2.2
maskedPan WS_2.2
panExpiryDate WS_2.2
s10TransactionReference WS_2.6 See the Containers part
s10FromTransactionReference WS_2.6 See the Containers part
transactionReference WS_2.6
cardData WS_2.9 See the Containers part
acquirerResponseMessage WS_2.9
seal WS_2.0
complementaryCode WS_2.13
preAuthenticationColor WS_2.13
preAuthenticationProfile WS_2.13
preAuthenticationProfileValue WS_2.13
preAuthenticationThreshold WS_2.13
preAuthenticationValue WS_2.13
preAuthorisationProfile WS_2.13
preAuthorisationProfileValue WS_2.13
scoreColor WS_2.13
scoreProfile WS_2.13
scoreThreshold WS_2.13
scoreValue WS_2.13
cardCSCResultCode WS_2.17
avsPostcodeResponseCode WS_2.17
avsAddressResponseCode WS_2.17
getTransDataResponseCode WS_2.18 Response code of this operation
acquirerResponseCode WS_2.18
paymentAttemptNumber WS_2.19
errorFieldName WS_2.21
paymentMeanDataProvider WS_2.31

Example of response for getTransactionData

      {
  "automaticResponseStatus": "UNDEFINED",
  "authorisationId": "298392",
  "captureLimitDate": "20140108",
  "paymentMeanType": "CARD",
  "paymentMeanBrand": "MASTERCARD",
  "currencyCode": "826",
  "currentAmount": 1000,
  "customerId": "customerId1",
  "customerIpAddress": "127.0.0.1",
  "lastOperationDateTime": "2014-01-07T12:50:10+01:00",
  "lastOperationName": "TRANSACTION",
  "orderId": "123",
  "originAmount": 1000,
  "transactionDateTime": "2014-01-07T12:50:01+01:00",
  "responseCode": "00",
  "transactionStatus": "TO_CAPTURE",
  "orderChannel": "INTERNET",
  "paymentPattern": "ONE_SHOT",
  "merchantId": "011223344550000",
  "seal": "d971d516610f68050a71068c49ae778c37eb1c9b16f2ec90a3feadeb1bb60876"
}

    

Function "GetFraudData" of service "diagnostic"

This function makes it possible to recover information concerning fraud control regarding a specific transaction previously set up using WL Sips which is stored in the WL Sips database.

The URL is : https://office-server.sips-atos.com /rs-services/v2/diagnostic/getFraudData

getFraudData request format

Field Presence As of Version Comments
merchantId Mandatory WS_2.13
interfaceVersion Mandatory WS_2.13 The recommended value is DR_WS_ 2.32 in order to take advantage of the latest features
transactionReference Conditional WS_2.13 Mandatory if you do not use the s10TransactionReference, depending on your merchant configuration
s10TransactionReference Conditional WS_2.13 Mandatory if you do not use the transactionReference, depending on your merchant configuration. See the Containers part
intermediateServiceProviderId Optional WS_2.13
seal Mandatory WS_2.13
keyVersion Mandatory WS_2.13
sealAlgorithm Optional WS_2.13

Example of request for getFraudData

      {
  "interfaceVersion": "DR_WS_2.13",
  "keyVersion": "1",
  "merchantId": "029107704346091",
  "sealAlgorithm": "SHA-256",
  "transactionReference": "12345678945613",
  "seal": "1b30f5b8bfb1739adf716e5c86c67e5034c91c29cd2651a5e0b8d6e5e12a6be5"
}

    

getFraudData response format

Field As of Version Comments
complementaryCode WS_2.13
fraudResponseCode WS_2.13
preAuthenticationColor WS_2.13
preAuthenticationProfile WS_2.13
preAuthenticationProfileValue WS_2.13
preAuthenticationRuleResultList WS_2.13 List of container preAuthenticationRuleResult . See the Containers part
preAuthenticationThreshold WS_2.13
preAuthenticationValue WS_2.13
preAuthorisationProfile WS_2.13
preAuthorisationProfileValue WS_2.13
preAuthorisationRuleResultList WS_2.13 List of container preAuthorisationRuleResult . See the Containers part
scoreColor WS_2.13
scoreProfile WS_2.13
scoreThreshold WS_2.13
scoreValue WS_2.13
seal WS_2.13
errorFieldName WS_2.21

Example of response for getFraudData

      {
  "fraudResponseCode": "00",
  "preAuthorisationProfile": "MP0050",
  "preAuthorisationRuleResultList": [
    {
      "ruleCode": "CA",
      "ruleType": "N",
      "ruleWeight": "4",
      "ruleSetting": "S",
      "ruleResultIndicator": "-4",
      "ruleDetailedInfo": "MIN\u003d1000:2000;MAX\u003d1000:100000"
    },
    {
      "ruleCode": "PE",
      "ruleType": "N",
      "ruleWeight": "4",
      "ruleSetting": "S",
      "ruleResultIndicator": "0",
      "ruleDetailedInfo": "EXPIRY\u003d1216:0616"
    },
    {
      "ruleCode": "EC",
      "ruleType": "N",
      "ruleWeight": "2",
      "ruleSetting": "N",
      "ruleResultIndicator": "U"
    }
  ],
  "scoreColor": "BLACK",
  "scoreProfile": "MP0050",
  "scoreThreshold": "-17;-8",
  "scoreValue": "-4.0",
  "seal": "0c67850db20d23c8efd5f186c8f03104b697f1b4f49ef18af18cddf74b01bcbb"
}

    

Function "CardCheckEnrollment" of service "checkout"

Requests for payment initialization via card with 3-D Secure process.

In this document, unless otherwise stated, any reference to 3-D Secure includes Visa (Verified by Visa), MasterCard (SecureCode) and American Express (SafeKey).

This request initializes a transaction on WL Sips platform and checks the card enrollment. If the card is enrolled to 3D-Secure program, you will receive in response a secure URL (redirectionUrl) to which the customer should be redirected to continue the authentication. This redirection must be made via a POST form, see the part "POST form to the ACS". On the other hand, you can proceed with the payment directly by calling cardValidateAuthenticationAndOrder method.

Sensitive information (card number, card security code) can be handled in three ways, via the panType field:

  • encryption via the CSE mode (see the relevant documentation)
  • card number tokenisation
  • card number in plain text (significant PCI constraint)

The URL is : https://office-server.sips-atos.com /rs-services/v2/checkout/cardCheckEnrollment

cardCheckEnrollment request format

Field Presence As of Version Comments
amount Mandatory WS_2.0
captureDay Optional WS_2.0
captureMode Optional WS_2.0
cardCSCValue Optional WS_2.0
cardExpiryDate Mandatory WS_2.0
cardNumber Mandatory WS_2.0
currencyCode Mandatory WS_2.0
customerId Optional WS_2.0
invoiceReference Optional WS_2.0
merchantId Mandatory WS_2.0
merchantName Optional WS_2.0 Allow to change the name displayed on the 3-D Secure authentication page
merchantReturnUrl Optional WS_2.0
merchantUrl Optional WS_2.0
merchantTransactionDateTime Optional WS_2.0
orderChannel Mandatory WS_2.0
orderId Optional WS_2.0
returnContext Optional WS_2.0
interfaceVersion Mandatory WS_2.0 The recommended value is IR_WS_ 2.32 in order to take advantage of the latest features
transactionReference Conditional WS_2.0 Mandatory if you do not use the s10TransactionReference, depending on your merchant configuration
transactionOrigin Optional WS_2.0
statementReference Optional WS_2.0
paymentPattern Optional WS_2.0
customerIpAddress Optional WS_2.0
customerLanguage Optional WS_2.0
billingAddress Optional WS_2.0 See the Containers part
billingContact Optional WS_2.0 See the Containers part
customerAddress Optional WS_2.0 See the Containers part
customerContact Optional WS_2.0 See the Containers part
deliveryAddress Optional WS_2.0 See the Containers part
deliveryContact Optional WS_2.0 See the Containers part
deliveryData Optional WS_2.19 See the Containers part
holderAddress Optional WS_2.0 See the Containers part
holderContact Optional WS_2.0 See the Containers part
customerData Optional WS_2.0 See the Containers part
shoppingCartDetail Optional WS_2.19 See the Containers part
fraudData Optional WS_2.0 See the Containers part
authenticationData Optional WS_2.0 See the Containers part
s10TransactionReference Conditional WS_2.0 Mandatory if you do not use the transactionReference, depending on your merchant configuration. See the Containers part
panType Optional WS_2.11
intermediateServiceProviderId Optional WS_2.12
seal Mandatory WS_2.0
keyVersion Mandatory WS_2.0
sealAlgorithm Optional WS_2.12
paymentMeanBrand Optional WS_2.13
paymentMeanBrandSelectionStatus Optional WS_2.13 If this field is given in the input the paymentMeanBrand is mandatory
travelContext Optional WS_2.19 See the Containers part
orderContext Optional WS_2.19 See the Containers part
paymentMeanData Optional WS_2.18 See the Containers part
customerAccountHistoric Optional WS_2.23 See the Containers part

Example of request for cardCheckEnrollment

      {
  "amount": "1000",
  "captureDay": "0",
  "captureMode": "AUTHOR_CAPTURE",
  "cardCSCValue": "123",
  "cardExpiryDate": "201602",
  "cardNumber": "1234123412341234",
  "currencyCode": "978",
  "interfaceVersion": "IR_WS_2.9",
  "keyVersion": "1",
  "merchantId": "011223344550000",
  "merchantTransactionDateTime": "2015-05-28T11:23:14.211+02:00",
  "orderChannel": "INTERNET",
  "orderId": "1234",
  "transactionReference": "TREFEXA2015",
  "seal": "607083393a51b4b23261270df83c28a61e06f74928bc1e868c0abb9325dde2f2"
}

    

cardCheckEnrollment response format

Field As of Version Comments
redirectionUrl WS_2.0
errorFieldName WS_2.0
paReqMessage WS_2.0
redirectionData WS_2.0
redirectionStatusCode WS_2.0
messageVersion WS_2.0
seal WS_2.0
paymentMeanBrandSelectionStatus WS_2.13
responseCode WS_2.23
maskedPan WS_2.32
tokenPan WS_2.32

Example of response for cardCheckEnrollment

      {
  "redirectionUrl": "http://www.acssiteweb.com",
  "paReqMessage": "eJxVUU1zgj...Rv8P/AJQjttc\u003d",
  "redirectionData": "uqjeV+Keg...MAwXk2jDJAe2TI\u003d",
  "redirectionStatusCode": "00",
  "messageVersion": "0.1",
  "seal": "3c40cf8c12a8eebdfc114c83db8f944b77932b03814d8bf43ea792c20d05e7a6"
}

    

Function "WalletCheckEnrollment" of service "checkout"

Requests for payment initialization via wallet with 3-D Secure process.

In this document, unless otherwise stated, any reference to 3-D Secure includes Visa (Verified by Visa), MasterCard (SecureCode) and American Express (SafeKey).

This request initializes a transaction on WL Sips platform and checks the card enrollment retrieved from the wallet. If the enrollment step is successful, you will receive in response a secure URL (redirectionUrl) to which the customer should be redirected to continue the authentication. This redirection must be made via a POST form, see the part "POST form to the ACS". On the other hand, you can proceed with the payment directly by calling cardValidateAuthenticationAndOrder method.

The URL is : https://office-server.sips-atos.com /rs-services/v2/checkout/walletCheckEnrollment

walletCheckEnrollment request format

Field Presence As of Version Comments
amount Mandatory WS_2.0
authenticationData Optional WS_2.0 See the Containers part
billingAddress Optional WS_2.0 See the Containers part
billingContact Optional WS_2.0 See the Containers part
captureDay Optional WS_2.0
captureMode Optional WS_2.0
currencyCode Mandatory WS_2.0
customerAddress Optional WS_2.0 See the Containers part
customerContact Optional WS_2.0 See the Containers part
customerData Optional WS_2.0 See the Containers part
customerId Optional WS_2.0
customerIpAddress Optional WS_2.0
customerLanguage Optional WS_2.0
deliveryAddress Optional WS_2.0 See the Containers part
deliveryContact Optional WS_2.0 See the Containers part
deliveryData Optional WS_2.19 See the Containers part
fraudData Optional WS_2.0 See the Containers part
holderAddress Optional WS_2.0 See the Containers part
holderContact Optional WS_2.0 See the Containers part
shoppingCartDetail Optional WS_2.19 See the Containers part
interfaceVersion Mandatory WS_2.0 The recommended value is IR_WS_ 2.32 in order to take advantage of the latest features
invoiceReference Optional WS_2.0
merchantId Mandatory WS_2.0
merchantName Optional WS_2.0 Allow to change the name displayed on the 3-D Secure authentication page
merchantReturnUrl Optional WS_2.0
merchantTransactionDateTime Optional WS_2.0
merchantUrl Optional WS_2.0
orderChannel Mandatory WS_2.0
orderId Optional WS_2.0
merchantWalletId Mandatory WS_2.0
paymentMeanId Mandatory WS_2.0
paymentPattern Optional WS_2.0
returnContext Optional WS_2.0
statementReference Optional WS_2.0
transactionOrigin Optional WS_2.0
transactionReference Conditional WS_2.0 Mandatory if you do not use the s10TransactionReference, depending on your merchant configuration
cardCSCValue Optional WS_2.0
cscType Optional WS_2.32
s10TransactionReference Conditional WS_2.0 Mandatory if you do not use the transactionReference, depending on your merchant configuration. See the Containers part
intermediateServiceProviderId Optional WS_2.12
seal Mandatory WS_2.0
keyVersion Mandatory WS_2.0
sealAlgorithm Optional WS_2.12
orderContext Optional WS_2.19 See the Containers part
travelContext Optional WS_2.19 See the Containers part

Example of request for walletCheckEnrollment

      {
  "amount": "1000",
  "captureDay": "0",
  "captureMode": "AUTHOR_CAPTURE",
  "cardCSCValue": "123",
  "currencyCode": "978",
  "interfaceVersion": "IR_WS_2.9",
  "keyVersion": "1",
  "merchantId": "011223344550000",
  "merchantTransactionDateTime": "2015-05-28T11:30:14.232+02:00",
  "merchantWalletId": "WALLET01",
  "orderChannel": "INTERNET",
  "orderId": "1234",
  "paymentMeanId": "10",
  "transactionReference": "TREFEXA2015",
  "seal": "3bfc4e958ba4ea43090db3c0c0bdba7162c92727ca1338b2111b28ddd91056a1"
}

    

walletCheckEnrollment response format

Field As of Version Comments
redirectionUrl WS_2.0
errorFieldName WS_2.0
paReqMessage WS_2.0
redirectionData WS_2.0
redirectionStatusCode WS_2.0
messageVersion WS_2.0
seal WS_2.0
responseCode WS_2.23

Example of response for walletCheckEnrollment

      {
  "redirectionUrl": "http://www.acssiteweb.com",
  "paReqMessage": "eJxVUU1zgj...Rv8P/AJQjttc\u003d",
  "redirectionData": "uqjeV+Keg...MAwXk2jDJAe2TI\u003d",
  "redirectionStatusCode": "00",
  "messageVersion": "0.1",
  "seal": "3c40cf8c12a8eebdfc114c83db8f944b77932b03814d8bf43ea792c20d05e7a6"
}

    

Function "CardValidateAuthenticationAndOrder" of service "checkout"

Requests for payment finalization and order with a 3-D Secure process.

In this document, unless otherwise stated, any reference to 3-D Secure includes Visa (Verified by Visa), MasterCard (SecureCode) and American Express (SafeKey).

This request is mandatory to perform the payment order with a 3-D Secure context (PARes message). It must be called after you received the POST form from the ACS (Access Control Server) (See Post form to the ACS).

The URL is : https://office-server.sips-atos.com /rs-services/v2/checkout/cardValidateAuthenticationAndOrder

cardValidateAuthenticationAndOrder request format

Field Presence As of Version Comments
interfaceVersion Mandatory WS_2.0 The recommended value is IR_WS_ 2.32 in order to take advantage of the latest features
messageVersion Mandatory WS_2.0 Must be identical to the messageVersion field received from cardCheckEnrollment or walletCheckEnrollment method
merchantId Mandatory WS_2.0
redirectionData Mandatory WS_2.0
transactionReference Conditional WS_2.0 Mandatory if you do not use the s10TransactionReference, depending on your merchant configuration
s10TransactionReference Conditional WS_2.0 Mandatory if you do not use the transactionReference, depending on your merchant configuration. See the Containers part
paResMessage Conditional WS_2.0 Mandatory if an authentification validation operation must be done on your card, do not fill this field only if you would like to attempt a 'CardValidateAuthenAndOrder' operation with a not-enrolled card. If you fill it, use 'PARes' field returned by the customer bank ACS when the card enrollment has been checked with application of standard encoding 'Url Encode'.
intermediateServiceProviderId Optional WS_2.12
seal Mandatory WS_2.0
keyVersion Mandatory WS_2.0
sealAlgorithm Optional WS_2.12

Example of request for cardValidateAuthenticationAndOrder

      {
  "interfaceVersion": "IR_WS_2.9",
  "keyVersion": "1",
  "merchantId": "011223344550000",
  "messageVersion": "0.1",
  "paResMessage": "eJydVVuTqjgQ....7h%2FwH0CKem",
  "redirectionData": "uqjeV+KegCSM0POI...CjVUfxqyFq7zSYus7E\u003d",
  "transactionReference": "TREFEXA2015",
  "seal": "9565b71cb583f025278de91940c69900dee72d91e8184ddb6547f00927597fd1"
}

    

cardValidateAuthenticationAndOrder response format

Field As of Version Comments
acquirerResponseCode WS_2.0
acquirerResponseMessage WS_2.0
amount WS_2.0
authorisationId WS_2.0
avsAddressResponseCode WS_2.0
avsPostcodeResponseCode WS_2.0
captureDay WS_2.0
captureMode WS_2.0
cardCSCResultCode WS_2.0
cardExpiryDate WS_2.0
complementaryCode WS_2.0
complementaryInfo WS_2.0
currencyCode WS_2.0
customerId WS_2.0
customerIpAddress WS_2.0
errorFieldName WS_2.0
holderAuthentMethod WS_2.0
holderAuthentRelegation WS_2.0 Returned only if the interfaceVersion is less than 2.17. Please use the field holderAuthentRelegationCode
holderAuthentStatus WS_2.0
holderAuthentProgram WS_2.0
invoiceReference WS_2.0
guaranteeIndicator WS_2.0
maskedPan WS_2.0
merchantTransactionDateTime WS_2.0
merchantId WS_2.0
orderChannel WS_2.0
orderId WS_2.0
paymentMeanBrand WS_2.0
paymentPattern WS_2.0
responseCode WS_2.0
returnContext WS_2.0
statementReference WS_2.0
holderAuthentResponseCode WS_2.23
transactionDateTime WS_2.0
transactionReference WS_2.0
tokenPan WS_2.0
scoreColor WS_2.0
scoreInfo WS_2.0
scoreProfile WS_2.0
scoreThreshold WS_2.0
scoreValue WS_2.0
s10TransactionReference WS_2.0 See the Containers part
seal WS_2.0
paymentMeanBrandSelectionStatus WS_2.13
preAuthorisationProfile WS_2.13
preAuthorisationProfileValue WS_2.13
preAuthorisationRuleResultList WS_2.13 List of container preAuthorisationRuleResult . See the Containers part
acquirerNativeResponseCode WS_2.14
transactionPlatform WS_2.17 Always filled with « PROD »
holderAuthentRelegationCode WS_2.17
cardData WS_2.19 See the Containers part
authorMessageReference WS_2.19
authorisationTypeLabel WS_2.19
acceptanceSystemApplicationId WS_2.20
panEntryMode WS_2.21
walletType WS_2.21
issuerWalletInformation WS_2.21
intermediateServiceProviderOperationId WS_2.24
holderAuthentType WS_2.24
authentExemptionReasonList WS_2.31
schemeTransactionIdentifier WS_2.31
paymentAccountReference WS_2.31
guaranteeLimitDateTime WS_2.32

Example of response for cardValidateAuthenticationAndOrder

      {
  "amount": 1000,
  "authorisationId": "010628",
  "avsAddressResponseCode": "1",
  "avsPostcodeResponseCode": "1",
  "captureDay": 0,
  "captureMode": "AUTHOR_CAPTURE",
  "cardExpiryDate": "201602",
  "currencyCode": "978",
  "holderAuthentStatus": "3D_SUCCESS",
  "guaranteeIndicator": "Y",
  "maskedPan": "4907##########00",
  "merchantId": "011223344550000",
  "orderChannel": "INTERNET",
  "orderId": "1234",
  "paymentMeanBrand": "VISA",
  "responseCode": "00",
  "transactionDateTime": "2015-05-28T12:38:25+03:00",
  "transactionReference": "TREFEXA2015",
  "s10TransactionReference": {
    "s10TransactionId": "129306",
    "s10TransactionIdDate": "20150528"
  },
  "seal": "ef3f3cc68a39a5d1144663162a35fa6070bfe39d5abbe672b15417ff87afc431",
  "transactionPlatform": "PROD"
}

    

Function "CardValidateAuthentication" of service "checkout"

Requests for 3-D Secure validation of authentication:

In this document, unless otherwise stated, any reference to 3-D Secure includes Visa (Verified by Visa), MasterCard (SecureCode) and American Express (SafeKey).

This request is mandatory to check the complete 3-D Secure authentication (with PARes message). It must be called after you received the POST form from the ACS (Access Control Server) (See "Post form to the ACS").

This method is mainly used for control purposes of the card holder before saving the card in a wallet.

The URL is : https://office-server.sips-atos.com /rs-services/v2/checkout/cardValidateAuthentication

cardValidateAuthentication request format

Field Presence As of Version Comments
interfaceVersion Mandatory WS_2.0 The recommended value is IR_WS_ 2.32 in order to take advantage of the latest features
messageVersion Mandatory WS_2.0 Must be identical to the messageVersion field received from cardCheckEnrollment or walletCheckEnrollment method
merchantId Mandatory WS_2.0
redirectionData Mandatory WS_2.0
paResMessage Conditional WS_2.0 Mandatory if an authentification validation operation must be done on your card, do not fill this field only if you would like to attempt a 'CardValidateAuthenAndOrder' operation with a not-enrolled card. If you fill it, use 'PARes' field returned by the customer bank ACS when the card enrollment has been checked with application of standard encoding 'Url Encode'.
transactionReference Conditional WS_2.0 Mandatory if you do not use the s10TransactionReference, depending on your merchant configuration
s10TransactionReference Conditional WS_2.0 Mandatory if you do not use the transactionReference, depending on your merchant configuration. See the Containers part
intermediateServiceProviderId Optional WS_2.12
seal Mandatory WS_2.0
keyVersion Mandatory WS_2.0
sealAlgorithm Optional WS_2.12

Example of request for cardValidateAuthentication

      {
  "interfaceVersion": "IR_WS_2.9",
  "keyVersion": "1",
  "merchantId": "011223344550000",
  "messageVersion": "0.1",
  "paResMessage": "eJydVVuTqjgQ....7h%2FwH0CKem",
  "redirectionData": "uqjeV+KegCSM0POI...CjVUfxqyFq7zSYus7E\u003d",
  "transactionReference": "TREFEXA2015",
  "seal": "9565b71cb583f025278de91940c69900dee72d91e8184ddb6547f00927597fd1"
}

    

cardValidateAuthentication response format

Field As of Version Comments
responseCode WS_2.0
holderAuthentResponseCode WS_2.0
seal WS_2.0
errorFieldName WS_2.21
holderAuthentStatus WS_2.27
holderAuthentMethod WS_2.27
holderAuthentProgram WS_2.27
threeD WS_2.27 See the Containers part
threeDV2 WS_2.27 See the Containers part

Example of response for cardValidateAuthentication

      {
  "responseCode": "00",
  "holderAuthentResponseCode": "00",
  "seal": "ef3f3cc68a39a5d1144663162a35fa6070bfe39d5abbe672b15417ff87afc431"
}

    

Function "CreditHolder" of service "cashManagement"

This function allows the merchant who has the banking data of their clients to credit their account without any prior transaction.

Note : please read the set-up guide ('cash management > credit holder' section), to find out in which cases you can perform a credit holder operation.

The URL is : https://office-server.sips-atos.com /rs-services/v2/cashManagement/creditHolder

creditHolder request format

Field Presence As of Version Comments
amount Mandatory WS_2.0
cardEffectiveDate Optional WS_2.0
cardExpiryDate Mandatory WS_2.0
cardNumber Mandatory WS_2.0
cardScheme Optional WS_2.0
cardSeqNumber Optional WS_2.0
currencyCode Mandatory WS_2.0
customerEmail Optional WS_2.0
customerId Optional WS_2.0
customerIpAddress Optional WS_2.0
interfaceVersion Mandatory WS_2.0 The recommended value is CR_WS_ 2.32 in order to take advantage of the latest features
merchantId Mandatory WS_2.0
orderChannel Optional WS_2.0
orderId Optional WS_2.0
returnContext Optional WS_2.0
transactionOrigin Optional WS_2.0
transactionReference Conditional WS_2.0 Mandatory if you do not use the s10TransactionReference, depending on your merchant configuration
panType Optional WS_2.1
s10TransactionReference Conditional WS_2.6 Mandatory if you do not use the transactionReference, depending on your merchant configuration. See the Containers part
intermediateServiceProviderId Optional WS_2.12
seal Mandatory WS_2.0
keyVersion Mandatory WS_2.0
sealAlgorithm Optional WS_2.12
subMerchantId Optional WS_2.14
subMerchantShortName Optional WS_2.14
subMerchantCategoryCode Optional WS_2.14
subMerchantLegalId Optional WS_2.14
subMerchantAddress Optional WS_2.14 See the Containers part
statementReference Optional WS_2.19

Example of request for creditHolder

      {
  "amount": "1000",
  "cardExpiryDate": "201602",
  "cardNumber": "1234123412341234",
  "currencyCode": "978",
  "keyVersion": "1",
  "interfaceVersion": "CR_WS_2.9",
  "merchantId": "011223344550000",
  "orderChannel": "INTERNET",
  "orderId": "1234",
  "transactionReference": "TREFEXA2015",
  "seal": "607083393a51b4b23261270df83c28a61e06f74928bc1e868c0abb9325dde2f2"
}

    

creditHolder response format

Field As of Version Comments
acquirerResponseCode WS_2.0
authorisationId WS_2.0
maskedPan WS_2.0
newStatus WS_2.0
operationDateTime WS_2.0
responseCode WS_2.0
s10TransactionReference WS_2.6 See the Containers part
transactionReference WS_2.6
transactionPlatform WS_2.17 Always filled with « PROD »
errorFieldName WS_2.21
seal WS_2.0

Example of response for creditHolder

      {
  "responseCode": "00",
  "holderAuthentResponseCode": "00",
  "seal": "ef3f3cc68a39a5d1144663162a35fa6070bfe39d5abbe672b15417ff87afc431"
}

    

Function "WalletOrder" of service "checkout"

Requests for payment orders via electronic wallets include the following elements:

The URL is : https://office-server.sips-atos.com /rs-services/v2/checkout/walletOrder

walletOrder request format

Field Presence As of Version Comments
amount Mandatory WS_2.0
captureDay Optional WS_2.0
captureMode Optional WS_2.0
currencyCode Mandatory WS_2.0
customerId Optional WS_2.0
customerIpAddress Optional WS_2.0
fraudData Optional WS_2.0 See the Containers part
merchantId Mandatory WS_2.0
merchantWalletId Mandatory WS_2.0
merchantTransactionDateTime Optional WS_2.0
orderChannel Mandatory WS_2.0
orderId Optional WS_2.0
paymentMeanId Mandatory WS_2.0
interfaceVersion Mandatory WS_2.0 The recommended value is IR_WS_ 2.32 in order to take advantage of the latest features
returnContext Optional WS_2.0
transactionReference Conditional WS_2.0 Mandatory if you do not use the s10TransactionReference, depending on your merchant configuration
transactionOrigin Optional WS_2.0
billingAddress Optional WS_2.0 See the Containers part
billingContact Optional WS_2.0 See the Containers part
customerAddress Optional WS_2.0 See the Containers part
customerContact Optional WS_2.0 See the Containers part
deliveryAddress Optional WS_2.0 See the Containers part
deliveryContact Optional WS_2.0 See the Containers part
deliveryData Optional WS_2.19 See the Containers part
customerData Optional WS_2.1 See the Containers part
invoiceReference Optional WS_2.0
statementReference Optional WS_2.2
paymentPattern Conditional WS_2.3 This field is mandatory for certain payment means. Please refer to the respective payment mean implementation guide for details
cardCSCValue Optional WS_2.3
cscType Optional WS_2.32
holderAddress Optional WS_2.0 See the Containers part
holderContact Optional WS_2.0 See the Containers part
authenticationData Optional WS_2.0 See the Containers part
s10TransactionReference Conditional WS_2.6 Mandatory if you do not use the transactionReference, depending on your merchant configuration. See the Containers part
intermediateServiceProviderId Optional WS_2.12
seal Mandatory WS_2.0
keyVersion Mandatory WS_2.0
sealAlgorithm Optional WS_2.12
customerLanguage Optional WS_2.15
orderContext Optional WS_2.19 See the Containers part
travelContext Optional WS_2.19 See the Containers part
paymentMeanData Optional WS_2.17 See the Containers part
holderData Optional WS_2.17 See the Containers part
shoppingCartDetail Optional WS_2.19 See the Containers part

Example of request for walletOrder

      {
  "amount": "2500",
  "captureDay": "0",
  "captureMode": "AUTHOR_CAPTURE",
  "currencyCode": "978",
  "customerIpAddress": "127.0.0.1",
  "interfaceVersion": "IR_WS_2.3",
  "invoiceReference": "FAC007NB",
  "keyVersion": "1",
  "merchantId": "011223344550000",
  "merchantTransactionDateTime": "2014-01-10T17:13:30.743+01:00",
  "orderChannel": "INTERNET",
  "merchantWalletId": "WALLET01",
  "paymentMeanId": "10",
  "transactionOrigin": "SO_WEBAPPLI",
  "transactionReference": "TREFEXA2012",
  "seal": "5bb0e9fcbb3eaa28557ac41ed6ab57ab84d9edbe9fe8eb0cedd3e8548433b7cd"
}

    

walletOrder response format

Field As of Version Comments
acquirerResponseCode WS_2.0
authorisationId WS_2.0
cardScheme WS_2.0
complementaryCode WS_2.0
complementaryInfo WS_2.0
maskedPan WS_2.0
responseCode WS_2.0
returnContext WS_2.0 Value transferred to the payment request
transactionDateTime WS_2.0
tokenPan WS_2.1
scoreColor WS_2.1
scoreInfo WS_2.1
scoreProfile WS_2.1
scoreThreshold WS_2.1
scoreValue WS_2.1
s10TransactionReference WS_2.6 See the Containers part
transactionReference WS_2.6
cardData WS_2.9 See the Containers part
seal WS_2.0
preAuthorisationProfile WS_2.13
preAuthorisationProfileValue WS_2.13
preAuthorisationRuleResultList WS_2.13 List of container preAuthorisationRuleResult . See the Containers part
captureDay WS_2.15
captureMode WS_2.15
transactionPlatform WS_2.17 Always filled with « PROD »
cardCSCResultCode WS_2.17
avsPostcodeResponseCode WS_2.17
avsAddressResponseCode WS_2.17
authorMessageReference WS_2.19
authorisationTypeLabel WS_2.19
acquirerResponseMessage WS_2.20
recurringResponseCode WS_2.20
holderAuthentRelegationCode WS_2.20
holderAuthentStatus WS_2.20
guaranteeIndicator WS_2.20
acceptanceSystemApplicationId WS_2.20
errorFieldName WS_2.21
intermediateServiceProviderOperationId WS_2.24
orderId WS_2.24
schemeTransactionIdentifier WS_2.31
paymentAccountReference WS_2.31
guaranteeLimitDateTime WS_2.32

Example of response for walletOrder

      {
  "acquirerResponseCode": "00",
  "authorisationId": "123456789102",
  "cardScheme": "MASTERCARD",
  "maskedPan": "5219##########00",
  "responseCode": "00",
  "returnContext": "ReturnContext",
  "transactionDateTime": "2012-10-16T23:50:44-12:00",
  "seal": "7ca065ebba90762e3286ee16d6a2d2da0eea8bae6b46592058933881d96d0c3d",
  "transactionPlatform": "PROD"
}

    

Function "WalletIssuerWalletInitialize" of service "checkout"

Requests to initialize a one-click payment with an issuer wallets (Paylib):

This request is mandatory to obtain the redirection data and urls used to redirect to buyer into the OneClick authentication process pages for issuer wallets stored in a WL Sips wallet. If the initialization step is successful, you will receive in response a secure URL (redirectionUrl) to which the customer should be redirected to continue the one-click payment. This redirection must be made via a POST form, see the part "POST form to external suppliers". You shall also indicate in the request the URL (merchantReturnUrl) to which the customer will be redirected to at the end of the one-click payment with an external wallet. You must then call the walletIssuerWalletFinalize service to finalize the transaction.

The URL is : https://office-server.sips-atos.com /rs-services/v2/checkout/walletIssuerWalletInitialize

walletIssuerWalletInitialize request format

Field Presence As of Version Comments
merchantReturnUrl Mandatory WS_2.0
merchantId Mandatory WS_2.0
transactionReference Conditional WS_2.0 Mandatory if you do not use the s10TransactionReference, depending on your merchant configuration
interfaceVersion Mandatory WS_2.0 The recommended value is IR_WS_ 2.32 in order to take advantage of the latest features
amount Mandatory WS_2.0
currencyCode Mandatory WS_2.0
captureMode Optional WS_2.0
captureDay Optional WS_2.0
orderChannel Mandatory WS_2.0
orderId Optional WS_2.0
paymentPattern Optional WS_2.0 This field is mandatory for certain payment means. Please refer to the respective payment mean implementation guide for details
customerId Optional WS_2.0
customerIpAddress Optional WS_2.0
customerLanguage Optional WS_2.0
transactionOrigin Optional WS_2.0
returnContext Optional WS_2.0
statementReference Optional WS_2.0
invoiceReference Optional WS_2.0
merchantTransactionDateTime Optional WS_2.0
authenticationData Optional WS_2.0 See the Containers part
deliveryContact Optional WS_2.0 See the Containers part
deliveryAddress Optional WS_2.0 See the Containers part
customerContact Optional WS_2.0 See the Containers part
customerAddress Optional WS_2.0 See the Containers part
billingContact Optional WS_2.0 See the Containers part
billingAddress Optional WS_2.0 See the Containers part
holderAddress Optional WS_2.0 See the Containers part
holderContact Optional WS_2.0 See the Containers part
holderData Optional WS_2.0 See the Containers part
customerData Optional WS_2.0 See the Containers part
fraudData Optional WS_2.0 See the Containers part
deliveryData Optional WS_2.0 See the Containers part
shoppingCartDetail Optional WS_2.0 See the Containers part
s10TransactionReference Conditional WS_2.0 Mandatory if you do not use the transactionReference, depending on your merchant configuration. See the Containers part
responseKeyVersion Optional WS_2.0
intermediateServiceProviderId Optional WS_2.0
seal Mandatory WS_2.0
keyVersion Mandatory WS_2.0
sealAlgorithm Optional WS_2.0
travelContext Optional WS_2.0 See the Containers part
orderContext Optional WS_2.0 See the Containers part
merchantWalletId Mandatory WS_2.0
paymentMeanId Mandatory WS_2.0

Example of request for walletIssuerWalletInitialize

      {
  "amount": "1000",
  "captureMode": "AUTHOR_CAPTURE",
  "currencyCode": "978",
  "customerIpAddress": "127.0.0.1",
  "interfaceVersion": "IR_WS_2.3",
  "keyVersion": "1",
  "merchantId": "023101122334455",
  "merchantReturnUrl": "http://www.yoursiteweb.com",
  "merchantTransactionDateTime": "2014-07-11T10:59:57.723+02:00",
  "orderChannel": "INTERNET",
  "paymentMeanBrand": "PAYLIB",
  " transactionReference": "TREFEXA2012",
  "merchantWalletId":"12",
  "seal": " 95e479c276d71a07c655f3c2db1bb8b483c0921e544d4af4cff3e220b04eb551"
}


    

walletIssuerWalletInitialize response format

Field As of Version Comments
responseCode WS_2.0
redirectionUrl WS_2.0
redirectionData WS_2.0
messageVersion WS_2.0
paymentProviderSessionId WS_2.0
seal WS_2.0
errorFieldName WS_2.0
issuerWalletType WS_2.0

Example of response for walletIssuerWalletInitialize

      {
  "responseCode": "00",
  "redirectionUrl": "https://private-payment.dev-agile.qlf.sips.priv.atos.fr/paylib/FrontController",
  "redirectionData": "RSs7cZyL1DqsVso",
  "messageVersion": "0.1",
  "seal": "79cf30535e08b8c6c9cfdd55c343845947f8fea892ec0ea1db96378055f71de6"
}


    

Function "WalletIssuerWalletFinalize" of service "checkout"

Requests for wallet payment finalization for external wallets.

This request is mandatory to know the result of the wallet payment order with an external wallet. It must be called after you received the POST form from the external wallet through the merchantReturnUrl (see walletIssuerWalletInitialize request).

The URL is : https://office-server.sips-atos.com /rs-services/v2/checkout/walletIssuerWalletFinalize

walletIssuerWalletFinalize request format

Field Presence As of Version Comments
merchantId Mandatory WS_2.0
transactionReference Conditional WS_2.0 Mandatory if you do not use the s10TransactionReference, depending on your merchant configuration
interfaceVersion Mandatory WS_2.0 The recommended value is IR_WS_ 2.32 in order to take advantage of the latest features
redirectionData Mandatory WS_2.0
messageVersion Mandatory WS_2.0
s10TransactionReference Conditional WS_2.0 Mandatory if you do not use the transactionReference, depending on your merchant configuration. See the Containers part
intermediateServiceProviderId Optional WS_2.0
seal Mandatory WS_2.0
keyVersion Mandatory WS_2.0
sealAlgorithm Optional WS_2.0

Example of request for walletIssuerWalletFinalize

      {
  "interfaceVersion": "IR_WS_2.23",
  "keyVersion": "1",
  "merchantId": "011223344550000",
  "messageVersion": "0.1",
  "redirectionData": " RSs7cZyL1DqsVso ",
  "transactionReference": "TREFEXA2012",
  "seal": "30218c85ca303d33d5e7b60bb48222b9826fbc30b6c2ec98fff285702e445ae1"
}


    

walletIssuerWalletFinalize response format

Field As of Version Comments
merchantId WS_2.0
transactionReference WS_2.0
amount WS_2.0
currencyCode WS_2.0
captureMode WS_2.0
captureDay WS_2.0
orderChannel WS_2.0
paymentPattern WS_2.0
customerId WS_2.0
customerIpAddress WS_2.0
returnContext WS_2.0
statementReference WS_2.0
invoiceReference WS_2.0
merchantTransactionDateTime WS_2.0
acquirerResponseCode WS_2.0
avsPostcodeResponseCode WS_2.0
avsAddressResponseCode WS_2.0
authorisationId WS_2.0
guaranteeIndicator WS_2.0
transactionStatus WS_2.0
panEntryMode WS_2.0
paymentMeanBrand WS_2.0
maskedPan WS_2.0
cardExpiryDate WS_2.0
cardCSCResultCode WS_2.0
walletType WS_2.0
transactionDateTime WS_2.0
holderAuthentMethod WS_2.0
holderAuthentStatus WS_2.0
holderAuthentProgram WS_2.0
scoreColor WS_2.0
scoreInfo WS_2.0
scoreProfile WS_2.0
scoreThreshold WS_2.0
scoreValue WS_2.0
complementaryCode WS_2.0
complementaryInfo WS_2.0
responseCode WS_2.0
issuerWalletInformation WS_2.0
s10TransactionReference WS_2.0 See the Containers part
orderId WS_2.0
acquirerResponseMessage WS_2.0
cardData WS_2.0 See the Containers part
acquirerNativeResponseCode WS_2.0
acquirerResponseIdentifier WS_2.0
seal WS_2.0
preAuthorisationProfile WS_2.0
preAuthorisationProfileValue WS_2.0
preAuthorisationRuleResultList WS_2.0 List of container preAuthorisationRuleResult . See the Containers part
transactionPlatform WS_2.0 Always filled with « PROD »
errorFieldName WS_2.0
issuerWalletId WS_2.0
intermediateServiceProviderOperationId WS_2.24

Example of response for walletIssuerWalletFinalize

      {
  "responseCode": "00",
  "captureDay": "0",
  "currencyCode": "978",
  "merchantId": "011223344550000",
  "paymentPattern": "ONE_SHOT",
  "transactionAmount": "200",
  "transactionDateTime": "2014-01-14T08:38:11.494+01:00",
  "transactionReference": "TREFEXA2012",
  "seal": "79cf30535e08b8c6c9cfdd55c343845947f8fea892ec0ea1db96378055f71de6",
  "transactionPlatform": "PROD"
}

    

Function "WalletCreditHolder" of service "cashManagement"

This function allows the merchant who has the wallet data of their clients to credit their account without any prior transaction.

The URL is : https://office-server.sips-atos.com /rs-services/v2/cashManagement/walletCreditHolder

walletCreditHolder request format

Field Presence As of Version Comments
amount Mandatory WS_2.0
currencyCode Mandatory WS_2.0
customerEmail Optional WS_2.0
customerId Optional WS_2.0
customerIpAddress Optional WS_2.0
interfaceVersion Mandatory WS_2.0 The recommended value is CR_WS_ 2.32 in order to take advantage of the latest features
merchantId Mandatory WS_2.0
merchantWalletId Mandatory WS_2.0
paymentMeanId Mandatory WS_2.0
orderChannel Optional WS_2.0
orderId Optional WS_2.0
returnContext Optional WS_2.0
transactionOrigin Optional WS_2.0
transactionReference Conditional WS_2.0 Mandatory if you do not use the s10TransactionReference, depending on your merchant configuration
s10TransactionReference Conditional WS_2.6 Mandatory if you do not use the transactionReference, depending on your merchant configuration. See the Containers part
intermediateServiceProviderId Optional WS_2.12
seal Mandatory WS_2.0
keyVersion Mandatory WS_2.0
sealAlgorithm Optional WS_2.12
statementReference Optional WS_2.19

Example of request for walletCreditHolder

      {
  "amount": "1000",
  "currencyCode": "978",
  "customerEmail": "toto@mail.fr",
  "customerId": "customerId1",
  "customerIpAddress": "127.0.0.1",
  "interfaceVersion": "CR_WS_2.6",
  "keyVersion": "1",
  "merchantId": "011223344550000",
  "merchantWalletId": "SIM01",
  "orderChannel": "INTERNET",
  "orderId": "123",
  "paymentMeanId": "2",
  "returnContext": "my return context",
  "transactionOrigin": "SIPS-SIM",
  "transactionReference": "SIM2014012248339",
  "seal": "d3f5f2c4c6f608e3a4940c6700ca6827c066715512be835660a8091c6ec1e098"
}

    

walletCreditHolder response format

Field As of Version Comments
acquirerResponseCode WS_2.0
authorisationId WS_2.0
maskedPan WS_2.0
newStatus WS_2.0
operationDateTime WS_2.0
responseCode WS_2.0
s10TransactionReference WS_2.6 See the Containers part
transactionReference WS_2.0
paymentMeanBrand WS_2.0
transactionPlatform WS_2.17 Always filled with « PROD »
seal WS_2.0
errorFieldName WS_2.21

Example of response for walletCreditHolder

      {
  "maskedPan": "4907##########00",
  "newStatus": "TO_CREDIT",
  "operationDateTime": "2015-05-06T12:12:07+03:00",
  "responseCode": "00",
  "s10TransactionReference": {
    "s10TransactionId": "34800",
    "s10TransactionIdDate": "20150506"
  },
  "transactionReference": "SIM2014012248339",
  "paymentMeanBrand": "VISA",
  "seal": "250c2a5831ae3b1a015d4d8be0e1970936e2c53b50607c8f6182556c0291ab8d",
  "transactionPlatform": "PROD"
}

    

Function "PaymentProviderInitialize" of service "checkout"

Requests for payment initialization for external wallets.

/>This request initializes a session for an external wallet order. For a non-mobile transaction, if the initialization step is successful, you will receive in response a secure URL (redirectionUrl) to which the customer should be redirected to continue the payment order. This redirection must be made via a POST form, see the part "POST form to external suppliers". In the request, you shall also indicate the URL (merchantReturnUrl) to which the customer will be redirected to at the end of the external wallet payment. You must then call the paymentProviderFinalize service to finalize the transaction.

The URL is : https://office-server.sips-atos.com /rs-services/v2/checkout/paymentProviderInitialize

paymentProviderInitialize request format

Field Presence As of Version Comments
paymentMeanBrand Mandatory WS_2.0
merchantReturnUrl Mandatory WS_2.0
merchantId Mandatory WS_2.0
transactionReference Conditional WS_2.0 Mandatory if you do not use the s10TransactionReference, depending on your merchant configuration
interfaceVersion Mandatory WS_2.0 The recommended value is IR_WS_ 2.32 in order to take advantage of the latest features
amount Mandatory WS_2.0
currencyCode Mandatory WS_2.0
captureMode Optional WS_2.0
captureDay Optional WS_2.0
orderChannel Mandatory WS_2.0
orderId Optional WS_2.0
paymentPattern Conditional WS_2.0 This field is mandatory for certain payment means. Please refer to the respective payment mean implementation guide for details
customerId Optional WS_2.0
customerIpAddress Optional WS_2.0
customerLanguage Optional WS_2.0
transactionOrigin Optional WS_2.0
returnContext Optional WS_2.0
statementReference Optional WS_2.0
invoiceReference Optional WS_2.0
merchantTransactionDateTime Optional WS_2.0
authenticationData Optional WS_2.0 See the Containers part
deliveryContact Optional WS_2.0 See the Containers part
deliveryAddress Optional WS_2.0 See the Containers part
customerContact Optional WS_2.0 See the Containers part
customerAddress Optional WS_2.0 See the Containers part
billingContact Optional WS_2.0 See the Containers part
billingAddress Optional WS_2.0 See the Containers part
holderAddress Optional WS_2.0 See the Containers part
holderContact Optional WS_2.0 See the Containers part
holderData Optional WS_2.19 See the Containers part
customerData Optional WS_2.0 See the Containers part
fraudData Optional WS_2.0 See the Containers part
deliveryData Optional WS_2.6 See the Containers part
shoppingCartDetail Optional WS_2.6 See the Containers part
s10TransactionReference Conditional WS_2.6 Mandatory if you do not use the transactionReference, depending on your merchant configuration. See the Containers part
responseKeyVersion Optional WS_2.7
paymentMeanData Optional WS_2.10 See the Containers part
intermediateServiceProviderId Optional WS_2.12
seal Mandatory WS_2.0
keyVersion Mandatory WS_2.0
sealAlgorithm Optional WS_2.12
travelContext Optional WS_2.19 See the Containers part
orderContext Optional WS_2.19 See the Containers part

Example of request for paymentProviderInitialize

      {
  "amount": "1000",
  "captureMode": "AUTHOR_CAPTURE",
  "currencyCode": "978",
  "customerIpAddress": "127.0.0.1",
  "interfaceVersion": "IR_WS_2.3",
  "keyVersion": "1",
  "merchantId": "023101122334455",
  "merchantReturnUrl": "http://www.yoursiteweb.com",
  "merchantTransactionDateTime": "2014-07-11T10:59:57.723+02:00",
  "orderChannel": "INTERNET",
  "paymentMeanBrand": "PAYLIB",
  " transactionReference": "TREFEXA2012",
  "seal": " 95e479c276d71a07c655f3c2db1bb8b483c0921e544d4af4cff3e220b04eb551"
}

    

paymentProviderInitialize response format

Field As of Version Comments
responseCode WS_2.0
redirectionUrl WS_2.0
redirectionData WS_2.0
messageVersion WS_2.0
paymentProviderSessionId WS_2.1
outerRedirectionUrl WS_2.9
acquirerNativeResponseCode WS_2.10
acquirerResponseIdentifier WS_2.10
acquirerResponseMessage WS_2.10
seal WS_2.0
errorFieldName WS_2.21

Example of response for paymentProviderInitialize

      {
  "responseCode": "00",
  "redirectionUrl": "https://payment.sips.atos.fr/paymentprovider/init",
  "redirectionData": "RSs7cZyL1DqsVso",
  "messageVersion": "0.1",
  "seal": "79cf30535e08b8c6c9cfdd55c343845947f8fea892ec0ea1db96378055f71de6"
}

    

Function "PaymentProviderGetContext" of service "checkout"

This request is optional and allow you to know the identity of the payer and his shipping address in order to display them before the confirmation of transaction of a PayPal transaction.

This function is only available for the payment mean PayPal.

The URL is : https://office-server.sips-atos.com /rs-services/v2/checkout/paymentProviderGetContext

paymentProviderGetContext request format

Field Presence As of Version Comments
merchantId Mandatory WS_2.0
transactionReference Conditional WS_2.0 Mandatory if you do not use the s10TransactionReference, depending on your merchant configuration
interfaceVersion Mandatory WS_2.0 The recommended value is IR_WS_ 2.32 in order to take advantage of the latest features
redirectionData Mandatory WS_2.0
messageVersion Mandatory WS_2.0
s10TransactionReference Conditional WS_2.0 Mandatory if you do not use the transactionReference, depending on your merchant configuration. See the Containers part
intermediateServiceProviderId Optional WS_1.2
seal Mandatory WS_2.0
keyVersion Mandatory WS_2.0
sealAlgorithm Optional WS_2.12

Example of request for paymentProviderGetContext

      {
  "interfaceVersion": "IR_WS_2.0",
  "keyVersion": "1",
  "merchantId": "011223344550000",
  "messageVersion": "0.1",
  "redirectionData": "RSs7cZy...L1DqsVso",
  "transactionReference": "TREFEXA2012",
  "seal": "30218c85ca303d33d5e7b60bb48222b9826fbc30b6c2ec98fff285702e445ae1"
}

    

paymentProviderGetContext response format

Field As of Version Comments
responseCode WS_2.0
deliveryAddress WS_2.0 See the Containers part
deliveryContact WS_2.0 See the Containers part
customerAddress WS_2.0 See the Containers part
customerContact WS_2.0 See the Containers part
paymentMeanData WS_2.0 See the Containers part
acquirerNativeResponseCode WS_2.0
acquirerResponseMessage WS_2.0
acquirerResponseIdentifier WS_2.0
seal WS_2.0
holderAddress WS_2.0 See the Containers part
errorFieldName WS_2.21

Example of response for paymentProviderGetContext

      {
  "responseCode": "00",
  "deliveryAddress": {
    "addressAdditional1": "devliveryAdd11",
    "city": "Blois",
    "country": "FR",
    "street": "Street",
    "zipCode": "41000"
  },
  "deliveryContact": {
    "email": "team@email.com",
    "firstname": "Team",
    "lastname": "John",
    "phone": "0254440000"
  },
  "customerAddress": {
    "addressAdditional1": "devliveryAdd11",
    "city": "Blois",
    "country": "FR",
    "street": "Street",
    "zipCode": "41000"
  },
  "customerContact": {
    "firstname": "Team",
    "lastname": "BO",
    "phone": "0254440000"
  },
  "paymentMeanData": {
    "paypal": {
      "token": "EC-4S931937D5977923H",
      "deliveryAddressStatus": "Confirmed",
      "payerId": "H3G7GWRLLSBDY",
      "payerStatus": "verified",
      "paymentStatus": "PaymentActionNotInitiated"
    }
  },
  "acquirerResponseMessage": "Process succeeded",
  "acquirerResponseIdentifier": "419d14fb8a5c",
  "seal": "18509963c41e3102967ee0ebc149165032b1b53cffec29f46d29ab37d8bc1df4"
}

    

Function "PaymentProviderFinalize" of service "checkout"

Requests for payment finalization for external wallets.

/>This request is mandatory to know the result of the payment order with an external wallet. It must be called after you received the POST form from the external wallet through the merchantReturnUrl (see paymentProviderInitialize request).

The URL is : https://office-server.sips-atos.com /rs-services/v2/checkout/paymentProviderFinalize

paymentProviderFinalize request format

Field Presence As of Version Comments
merchantId Mandatory WS_2.0
transactionReference Conditional WS_2.0 Mandatory if you do not use the s10TransactionReference, depending on your merchant configuration
interfaceVersion Mandatory WS_2.0 The recommended value is IR_WS_ 2.32 in order to take advantage of the latest features
redirectionData Mandatory WS_2.0
messageVersion Mandatory WS_2.0
s10TransactionReference Conditional WS_2.6 Mandatory if you do not use the transactionReference, depending on your merchant configuration. See the Containers part
intermediateServiceProviderId Optional WS_2.12
seal Mandatory WS_2.0
keyVersion Mandatory WS_2.0
sealAlgorithm Optional WS_2.12

Example of request for paymentProviderFinalize

      {
  "interfaceVersion": "IR_WS_2.0",
  "keyVersion": "1",
  "merchantId": "011223344550000",
  "messageVersion": "0.1",
  "redirectionData": " RSs7cZyL1DqsVso ",
  "transactionReference": "TREFEXA2012",
  "seal": "30218c85ca303d33d5e7b60bb48222b9826fbc30b6c2ec98fff285702e445ae1"
}

    

paymentProviderFinalize response format

Field As of Version Comments
merchantId WS_2.0
transactionReference WS_2.0
amount WS_2.0
currencyCode WS_2.0
captureMode WS_2.0
captureDay WS_2.0
orderChannel WS_2.0
paymentPattern WS_2.0
customerId WS_2.0
customerIpAddress WS_2.0
returnContext WS_2.0
statementReference WS_2.0
invoiceReference WS_2.0
merchantTransactionDateTime WS_2.0
acquirerResponseCode WS_2.0
avsPostcodeResponseCode WS_2.0
avsAddressResponseCode WS_2.0
authorisationId WS_2.0
guaranteeIndicator WS_2.0
transactionStatus WS_2.0
panEntryMode WS_2.0
paymentMeanBrand WS_2.0
maskedPan WS_2.0
cardExpiryDate WS_2.0
cardCSCResultCode WS_2.0
walletType WS_2.0
transactionDateTime WS_2.0
holderAuthentMethod WS_2.0
holderAuthentStatus WS_2.0
holderAuthentProgram WS_2.0
scoreColor WS_2.0
scoreInfo WS_2.0
scoreProfile WS_2.0
scoreThreshold WS_2.0
scoreValue WS_2.0
complementaryCode WS_2.0
complementaryInfo WS_2.0
responseCode WS_2.0
issuerWalletInformation WS_2.6
s10TransactionReference WS_2.6 See the Containers part
orderId WS_2.6
acquirerResponseMessage WS_2.6
cardData WS_2.9 See the Containers part
acquirerNativeResponseCode WS_2.10
acquirerResponseIdentifier WS_2.10
seal WS_2.0
preAuthorisationProfile WS_2.13
preAuthorisationProfileValue WS_2.13
preAuthorisationRuleResultList WS_2.13 List of container preAuthorisationRuleResult . See the Containers part
transactionPlatform WS_2.17 Always filled with « PROD »
errorFieldName WS_2.21
issuerWalletId WS_2.23
intermediateServiceProviderOperationId WS_2.24

Example of response for paymentProviderFinalize

      {
  "responseCode": "00",
  "captureDay": "0",
  "currencyCode": "978",
  "merchantId": "011223344550000",
  "paymentPattern": "ONE_SHOT",
  "transactionAmount": "200",
  "transactionDateTime": "2014-01-14T08:38:11.494+01:00",
  "transactionReference": "TREFEXA2012",
  "seal": "79cf30535e08b8c6c9cfdd55c343845947f8fea892ec0ea1db96378055f71de6",
  "transactionPlatform": "PROD"
}

    

Function "DirectDebitOrder" of service "checkout"

This function allows you, if you have the bank information of a customer, to make payments by direct debit (SDD and ELV).

The URL is : https://office-server.sips-atos.com /rs-services/v2/checkout/directDebitOrder

directDebitOrder request format

Field Presence As of Version Comments
amount Mandatory WS_2.0
captureDay Optional WS_2.0
captureMode Optional WS_2.0
currencyCode Mandatory WS_2.0
customerId Optional WS_2.0
customerIpAddress Optional WS_2.0
interfaceVersion Mandatory WS_2.0 The recommended value is IR_WS_ 2.32 in order to take advantage of the latest features
invoiceReference Optional WS_2.0
merchantId Mandatory WS_2.0
merchantTransactionDateTime Optional WS_2.0
orderChannel Mandatory WS_2.0
orderId Optional WS_2.0
returnContext Optional WS_2.0
transactionReference Conditional WS_2.0 Mandatory if you do not use the s10TransactionReference, depending on your merchant configuration
transactionOrigin Optional WS_2.0
statementReference Optional WS_2.0
paymentMeanBrand Mandatory WS_2.0
customerBankCode Optional WS_2.5
customerAccount Optional WS_2.5
customerBankAccountType Optional WS_2.5
billingContact Optional WS_2.0 See the Containers part
billingAddress Optional WS_2.0 See the Containers part
customerContact Optional WS_2.0 See the Containers part
customerAddress Optional WS_2.0 See the Containers part
deliveryContact Optional WS_2.0 See the Containers part
deliveryAddress Optional WS_2.0 See the Containers part
customerData Optional WS_2.0 See the Containers part
fraudData Optional WS_2.0 See the Containers part
holderContact Optional WS_2.0 See the Containers part
holderAddress Optional WS_2.0 See the Containers part
paymentPattern Conditional WS_2.0 This field is mandatory for certain payment means. Please refer to the respective payment mean implementation guide for details
instalmentData Optional WS_2.0 See the Containers part
mandateAuthentMethod Optional WS_2.0
mandateUsage Optional WS_2.0
mandateId Conditional WS_2.0
creditorId Optional WS_2.0
valueDate Optional WS_2.0
s10TransactionReference Conditional WS_2.6 Mandatory if you do not use the transactionReference, depending on your merchant configuration. See the Containers part
riskManagementCustomDataList Optional WS_2.8 List of container riskManagementCustomData . See the Containers part
shoppingCartDetail Optional WS_2.8 See the Containers part
intermediateServiceProviderId Optional WS_2.12
seal Mandatory WS_2.0
keyVersion Mandatory WS_2.0
sealAlgorithm Optional WS_2.12

Example of request for directDebitOrder

      {
  "amount": "2500",
  "captureDay": "0",
  "captureMode": "AUTHOR_CAPTURE",
  "cardCSCValue": "0000",
  "currencyCode": "978",
  "customerBankAccountType": "BIC_IBAN",
  "interfaceVersion": " IR_WS_2.3",
  "keyVersion": "1",
  "mandateId": "000000000000001999",
  "merchantId": "011223344550000",
  "orderChannel": "INTERNET",
  "orderId": " ORD101",
  "paymentMeanBrand": "SEPA_DIRECT_DEBIT",
  "returnContext": "ReturnContext",
  "transactionOrigin": " SO_WEBAPPLI",
  "transactionReference": "TREFEXA2012",
  "seal": "2205f0636dc500c4f3ef536075895b8baba3a60c7087e06cd9d330c50a50c53e"
}

    

directDebitOrder response format

Field As of Version Comments
authorisationId WS_2.0
acquirerResponseCode WS_2.0
complementaryCode WS_2.0
complementaryInfo WS_2.0
responseCode WS_2.0
errorFieldName WS_2.5
transactionDateTime WS_2.0
guaranteeIndicator WS_2.0
holderAuthentRelegationCode WS_2.0
holderAuthentStatus WS_2.0
scoreColor WS_2.0
scoreInfo WS_2.0
scoreProfile WS_2.0
scoreThreshold WS_2.0
scoreValue WS_2.0
maskedPan WS_2.0
captureLimitDate WS_2.0
transactionActors WS_2.0
mandateId WS_2.5
creditorId WS_2.5
valueDate WS_2.5
s10TransactionReference WS_2.6 See the Containers part
transactionReference WS_2.6
seal WS_2.0
preAuthorisationProfile WS_2.13
preAuthorisationProfileValue WS_2.13
preAuthorisationRuleResultList WS_2.13 List of container preAuthorisationRuleResult . See the Containers part
captureDay WS_2.15
captureMode WS_2.15
transactionPlatform WS_2.17 Always filled with « PROD »
intermediateServiceProviderOperationId WS_2.24
orderId WS_2.24
secureReference WS_2.26

Example of response for directDebitOrder

      {
  "acquirerResponseCode": "00",
  "authorisationId": "123456789102",
  "maskedPan": "5219##########00",
  "responseCode": "00",
  "transactionDateTime": "2012-10-16T23:50:44-12:00",
  "captureLimitDate": "2012-11-16T23:50:44-12:00",
  "transactionActors": "BTOB",
  "seal": "7ca065ebba90762e3286ee16d6a2d2da0eea8bae6b46592058933881d96d0c3d",
  "transactionPlatform": "PROD"
}

    

Function "CreditTransferInquire" of service "checkout"

Requests to retrieve the list of issuer’s bank available:

This service is currently available for the payment means iDEAL.

This request provides a list of issuer’s banks. If the request is successful, you will receive in response a list of bank with their name and code. This information must be use for the initialization step (CreditTransferInitialize).

The URL is : https://office-server.sips-atos.com /rs-services/v2/checkout/creditTransferInquire

creditTransferInquire request format

Field Presence As of Version Comments
currencyCode Mandatory WS_2.0
customerLanguage Optional WS_2.0
interfaceVersion Mandatory WS_2.0 The recommended value is IR_WS_ 2.32 in order to take advantage of the latest features
merchantId Mandatory WS_2.0
paymentMeanBrand Mandatory WS_2.0
transactionReference Conditional WS_2.0 Mandatory if you do not use the s10TransactionReference, depending on your merchant configuration
s10TransactionReference Conditional WS_2.0 Mandatory if you do not use the transactionReference, depending on your merchant configuration. See the Containers part
intermediateServiceProviderId Optional WS_2.12
seal Mandatory WS_2.0
keyVersion Mandatory WS_2.0
sealAlgorithm Optional WS_2.12

Example of request for creditTransferInquire

      {
  "currencyCode": "978",
  "customerLanguage": "fr",
  "interfaceVersion": "IR_WS_2.9",
  "keyVersion": "1",
  "merchantId": "011223344550000",
  "paymentMeanBrand": "IDEAL",
  "transactionReference": " TREFEXA2015",
  "seal": "ec7be3e2a0086a86f66f74bb6e10f244e51e4e648c7dbbf7c89ce9aa78a569cf"
}

    

creditTransferInquire response format

Field As of Version Comments
customerBankList WS_2.0 List of container customerBank . See the Containers part
errorFieldName WS_2.0
responseCode WS_2.0
seal WS_2.0

Example of response for creditTransferInquire

      {
  "customerBankList": [
    {
      "customerBankCode": "RABONL2U",
      "customerBankName": "BANK - RABO"
    },
    {
      "customerBankCode": "INGBNL2A",
      "customerBankName": "BANK - ING"
    }
  ],
  "responseCode": "00",
  "seal": "c46465d780517ce593b4bd5afe789fe58d2bc972937aaa35707ec8668265e6dc"
}

    

Function "CreditTransferInitialize" of service "checkout"

This service is currently available for the payment means iDEAL and Sofortüberweisung.

This request initializes a session for a bank transfer. If the initialization step is successful, you will receive in response a secure URL (redirectionUrl) to which the customer should be redirected to continue the bank transfer. This redirection must be made via a POST form, see the part "POST form to external suppliers".

In the request, you shall also indicate the URL (merchantReturnUrl) to which the customer will be redirected to at the end of the external bank transfer. You must then call the creditTransferrFinalizeAndOrder service to finalize the transaction.

The URL is : https://office-server.sips-atos.com /rs-services/v2/checkout/creditTransferInitialize

creditTransferInitialize request format

Field Presence As of Version Comments
amount Mandatory WS_2.0
customerBankCode Conditional WS_2.0
customerBankName Conditional WS_2.0
currencyCode Mandatory WS_2.0
customerId Optional WS_2.0
customerIpAddress Optional WS_2.0
customerLanguage Optional WS_2.0
merchantTransactionDateTime Optional WS_2.0
orderChannel Mandatory WS_2.0
orderId Optional WS_2.0
paymentPattern Optional WS_2.0
returnContext Optional WS_2.0
paymentMeanBrand Mandatory WS_2.0
statementReference Optional WS_2.0
transactionOrigin Optional WS_2.0
transactionReference Conditional WS_2.0 Mandatory if you do not use the s10TransactionReference, depending on your merchant configuration
merchantReturnUrl Optional WS_2.0
merchantId Mandatory WS_2.0
interfaceVersion Mandatory WS_2.0 The recommended value is IR_WS_ 2.32 in order to take advantage of the latest features
invoiceReference Optional WS_2.0
billingContact Optional WS_2.0 See the Containers part
billingAddress Optional WS_2.0 See the Containers part
customerContact Optional WS_2.0 See the Containers part
customerAddress Optional WS_2.0 See the Containers part
customerData Optional WS_2.0 See the Containers part
deliveryContact Optional WS_2.0 See the Containers part
deliveryAddress Optional WS_2.0 See the Containers part
holderContact Optional WS_2.0 See the Containers part
holderAddress Optional WS_2.0 See the Containers part
s10TransactionReference Conditional WS_2.0 Mandatory if you do not use the transactionReference, depending on your merchant configuration. See the Containers part
fraudData Optional WS_2.10 See the Containers part
intermediateServiceProviderId Optional WS_2.12
seal Mandatory WS_2.0
keyVersion Mandatory WS_2.0
sealAlgorithm Optional WS_2.12

Example of request for creditTransferInitialize

      {
  "amount": "1000",
  "currencyCode": "978",
  "customerBankCode": "RABONL2U",
  "customerBankName": "BANK - RABO",
  "customerLanguage": "fr",
  "interfaceVersion": "IR_WS_2.9",
  "keyVersion": "1",
  "merchantId": "011223344550000",
  "merchantReturnUrl": "http://www.yoursiteweb.com",
  "merchantTransactionDateTime": "2015-05-28T11:07:11.005+02:00",
  "orderChannel": "INTERNET",
  "orderId": "123",
  "paymentMeanBrand": "IDEAL",
  "transactionReference": " TREFEXA2015",
  "seal": "50e15601a2e83bcc5ffe596a51bab5b8dab2e3c62d3de2fe0d15502600f4aded"
}

    

creditTransferInitialize response format

Field As of Version Comments
responseCode WS_2.0
redirectionUrl WS_2.0
redirectionData WS_2.0
messageVersion WS_2.0
errorFieldName WS_2.0
seal WS_2.0

Example of response for creditTransferInitialize

      {
  "responseCode": "00",
  "redirectionUrl": "https://payment-web.sips-atos.com/paymentprovider/init",
  "redirectionData": "RSs7cZyL1D...a+hZ+1ticHD/4/s\u003d",
  "messageVersion": "0.1",
  "seal": "d0814427cbd5515e78cb54476c8594eb2c1d3732a9b392afd325ebae33945069"
}

    

Function "CreditTransferFinalizeAndOrder" of service "checkout"

This service is currently available for the payment means iDEAL and Sofortüberweisung.

This request is mandatory to know the result of the bank transfer. It must be called after you received the POST form from the bank transfer service through the merchantReturnUrl (see creditTransferInitialize request).

The URL is : https://office-server.sips-atos.com /rs-services/v2/checkout/creditTransferFinalizeAndOrder

creditTransferFinalizeAndOrder request format

Field Presence As of Version Comments
interfaceVersion Mandatory WS_2.0 The recommended value is IR_WS_ 2.32 in order to take advantage of the latest features
merchantId Mandatory WS_2.0
messageVersion Mandatory WS_2.0
redirectionData Mandatory WS_2.0
transactionReference Conditional WS_2.0 Mandatory if you do not use the s10TransactionReference, depending on your merchant configuration
s10TransactionReference Conditional WS_2.0 Mandatory if you do not use the transactionReference, depending on your merchant configuration. See the Containers part
intermediateServiceProviderId Optional WS_2.12
seal Mandatory WS_2.0
keyVersion Mandatory WS_2.0
sealAlgorithm Optional WS_2.12

Example of request for creditTransferFinalizeAndOrder

      {
  "interfaceVersion": "IR_WS_2.6",
  "keyVersion": "1",
  "merchantId": "011223344550000",
  "messageVersion": "0.1",
  "redirectionData": "RSs7cZyL1Dq....MzMbzqw",
  "transactionReference": "TREFEXA2015",
  "seal": "f8769766243dcb603e417556a0e1d54b29b64cb9398317af3a16eb0a19db7057"
}

    

creditTransferFinalizeAndOrder response format

Field As of Version Comments
amount WS_2.0
authorisationId WS_2.0
customerBankCode WS_2.0
customerBankName WS_2.0
captureDay WS_2.0
captureMode WS_2.0
complementaryCode WS_2.0
complementaryInfo WS_2.0
currencyCode WS_2.0
customerId WS_2.0
customerIpAddress WS_2.0
errorFieldName WS_2.0
holderAuthentMethod WS_2.0
holderAuthentStatus WS_2.0
holderAuthentProgram WS_2.0
invoiceReference WS_2.0
merchantTransactionDateTime WS_2.0
merchantId WS_2.0
orderChannel WS_2.0
orderId WS_2.0
paymentMeanBrand WS_2.0
paymentPattern WS_2.0
paymentMeanType WS_2.0
responseCode WS_2.0
returnContext WS_2.0
statementReference WS_2.0
s10TransactionReference WS_2.0 See the Containers part
scoreColor WS_2.0
scoreInfo WS_2.0
scoreProfile WS_2.0
scoreThreshold WS_2.0
scoreValue WS_2.0
transactionDateTime WS_2.0
transactionReference WS_2.0
seal WS_2.0
preAuthorisationProfile WS_2.13
preAuthorisationProfileValue WS_2.13
preAuthorisationRuleResultList WS_2.13 List of container preAuthorisationRuleResult . See the Containers part
transactionPlatform WS_2.17 Always filled with « PROD »
intermediateServiceProviderOperationId WS_2.24

Example of response for creditTransferFinalizeAndOrder

      {
  "amount": 1000,
  "customerBankCode": "RABONL2U",
  "customerBankName": "BANK - RABO",
  "captureDay": 0,
  "captureMode": "AUTHOR_CAPTURE",
  "currencyCode": "978",
  "merchantTransactionDateTime": "2014-12-05T00:00:00+01:00",
  "merchantId": "011223344550000",
  "orderChannel": "INTERNET",
  "orderId": "123",
  "paymentMeanBrand": "IDEAL",
  "paymentPattern": "ONE_SHOT",
  "responseCode": "00",
  "s10TransactionReference": {
    "s10TransactionId": "129192",
    "s10TransactionIdDate": "20150528"
  },
  "transactionDateTime": "2015-05-28T11:18:26+02:00",
  "transactionReference": "TREFEXA2015",
  "seal": "85cd304554ebc24a60255dbb695b34c46665c6ad2f838966941ceb6dacd9e6ec",
  "transactionPlatform": "PROD"
}

    

Function "Recycle" of service "cashManagement"

This function makes it possible to create a new transaction using the bank details of an existing transaction. This operation is similar to duplicate operation, but include some limitations.

Note : please read the set-up guide ('cash management > recycle' section), to find out in which cases you can perform a recycle operation.

The URL is : https://office-server.sips-atos.com /rs-services/v2/cashManagement/recycle

recycle request format

Field Presence As of Version Comments
amount Mandatory WS_2.0
currencyCode Mandatory WS_2.0
captureDay Optional WS_2.0
captureMode Optional WS_2.0
fromTransactionReference Conditional WS_2.0 Mandatory if you do not use the s10FromTransactionReference
interfaceVersion Mandatory WS_2.0 The recommended value is CR_WS_ 2.32 in order to take advantage of the latest features
merchantId Mandatory WS_2.0
merchantTransactionDateTime Optional WS_2.0
statementReference Optional WS_2.0
transactionOrigin Optional WS_2.0
transactionReference Conditional WS_2.0 Mandatory if you do not use the s10TransactionReference, depending on your merchant configuration
lastRecoveryIndicator Optional WS_2.17
s10TransactionReference Conditional WS_2.6 Mandatory if you do not use the transactionReference, depending on your merchant configuration. See the Containers part
s10FromTransactionReference Conditional WS_2.6 Mandatory if you do not use the fromTransactionReference. See the Containers part
intermediateServiceProviderId Optional WS_2.12
seal Mandatory WS_2.0
keyVersion Mandatory WS_2.0
sealAlgorithm Optional WS_2.12

Example of request for recycle

      {
  "amount": "1000",
  "captureMode": "AUTHOR_CAPTURE",
  "currencyCode": "978",
  "fromTransactionReference": "SIM2014082813176",
  "interfaceVersion": "CR_WS_2.0",
  "merchantId": "011223344550000",
  "merchantTransactionDateTime": "2014-08-28T13:17:16.480+02:00",
  "transactionOrigin": "SIPS-SIM",
  "transactionReference": "SIM20140828131716",
  "seal": "bab5067f4fa23924cd80f35d5585519a563ff261f38dfa9b74fbb76888b00b64",
  "keyVersion": "1"
}

    

recycle response format

Field As of Version Comments
acquirerResponseCode WS_2.0
authorisationId WS_2.0
complementaryCode WS_2.0
complementaryInfo WS_2.0
maskedPan WS_2.0
panExpiryDate WS_2.0
paymentMeanBrand WS_2.0
scoreValue WS_2.0
scoreColor WS_2.0
scoreInfo WS_2.0
scoreProfile WS_2.0
scoreThreshold WS_2.0
responseCode WS_2.0
transactionDateTime WS_2.0
s10TransactionReference WS_2.6 See the Containers part
transactionReference WS_2.6
cardData WS_2.9 See the Containers part
seal WS_2.0
preAuthorisationProfile WS_2.13
preAuthorisationProfileValue WS_2.13
preAuthorisationRuleResultList WS_2.13 List of container preAuthorisationRuleResult . See the Containers part
preAuthenticationColor WS_2.13
preAuthenticationInfo WS_2.13
preAuthenticationProfile WS_2.13
preAuthenticationProfileValue WS_2.13
preAuthenticationRuleResultList WS_2.13 List of container preAuthenticationRuleResult . See the Containers part
preAuthenticationThreshold WS_2.13
preAuthenticationValue WS_2.13
paymentMeanBrandSelectionStatus WS_2.13
transactionPlatform WS_2.17 Always filled with « PROD »
errorFieldName WS_2.21
schemeTransactionIdentifier WS_2.31
paymentAccountReference WS_2.31

Example of response for recycle

      {
  "acquirerResponseCode": "00",
  "authorisationId": "736256",
  "maskedPan": "4541##########00",
  "panExpiryDate": "201504",
  "paymentMeanBrand": "VISA",
  "scoreValue": "-2.3",
  "scoreColor": "RED",
  "scoreInfo": "A3;N;NOT_APPLICABLE#WN;P;U#BN;N;U#GN;N;U#SC;N;TRANS\u003d3:2;CUMUL\u003d3000:250000",
  "scoreProfile": "myprofSco",
  "scoreThreshold": "-3.0",
  "responseCode": "00",
  "transactionDateTime": "2014-08-28T13:20:45+02:00",
  "seal": "df0c23e0a60a745f1f546168fafedb7ae547912473d76c93ee52d31b9d714765",
  "transactionPlatform": "PROD"
}

    

Function "AcceptChallenge" of service "cashManagement"

This function allows a merchant to accept the challenge on a transaction. Once the challenge is validated, the transaction retakes its normal course.

Note : please read the set-up guide ('cash management > challenge' section), to find out in which cases you can perform an accept challenge operation.

The URL is : https://office-server.sips-atos.com /rs-services/v2/cashManagement/acceptChallenge

acceptChallenge request format

Field Presence As of Version Comments
comment Optional WS_2.0
interfaceVersion Mandatory WS_2.0 The recommended value is CR_WS_ 2.32 in order to take advantage of the latest features
merchantId Mandatory WS_2.0
operationOrigin Optional WS_2.0
transactionReference Conditional WS_2.0 Mandatory if you do not use the s10TransactionReference, depending on your merchant configuration
validationIndicator Optional WS_2.0 Accepted values : « Y » and « N »
s10TransactionReference Conditional WS_2.6 Mandatory if you do not use the transactionReference, depending on your merchant configuration. See the Containers part
intermediateServiceProviderId Optional WS_2.12
seal Mandatory WS_2.0
keyVersion Mandatory WS_2.0
sealAlgorithm Optional WS_2.12

Example of request for acceptChallenge

      {
  "comment": "good id",
  "interfaceVersion": "CR_WS_2.6",
  "keyVersion": "1",
  "merchantId": "011223344550000",
  "operationOrigin": "SIPS-SIM",
  "transactionReference": "SIM20140121510382",
  "validationIndicator": "Y",
  "seal": "e746314133f7aaabd8ac33db0daf941eda744e8ff70b700490792ffe3480087d"
}

    

acceptChallenge response format

Field As of Version Comments
acquirerResponseCode WS_2.0
authorisationId WS_2.0
newStatus WS_2.0
operationDateTime WS_2.0
captureLimitDate WS_2.0
responseCode WS_2.0
seal WS_2.0
errorFieldName WS_2.21
schemeTransactionIdentifier WS_2.31
paymentAccountReference WS_2.31
guaranteeIndicator WS_2.32
secureReference WS_2.32

Example of response for acceptChallenge

      {
  "acquirerResponseCode": "00",
  "authorisationId": "123",
  "captureLimitDate": "1",
  "operationDateTime": "2014-10-16T23:51:42-12:00",
  "responseCode": "00",
  "newStatus": "VALIDATED",
  "seal": "919b544bfb60539c8979992bc469e0b4229030ee2462a51f62c9cbd3510b3647"
}

    

Function "RefuseChallenge" of service "cashManagement"

This function allows a merchant to refuse the challenge on a transaction. Once the challenge is refused, the transaction is refused.

Note : please read the set-up guide ('cash management > challenge' section), to find out in which cases you can perform a refuse challenge operation.

The URL is : https://office-server.sips-atos.com /rs-services/v2/cashManagement/refuseChallenge

refuseChallenge request format

Field Presence As of Version Comments
comment Optional WS_2.0
interfaceVersion Mandatory WS_2.0 The recommended value is CR_WS_ 2.32 in order to take advantage of the latest features
merchantId Mandatory WS_2.0
operationOrigin Optional WS_2.0
transactionReference Conditional WS_2.0 Mandatory if you do not use the s10TransactionReference, depending on your merchant configuration
s10TransactionReference Conditional WS_2.6 Mandatory if you do not use the transactionReference, depending on your merchant configuration. See the Containers part
intermediateServiceProviderId Optional WS_2.12
seal Mandatory WS_2.0
keyVersion Mandatory WS_2.0
sealAlgorithm Optional WS_2.12

Example of request for refuseChallenge

      {
  "comment": "bad id",
  "interfaceVersion": "CR_WS_2.6",
  "keyVersion": "1",
  "merchantId": "011223344550000",
  "operationOrigin": "SIPS-SIM",
  "transactionReference": "SIM20140121510382",
  "seal": "c36bcfaf3c05ef257795149686c53022f212e05c6fac98d0169c5e9313941444"
}

    

refuseChallenge response format

Field As of Version Comments
newStatus WS_2.0
operationDateTime WS_2.0
responseCode WS_2.0
seal WS_2.0
errorFieldName WS_2.21

Example of response for refuseChallenge

      {
  "operationDateTime": "2014-10-16T23:51:42-12:00",
  "responseCode": "00",
  "newStatus": "REFUSED",
  "seal": "919b544bfb60539c8979992bc469e0b4229030ee2462a51f62c9cbd3510b3647"
}

    

Function "PanToToken" of service "token"

This function makes it possible to transform a pan to a token.

The URL is : https://office-server.sips-atos.com /rs-services/v2/token/panToToken

panToToken request format

Field Presence As of Version Comments
merchantId Mandatory WS_2.0
interfaceVersion Mandatory WS_2.0 The recommended value is TR_WS_ 2.32 in order to take advantage of the latest features
userId Optional WS_2.0
panDataList Optional WS_2.0 List of container panData . See the Containers part
intermediateServiceProviderId Optional WS_2.12
seal Mandatory WS_2.0
keyVersion Mandatory WS_2.0
sealAlgorithm Optional WS_2.12

Example of request for panToToken

      {
  "interfaceVersion": "TR_WS_2.0",
  "keyVersion": "1",
  "merchantId": "011223344550000",
  "panDataList": [
    {
      "pan": "4907000000000600",
      "panId": "1"
    }
  ],
  "userId": "uid",
  "seal": "8f95bd9cc96c7723b530f0492c9fed50399b94f9b0c91c113b4f56a97fe2cb8f"
}

    

panToToken response format

Field As of Version Comments
responseCode WS_2.0
responseTokenPanDataList WS_2.0 List of container responseTokenPanData . See the Containers part
seal WS_2.0
errorFieldName WS_2.21

Example of response for panToToken

      {
  "responseCode": "00",
  "responseTokenPanDataList": [
    {
      "tokenResponseCode": "00",
      "panId": "1",
      "tokenPan": "490700h719850600"
    }
  ],
  "seal": "a16689b166fa9a508341fad15563633bb83367d009d3f2507c95bc71cd9f1ad5"
}

    

Function "TokenToPan" of service "token"

This function makes it possible to transform a token to a pan.

The URL is : https://office-server.sips-atos.com /rs-services/v2/token/tokenToPan

tokenToPan request format

Field Presence As of Version Comments
merchantId Mandatory WS_2.0
interfaceVersion Mandatory WS_2.0 The recommended value is TR_WS_ 2.32 in order to take advantage of the latest features
userId Optional WS_2.0
tokenPanDataList Optional WS_2.0 List of container tokenPanData . See the Containers part
intermediateServiceProviderId Optional WS_2.12
seal Mandatory WS_2.0
keyVersion Mandatory WS_2.0
sealAlgorithm Optional WS_2.12

Example of request for tokenToPan

      {
  "interfaceVersion": "TR_WS_2.0",
  "keyVersion": "1",
  "merchantId": "011223344550000",
  "panDataList": [
    {
      "pan": "490700h719850600",
      "panId": "1"
    }
  ],
  "userId": "uid",
  "seal": "e350c058e2be7a3686682587dfac89cd192cda1ad2c2f532e10f9d59b9ca0f13"
}

    

tokenToPan response format

Field As of Version Comments
responseCode WS_2.0
responsePanDataList WS_2.0 List of container responsePanData . See the Containers part
seal WS_2.0
errorFieldName WS_2.21

Example of response for tokenToPan

      {
  "responseCode": "00",
  "responsePanDataList": [
    {
      "tokenResponseCode": "00",
      "tokenPanId": "1",
      "pan": "4907000000000600"
    }
  ]
}

    

Function "TransactionToToken" of service "token"

This function makes it possible to retrieve the token pan from a transaction.

The URL is : https://office-server.sips-atos.com /rs-services/v2/token/transactionToToken

transactionToToken request format

Field Presence As of Version Comments
merchantId Mandatory WS_2.0
fromMerchantId Optional WS_2.0 Shop identifier of the original transaction. Mandatory if different from merchantId
fromTransactionReference Conditional WS_2.0 Mandatory if s10FromTransactionReference is absent
interfaceVersion Mandatory WS_2.0 The recommended value is TR_WS_ 2.32 in order to take advantage of the latest features
s10FromTransactionReference Conditional WS_2.6 Mandatory if fromTransactionReference is absent. See the Containers part
intermediateServiceProviderId Optional WS_2.12
seal Mandatory WS_2.0
keyVersion Mandatory WS_2.0
sealAlgorithm Optional WS_2.12
merchantExternalId Optional WS_2.0

Example of request for transactionToToken

      {
  "fromMerchantId": "024729465300006",
  "fromTransactionReference": "SIM20170613140621",
  "interfaceVersion": "TR_WS_2.20",
  "keyVersion": "1",
  "merchantExternalId": "myMerchantExternalId",
  "merchantId": "024729465300101",
  "seal": "9f0a2e696242acdb3f966fed16bfd91d540531b9e259f41c474f52fb2c62345b"
}

    

transactionToToken response format

Field As of Version Comments
responseCode WS_2.0
merchantId WS_2.0
fromMerchantId WS_2.0
fromTransactionReference WS_2.0
s10FromTransactionReference WS_2.6 See the Containers part
seal WS_2.0
merchantExternalId WS_2.0
tokenPan WS_2.0
paymentMeanBrand WS_2.0
cardExpiryDate WS_2.0
errorFieldName WS_2.21

Example of response for transactionToToken

      {
  "responseCode": "00",
  "merchantId": "024729465300101",
  "fromMerchantId": "024729465300006",
  "fromTransactionReference": "SIM20170613140621",
  "seal": "a8e229f12c98f5f2a1cf2a8def150691e2742410441675e308a4f9a695a14547",
  "merchantExternalId": "myMerchantExternalId",
  "tokenPan": "490700h719850600",
  "paymentMeanBrand": "VISA",
  "cardExpiryDate": "201802"
}

    

Function "GetCardData" of service "paymentMeanInfo"

This function allows consulting of the card information associated with a card number or a card IIN.

If the card number or the card IIN does not exist, a 05 response code is returned. If the request works, 00 response code is returned as well as information related to the card.

The URL is : https://office-server.sips-atos.com /rs-services/v2/paymentMeanInfo/getCardData

getCardData request format

Field Presence As of Version Comments
merchantId Mandatory WS_2.5
interfaceVersion Mandatory WS_2.5 The recommended value is PMR_WS_ 2.32 in order to take advantage of the latest features
cardNumber Optional WS_2.5 Must be set if cardIIN is not set
cardIIN Optional WS_2.5 Must be set if cardNumber is not set
seal Mandatory WS_2.5
keyVersion Mandatory WS_2.5
sealAlgorithm Optional WS_2.12
intermediateServiceProviderId Optional WS_2.12

Example of request for getCardData

      {
  "cardNumber": "4975000000000000",
  "interfaceVersion": "PMR_WS_2.5",
  "keyVersion": "1",
  "merchantId": "011223344550000",
  "seal": "97fccfbfde4570019236f31e3bb521be477bbc7bf7cf09c30f8fbc3a635a3011"
}

    

getCardData response format

Field As of Version Comments
paymentMeanInfoResponseCode WS_2.5
cardDataList WS_2.5 List of container cardData . See the Containers part
errorFieldName WS_2.5 Available if paymentMeanInfoResponseCode 12 or 30
seal WS_2.5

Example of response for getCardData

      {
  "paymentMeanInfoResponseCode": "00",
  "cardDataList": [
    {
      "cardScheme": "CB",
      "cardBrand": "CB",
      "cardProductCode": "2",
      "cardProductName": "CARTE NATIONALE DE RETRAIT ET DE PAIEMENT",
      "issuerCode": "10107",
      "issuerCountryCode": "FRA",
      "panLengthMin": 16,
      "panLengthMax": 16,
      "panCheckAlgorithm": "L",
      "cardProductProfile": "D"
    },
    {
      "cardScheme": "VISA",
      "cardBrand": "VISA",
      "cardProductCode": "F",
      "cardProductName": "VISA CLASSIC",
      "cardCorporateIndicator": "N",
      "issuerCode": "10107",
      "issuerCountryCode": "FRA",
      "issuerRegionCode": "D",
      "panLengthMin": 16,
      "panLengthMax": 16,
      "panCheckAlgorithm": "L"
    }
  ],
  "seal": "c10bc66f574d22c4eb68250fe80c7d764a420a4fa22fde23f69e3a67bf60d131"
}

    

Function "GetVelocityData" of service "fraud"

This function makes it possible to check the activity of a given data field over a given period.

The URL is : https://office-server.sips-atos.com /rs-services/v2/fraud/getVelocityData

getVelocityData request format

Field Presence As of Version Comments
velocityElementType Mandatory WS_2.0
velocityElementValue Mandatory WS_2.0
merchantId Mandatory WS_2.0
velocityPeriod Optional WS_2.0
interfaceVersion Mandatory WS_2.0 The recommended value is FR_WS_ 2.32 in order to take advantage of the latest features
intermediateServiceProviderId Optional WS_2.12
seal Mandatory WS_2.0
keyVersion Mandatory WS_2.0
sealAlgorithm Optional WS_2.12

Example of request for getVelocityData

      {
  "interfaceVersion": "FR_WS_2.9",
  "keyVersion": "1",
  "merchantId": "011223344550000",
  "velocityElementType": "customerId",
  "velocityElementValue": "cust010",
  "velocityPeriod": "50",
  "seal": "fc24b9e6bd7a433d258a1df1a8af2698b917d1632aaa1bc12c5c8f45adbeba11"
}

    

getVelocityData response format

Field As of Version Comments
responseCode WS_2.0
velocityTotalAmount WS_2.0
velocityNbTransaction WS_2.0
currencyCode WS_2.0
velocityProfileMaxTotalAmount WS_2.0
velocityProfileMaxNbTrans WS_2.0
velocityProfileMaxTransAmount WS_2.0
velocityProfileName WS_2.0
velocityProfilePeriod WS_2.0
velocityProfileDateTime WS_2.0
seal WS_2.0
errorFieldName WS_2.21

Example of response for getVelocityData

      {
  "responseCode": "00",
  "velocityTotalAmount": 0,
  "velocityNbTransaction": 0,
  "velocityProfilMaxTotalAmount": 1000,
  "velocityProfilMaxNbTrans": 10,
  "velocityProfilMaxTransAmount": 100,
  "currencyCode": "978",
  "velocityProfileName": "all_controls",
  "velocityProfilPeriod": 10,
  "velocityProfileDateTime": "2014-11-19T14:21:32+01:00",
  "seal": "5a65b70f786047ef13f80a55a6642211daa52df74039c605e70ac7d752f52731"
}

    

Function "AddToFraudList" of service "fraud"

The operation allows the management of the list types by insertion of PAN, TOKEN, Tid /Date, Tref.

The URL is : https://office-server.sips-atos.com /rs-services/v2/fraud/addToFraudList

addToFraudList request format

Field Presence As of Version Comments
merchantId Mandatory WS_2.15
interfaceVersion Mandatory WS_2.15 The recommended value is FR_WS_ 2.32 in order to take advantage of the latest features
intermediateServiceProviderId Optional WS_2.15
fraudListType Mandatory WS_2.15
fraudListLevel Mandatory WS_2.15
fraudListElementType Conditional WS_2.15
fraudListElementValue Mandatory WS_2.15
fraudListReasonCode Optional WS_2.15
seal Mandatory WS_2.15
keyVersion Mandatory WS_2.15
sealAlgorithm Optional WS_2.15

Example of request for addToFraudList

      {
  "fraudListElementType": "PAN",
  "fraudListElementValue": "5017674000000200",
  "fraudListLevel": "WHITE",
  "fraudListType": "CARD_LIST",
  "interfaceVersion": "FR_WS_2.15",
  "keyVersion": "1",
  "merchantId": "226000009630001",
  "seal": "b3f44355e912ebb9c3fed0e3a00a5782762afd604055f3a56438971a4e9ec58f"
}

    

addToFraudList response format

Field As of Version Comments
fraudResponseCode WS_2.15
errorFieldName WS_2.15
seal WS_2.15

Example of response for addToFraudList

      {
  "fraudResponseCode": "00",
  "seal": "0a7c1ab8fa767313e0631d166843eb55b9f783426241690a2b6e23ca40087811"
}

    

Function "RemoveFromFraudList" of service "fraud"

The operation allows the management removal of the list types of PAN, TOKEN, Tid /Date, Tref.

The URL is : https://office-server.sips-atos.com /rs-services/v2/fraud/removeFromFraudList

removeFromFraudList request format

Field Presence As of Version Comments
merchantId Mandatory WS_2.15
interfaceVersion Mandatory WS_2.15 The recommended value is FR_WS_ 2.32 in order to take advantage of the latest features
intermediateServiceProviderId Optional WS_2.15
fraudListType Mandatory WS_2.15
fraudListLevel Mandatory WS_2.15
fraudListElementType Conditional WS_2.15
fraudListElementValue Mandatory WS_2.15
seal Mandatory WS_2.15
keyVersion Mandatory WS_2.15
sealAlgorithm Optional WS_2.15

Example of request for removeFromFraudList

      {
  "fraudListElementType": "PAN",
  "fraudListElementValue": "5017674000000200",
  "fraudListLevel": "WHITE",
  "fraudListType": "CARD_LIST",
  "interfaceVersion": "FR_WS_2.15",
  "keyVersion": "1",
  "merchantId": "226000009630001",
  "seal": "b3f44355e912ebb9c3fed0e3a00a5782762afd604055f3a56438971a4e9ec58f"
}

    

removeFromFraudList response format

Field As of Version Comments
fraudResponseCode WS_2.15
errorFieldName WS_2.15
seal WS_2.15

Example of response for removeFromFraudList

      {
  "fraudResponseCode": "00",
  "seal": "0a7c1ab8fa767313e0631d166843eb55b9f783426241690a2b6e23ca40087811"
}

    

Function "AddCard" of service "wallet"

This function allows to create a wallet account with a card. The latter is created at the same time as adding the card, if it does not exist.

Sensitive information (card number) can be handled via the panType set to encryption via the CSE mode (see the relevant documentation) .

If the card is already recorded in the wallet, then a 94 response code is returned.

If the creation succeeds, response code 00 is returned as well as a lot of information about the account and the associated card :

  • wallet identifier
  • creation date
  • external identifier of the means of payment created for the wallet
  • card number, partially hidden (only the first 4 and 2 last digits are clear).

The URL is : https://office-server.sips-atos.com /rs-services/v2/wallet/addCard

addCard request format

Field Presence As of Version Comments
merchantId Mandatory WS_2.0
interfaceVersion Mandatory WS_2.0 The recommended value is WR_WS_ 2.32 in order to take advantage of the latest features
cardNumber Mandatory WS_2.0
cardExpiryDate Mandatory WS_2.0
panType Optional WS_2.31
merchantWalletId Mandatory WS_2.0
paymentMeanAlias Optional WS_2.0
paymentMeanBrand Optional WS_2.20
intermediateServiceProviderId Optional WS_2.12
seal Mandatory WS_2.0
keyVersion Mandatory WS_2.0
sealAlgorithm Optional WS_2.12

Example of request for addCard

      {
  "cardExpiryDate": "201405",
  "cardNumber": "5219000000000000",
  "interfaceVersion": " WR_WS_2.3",
  "keyVersion": "1",
  "merchantId": "011223344550000",
  "merchantWalletId": "iDWal1",
  "paymentMeanAlias": "myvisacard",
  "paymentMeanbrand": "VISA",
  "seal": "4b7beed20ff443b3c05cc904bcd793ba6cace54b9ff669cf26d8576e267dc03c"
}

    

addCard response format

Field As of Version Comments
walletActionDateTime WS_2.0
paymentMeanId WS_2.0
maskedPan WS_2.0
walletResponseCode WS_2.0
errorFieldName WS_2.0 Available if walletResponseCode 12 or 30
seal WS_2.0

Example of response for addCard

      {
  "walletActionDateTime": "2014-03-19T23:15:03-12:00",
  "paymentMeanId": "13",
  "maskedPan": "4977##########55",
  "walletResponseCode": "00",
  "seal": "a6671feade95c57085939fe973e8455a5c7a81d465f78f1b94c22f8b29a2b751"
}

    

Function "AddDirectDebit" of service "wallet"

This function allows to add a mandate to a wallet. If the mandat is already recorded in the wallet, then a 94 response code is returned.

If the creation succeeds, response code 00 is returned as well as a lot of information about the account and the associated mandate :

  • creation date
  • external identifier of the means of payment created for the wallet
  • iban, partially hidden (only the first 4 and 2 last digits are clear).

The URL is : https://office-server.sips-atos.com /rs-services/v2/wallet/addDirectDebit

addDirectDebit request format

Field Presence As of Version Comments
merchantId Mandatory WS_2.0
interfaceVersion Mandatory WS_2.0 The recommended value is WR_WS_ 2.32 in order to take advantage of the latest features
merchantWalletId Mandatory WS_2.0
paymentMeanBrand Mandatory WS_2.0
mandateId Optional WS_2.0
customerBankCode Optional WS_2.0
customerAccount Optional WS_2.0
transactionActors Optional WS_2.0
paymentMeanAlias Optional WS_2.0
intermediateServiceProviderId Optional WS_2.12
seal Mandatory WS_2.0
keyVersion Mandatory WS_2.0
sealAlgorithm Optional WS_2.12

Example of request for addDirectDebit

      {
  "customerAccount": "FR76300460012900297215195464",
  "customerBankCode": "CEPAFRPP118",
  "interfaceVersion": "WR_WS_2.0",
  "keyVersion": "1",
  "mandateId": "MANDATE0001",
  "merchantId": "011223344550000",
  "merchantWalletId": "1",
  "paymentMeanAlias": "ABC bank account",
  "paymentMeanBrand": "SEPA_DIRECT_DEBIT",
  "transactionActors": "BtoB",
  "seal": "8493c63cd279824b90bf39f542df205343392e08412345d4c2b9c856c42464ef9"
}

    

addDirectDebit response format

Field As of Version Comments
walletActionDateTime WS_2.0
paymentMeanId WS_2.0
maskedPan WS_2.0
transactionActors WS_2.0
walletResponseCode WS_2.0
errorFieldName WS_2.0 Available if walletResponseCode 12 or 30
seal WS_2.0

Example of response for addDirectDebit

      {
  "walletActionDateTime": "2014-07-28T21:14:13-12:00",
  "paymentMeanId": "8",
  "maskedPan": "MAND#####01",
  "transactionActors": "BtoB",
  "walletResponseCode": "00",
  "seal": "75cc0bd5f72a15fb38b0f609393437db61866f867fa7befeef9b3f496a9e449f"
}

    

Function "DeletePaymentMean" of service "wallet"

This function allows a merchant to permanently delete one of the payment means of his wallet.

If the account or the card does not exist, a 01 response code is returned. If the deletion works, 00 response code is returned and the date of removal.

The URL is : https://office-server.sips-atos.com /rs-services/v2/wallet/deletePaymentMean

deletePaymentMean request format

Field Presence As of Version Comments
merchantId Mandatory WS_2.0
interfaceVersion Mandatory WS_2.0 The recommended value is WR_WS_ 2.32 in order to take advantage of the latest features
merchantWalletId Mandatory WS_2.0
paymentMeanId Mandatory WS_2.0
intermediateServiceProviderId Optional WS_2.12
seal Mandatory WS_2.0
keyVersion Mandatory WS_2.0
sealAlgorithm Optional WS_2.12

Example of request for deletePaymentMean

      {
  "interfaceVersion": "WR_WS_2.3",
  "keyVersion": "2",
  "merchantId": "011223344550000",
  "merchantWalletId": "walId011",
  "paymentMeanId": "2",
  "seal": "dc02b07a50eaae5007be184ede9a1b03150809ced6fca81c81f7a54929129b44"
}

    

deletePaymentMean response format

Field As of Version Comments
walletActionDateTime WS_2.0
walletResponseCode WS_2.0
errorFieldName WS_2.0 Available if walletResponseCode 12 or 30
seal WS_2.0

Example of response for deletePaymentMean

      {
  "walletActionDateTime": "2014-05-19T23:22:08-12:00",
  "walletResponseCode": "00",
  "seal": "e721a45f7decf017ba079dd0c25b1e7916c6c9e6c7e86d6cef37bec2cf42ba04"
}

    

Function "UpdatePaymentMean" of service "wallet"

This function allows you to update one of the payment means contained in the client's wallet. If the account or the payment mean do not exist, a 01 response code is returned. If the update works, 00 response code is returned and the date of update.

The URL is : https://office-server.sips-atos.com /rs-services/v2/wallet/updatePaymentMean

updatePaymentMean request format

Field Presence As of Version Comments
merchantId Mandatory WS_2.0
interfaceVersion Mandatory WS_2.0 The recommended value is WR_WS_ 2.32 in order to take advantage of the latest features
merchantWalletId Mandatory WS_2.0
paymentMeanId Mandatory WS_2.0
paymentMeanAlias Optional WS_2.0
intermediateServiceProviderId Optional WS_2.12
seal Mandatory WS_2.0
keyVersion Mandatory WS_2.0
sealAlgorithm Optional WS_2.12

Example of request for updatePaymentMean

      {
  "interfaceVersion": "WR_WS_2.3",
  "keyVersion": "1",
  "merchantId": "011223344550000",
  "merchantWalletId": "walId011",
  "paymentMeanAlias": "myAlias",
  "paymentMeanId": "2",
  "seal": "1e26289499d5f6104e6300291f272d7b994a111eecf8feedccf934560de26e5d"
}

    

updatePaymentMean response format

Field As of Version Comments
walletActionDateTime WS_2.0
walletResponseCode WS_2.0
errorFieldName WS_2.0 Available if walletResponseCode 12 or 30
seal WS_2.0

Example of response for updatePaymentMean

      {
  "walletActionDateTime": "2014-05-19T23:19:54-12:00",
  "walletResponseCode": "00",
  "seal": "4d40a4af0fe8ceaf1370ab5e434c6ba939973bcacf33f202c72c47a8ab622c19"
}

    

Function "SignOff" of service "wallet"

This function allows to remove a wallet as well as its related payment means. If the account does not exist, a 01 response code is returned. If the deletion works, 00 response code is returned and the date of removal.

The URL is : https://office-server.sips-atos.com /rs-services/v2/wallet/signOff

signOff request format

Field Presence As of Version Comments
merchantId Mandatory WS_2.0
interfaceVersion Mandatory WS_2.0 The recommended value is WR_WS_ 2.32 in order to take advantage of the latest features
merchantWalletId Mandatory WS_2.0
intermediateServiceProviderId Optional WS_2.12
seal Mandatory WS_2.0
keyVersion Mandatory WS_2.0
sealAlgorithm Optional WS_2.12

Example of request for signOff

      {
  "interfaceVersion": "WR_WS_2.3",
  "keyVersion": "1",
  "merchantId": "011223344550000",
  "merchantWalletId": "SIM01",
  "seal": "8217a6163368bee3b5baebc47a822d40327344ce578411055f95d6e5752d00f4"
}

    

signOff response format

Field As of Version Comments
walletActionDateTime WS_2.0
walletResponseCode WS_2.0
errorFieldName WS_2.0 Available if walletResponseCode 12 or 30
seal WS_2.0

Example of response for signOff

      {
  "walletActionDateTime": "2014-05-19T23:20:25-12:00",
  "walletResponseCode": "00",
  "seal": "8ff8b4302b5eeda23bad2d556dd539c2b3991f8dcd4deb66e338df3a1f59ebe6"
}

    

Function "AddIssuerWallet" of service "wallet"

This function allows the addition of an external wallet identifier to a WL Sips Wallet. A new wallet is created if nonexistent. If the issuer wallet is already recorded in the wallet, then a 94 response code is returned. If the operation succeeds, response code 00 is returned.

The URL is : https://office-server.sips-atos.com /rs-services/v2/wallet/addIssuerWallet

addIssuerWallet request format

Field Presence As of Version Comments
merchantId Mandatory WS_2.0
interfaceVersion Mandatory WS_2.0 The recommended value is WR_WS_ 2.32 in order to take advantage of the latest features
issuerWalletId Mandatory WS_2.0
issuerWalletType Mandatory WS_2.0
merchantWalletId Mandatory WS_2.0
paymentMeanAlias Optional WS_2.0
intermediateServiceProviderId Optional WS_2.0
seal Mandatory WS_2.0
keyVersion Mandatory WS_2.0
sealAlgorithm Optional WS_2.0

Example of request for addIssuerWallet

      {
  "interfaceVersion": "WR_WS_2.23",
  "issuerWalletId": "xWfgmpijds",
  "issuerWalletType": "PAYLIB",
  "keyVersion": "1",
  "merchantId": "011223344550000",
  "merchantWalletId": "iDWal1",
  "paymentMeanAlias": "paylib un clique",
  "seal": "4b7beed20ff443b3c05cc904bcd793ba6cace54b9ff669cf26d8576e267dc03c"
}

    

addIssuerWallet response format

Field As of Version Comments
walletActionDateTime WS_2.0
paymentMeanId WS_2.0
walletResponseCode WS_2.0
errorFieldName WS_2.0
seal WS_2.0

Example of response for addIssuerWallet

      {
  "walletActionDateTime": "2018-03-19T23:15:03-12:00",
  "paymentMeanId": "13",
  "walletResponseCode": "00",
  "seal": "a6671feade95c57085939fe973e8455a5c7a81d465f78f1b94c22f8b29a2b751"
}

    

Function "GetWalletData" of service "wallet"

This function allows to consult a wallet and payment means associated to it.

If the account does not exist, a 01 response code is returned. If the request works, 00 response code is returned as well as information related to the payment means.

The URL is : https://office-server.sips-atos.com /rs-services/v2/wallet/getWalletData

getWalletData request format

Field Presence As of Version Comments
merchantId Mandatory WS_2.0
interfaceVersion Mandatory WS_2.0 The recommended value is WR_WS_ 2.32 in order to take advantage of the latest features
merchantWalletId Mandatory WS_2.0
intermediateServiceProviderId Optional WS_2.12
seal Mandatory WS_2.0
keyVersion Mandatory WS_2.0
sealAlgorithm Optional WS_2.12

Example of request for getWalletData

      {
  "interfaceVersion": " WR_WS_2.3",
  "keyVersion": "1",
  "merchantId": "011223344550000",
  "merchantWalletId": " walId011",
  "seal": "8217a6163368bee3b5baebc47a822d40327344ce578411055f95d6e5752d00f4"
}

    

getWalletData response format

Field As of Version Comments
walletCreationDateTime WS_2.0
walletLastActionDateTime WS_2.0
walletResponseCode WS_2.0
walletPaymentMeanDataList WS_2.0 List of container walletPaymentMeanData . See the Containers part
errorFieldName WS_2.0 Available if walletResponseCode 12 or 30
seal WS_2.0

Example of response for getWalletData

      {
  "walletCreationDateTime": "2013-12-23T05:17:26-12:00",
  "walletLastActionDateTime": "2014-01-19T23:16:00-12:00",
  "walletResponseCode": "00",
  "walletPaymentMeanDataList": [
    {
      "paymentMeanId": "14",
      "maskedPan": "4977##########02",
      "paymentMeanBrand": "SEPA_DIRECT_DEBIT"
    },
    {
      "paymentMeanId": "13",
      "maskedPan": "4977##########55",
      "paymentMeanAlias": "MySDD",
      "panExpiryDate": "201501",
      "paymentMeanBrand": "CB"
    }
  ],
  "seal": "4579cfc4044c29550327f9cba0be400129e95cb5b2639c6e301484930b4f9f94"
}

    

Function "GetPaymentMeanData" of service "wallet"

This function allows to consult a wallet and one of these payment means information.

If the account or payment mean does not exist, a 01 response code is returned. If the request works, 00 response code is returned as well as information related to the payment mean.

The URL is : https://office-server.sips-atos.com /rs-services/v2/wallet/getPaymentMeanData

getPaymentMeanData request format

Field Presence As of Version Comments
merchantId Mandatory WS_2.0
interfaceVersion Mandatory WS_2.0 The recommended value is WR_WS_ 2.32 in order to take advantage of the latest features
merchantWalletId Mandatory WS_2.0
paymentMeanId Mandatory WS_2.0
intermediateServiceProviderId Optional WS_2.12
seal Mandatory WS_2.0
keyVersion Mandatory WS_2.0
sealAlgorithm Optional WS_2.12

Example of request for getPaymentMeanData

      {
  "interfaceVersion": "WR_WS_2.3",
  "keyVersion": "1",
  "merchantId": "011223344550000",
  "merchantWalletId": " walId011",
  "paymentMeanId": "14",
  "seal": "7ba62b5dc8583a636fa35ec8399025e67d5a6335de4e04e25e99d21209e0bd4e"
}

    

getPaymentMeanData response format

Field As of Version Comments
walletResponseCode WS_2.0
walletPaymentMeanData WS_2.0 See the Containers part
errorFieldName WS_2.0 Available if walletResponseCode 12 or 30
seal WS_2.0

Example of response for getPaymentMeanData

      {
  "walletResponseCode": "00",
  "walletPaymentMeanData": {
    "paymentMeanId": "14",
    "maskedPan": "4977##########02",
    "paymentMeanBrand": "SEPA_DIRECT_DEBIT"
  },
  "seal": "17f797e25668662aa51d59dbbd51c7094410f46326d15568f73f27621380c34a"
}

    

Function "InitializeMandate" of service "mandate"

This operation initializes a mandate signing process. If the initialization step is successful, you will receive in response a secure URL (redirectionUrl) to which the customer should be redirected to continue the signing process. This redirection must be made via a POST form, see the part "POST form to external suppliers".

In the request, you shall also indicate the URL (merchantReturnUrl) to which the customer will be redirected to at the end of the process for mandate signature. You must then call the finalizeMandate service to obtain the result of the signing process.

The URL is : https://office-server.sips-atos.com /rs-services/v2/mandate/initializeMandate

initializeMandate request format

Field Presence As of Version Comments
paymentMeanAlias Mandatory WS_2.0
merchantReturnUrl Mandatory WS_2.0
merchantId Mandatory WS_2.0
interfaceVersion Mandatory WS_2.0 The recommended value is MR_WS_ 2.32 in order to take advantage of the latest features
returnContext Optional WS_2.0
intermediateServiceProviderId Optional WS_2.0
seal Mandatory WS_2.0
keyVersion Mandatory WS_2.0
sealAlgorithm Optional WS_2.0
paymentMeanData Optional WS_2.0
customerContact Optional WS_2.0 See the Containers part
customerAddress Optional WS_2.0 See the Containers part
customerLanguage Optional WS_2.0
mandateId Optional WS_2.0
transactionActors Optional WS_2.0
iban Mandatory WS_2.0