Introduction

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 In-App solution up to live operations.

Who does this document target?

This document is intended for merchants wishing to subscribe to the Sips offer and offer integrated payment as part of their mobile application. The Sips In-App connector is 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 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 client that can connect to the Sips In-App gateway.

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. The Sips In-App SDK must be used with at least any version 7.0 of the iOS system or any version 5.0 of the Android system.

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

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

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

Contacting the support

For any technical question or request for assistance, our services are available:

  • by telephone at: +33 (0) 811 10 70 33
  • by e-mail: sips@worldline.com

In order to facilitate the processing of your requests, please provide your merchantId (15-digit number).

Complying with PCI-DSS

Worldline has removed the PCI-DSS obligation for your part because encrypted card data flows between mobile applications and the Sips server.

Indeed, card data never flows through your server and this must never be the case.

Therefore, your application does not have to comply with the PCI-DSS standard; it simply has to comply with the PCI-DSS best practices described at this address :

https://www.pcisecuritystandards.org/document_library?association=PA-DSS

Understanding payment with Sips In-App

1. The customer enters their payment method details. The mobile application then contacts your server with the data to be sent to the Sips engine (except card data).

2. Your server contacts the Sips server to initialise a payment request.

3. The request is checked. If it is correct, it is encrypted and sent back using the redirectionData field. Your server also receives the URL of the Sips engine used for payment and the public key to encrypt the card data during payment.

4. Your server sends all data back to the mobile application.

5. The mobile application calls the SDK to make a payment by card by providing it with the public key and the redirectionData data received. The SDK encrypts this sensitive data with the public key provided.

6. The redirectionData field and the encrypted card details are sent to the Sips engine via HTTPS.

7 and 8. The Sips engine processes the payment. In return, the engine notifies your server and the mobile application of the operation status.

Note: you are responsible for preventing "man-in-the-middle" attacks between flows 1 and 4 (for more information on this please visit https://en.wikipedia.org/wiki/Man-in-the-middle_attack).

Understanding wallet management with Sips In-App

1. Depending on the wallet management function chosen, the mobile application contacts your server with the data to be sent to the Sips engine.

2. Your server contacts the Sips server to initialise the wallet management function.

3. The request is checked. If it is correct, it is encrypted and sent back using the redirectionData field. Your server also receives the URL of the Sips engine used for wallet management and the public key to encrypt the card data during payment.

4. Your server sends all data back to the mobile application.

5. The mobile application calls the SDK to perform the requested wallet management.

6. The redirectionData field and the encrypted card details (in case a card is added) are sent to the Sips engine via HTTPS.

7. The Sips engine processes the request. In return, the engine notifies the mobile application of the operation status.

Getting-started with Sips In-App 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: making a payment

As mentioned above, the payment request consists first of all of a call to your server from the mobile application in order to send the payment method data. Your server must then initialise the payment request to the Sips server via a REST (JSON) web service.

Initialising the payment request from your server

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

The value of the interfaceVersion field must be set to IR_MB_ 1.6 .

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 20 euros:

      {"amount" : "2000","currencyCode": "978","interfaceVersion" : "IR_MB_      1.6
","merchantId" : "012345678911111","sdkOperationName" : "CARDORDER", "paymentMeanBrand" : "VISA","paymentPattern" : "ONE_SHOT","transactionReference" : "STHTSH4418152014","keyVersion"1","seal" : "112a4b079ece08a0a55511cd5469fc47051d6ddb1404623170ba3873668e5c58" }
    

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"],…
    

Securing the request

The request includes the transaction parameters and is sent by your server. 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 Sips solution meets this challenge by exchanging signatures. An effective signature control comprises two elements:

  • The integrity of the request and response messages (and therefore the absence of modifications during the exchange).
  • The issuer and recipient authentication, as they share the same secret key.
Note: 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 .

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",
  "automaticResponseUrl": "https://automatic-response-url.fr/",
  "normalReturnUrl": "https://normal-return-url/",
  "captureDay": "0",
  "captureMode": "AUTHOR_CAPTURE",
  "currencyCode": "978",
  "interfaceVersion": "IR_WS_2.22",
  "keyVersion": "1",
  "merchantId": "011223344550000",
  "orderChannel": "INTERNET",
  "orderId": "ORD101",
  "returnContext": "ReturnContext",
  "transactionOrigin": "SO_WEBAPPLI",
  "transactionReference": "TREFEXA2012",
  "seal": "e4d75c6a779adee5850192d1ecc162ca0c85e960cb00d9923879609f89739152"
}
    

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

      2500https://automatic-response-url.fr/0AUTHOR_CAPTURE978IR_WS_2.22011223344550000https://normal-return-url/INTERNETORD101ReturnContextSO_WEBAPPLITREFEXA2012
    

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

      secret123
    

The expected seal is:

      e4d75c6a779adee5850192d1ecc162ca0c85e960cb00d9923879609f89739152
    
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", "automaticResponseUrl" :
    "https://automatic-response-url.fr/", "captureDay": "0", "captureMode":
    "AUTHOR_CAPTURE", "currencyCode": "978", "interfaceVersion": "IR_MB_1.4",
    "keyVersion": "1", "merchantId": "011223344550000", "sdkOperationName":
    "CARDORDER", "sdkVersion": "SDK100", "transactionReference":
    "TREFEXA2012", "seal":
    "c1d8cb38e65d68ad213bfb042873b17381a5d8c5e460813ab594396498386ca8"
    }
    

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

      2500https://automatic-response-url.fr/0AUTHOR_CAPTURE978IR_MB_1.4011223344550000CARDORDERSDK100TREFEXA2012
    

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

      secret123
    

The expected seal is:

      c1d8cb38e65d68ad213bfb042873b17381a5d8c5e460813ab594396498386ca8
    

Populating the fields of the orderInitialize request

Generic fields

Field Presence As of Version Comments
amount Mandatory IR_MB 1.0
automaticResponseUrl Optional IR_MB 1.0
captureDay Optional IR_MB 1.0
captureMode Optional IR_MB 1.0
currencyCode Mandatory IR_MB 1.0
customerEmail Optional IR_MB 1.0
customerId Optional IR_MB 1.0
customerLanguage Optional IR_MB 1.0
interfaceVersion Mandatory IR_MB 1.0
merchantId Mandatory IR_MB 1.0
merchantWalletId Optional IR_MB 1.0
orderId Optional IR_MB 1.0
paymentMeanBrand Optional IR_MB 1.0
paymentPattern Optional IR_MB 1.0
responseKeyVersion Optional IR_MB 1.0
returnContext Optional IR_MB 1.0
sdkOperationName Mandatory IR_MB 1.0 CARDORDER or WALLETORDER or PAYMENTPROVIDERORDER or THREEDSECUREANDORDER
sdkVersion Optional IR_MB 1.0 Value set at SDK100
transactionReference Conditional IR_MB 1.0 Mandatory if you do not use the s10TransactionReference, depending on your merchant configuration
invoiceReference Optional IR_MB 1.0
statementReference Optional IR_MB 1.0
intermediateServiceProviderId Optional IR_MB 1.2
seal Mandatory IR_MB 1.2
keyVersion Mandatory IR_MB 1.2
sealAlgorithm Optional IR_MB 1.2
paymentMeanBrandSelectionStatus Optional IR_MB 1.2
s10TransactionReference Conditional IR_MB 1.3 Mandatory if you do not use the transactionReference, depending on your merchant configuration. See the Containers part
responseEncoding Optional IR_MB 1.5

Optional fields pertaining to transactionId Sips 1.0

Content of s10TransactionReference :

Field Presence Version Comments
s10TransactionId Facultatif MB_1.3
s10TransactionIdDate Facultatif MB_1.3 This field is computed by our server. There is no need to set a value in this field (as it will be ignored if set).

Retrieving the response fields

Field As from version Comments
publicKeyValue MB_1.0
redirectionData MB_1.0
redirectionStatusCode MB_1.0
redirectionStatusMessage* MB_1.0
redirectionUrl MB_1.0
redirectionVersion MB_1.0
Seal MB_1.0

  • Sample response to an orderInitialize request:
      {"publicKeyValue":"30820122…10001","redirectionData":"4AgbsrffvP…dfx9mCns9Z3E","redirectionStatusCode":"00","redirectionStatusMessage":"Validation succeed","redirectionUrl":"https://office-server.sips-atos.com/rs-services/v2/checkoutInApp/cardOrder","redirectionVersion":"IR_MB_1.0","seal":"0abbfebf740b09993ac36a9173a791
809b7fd6c4cc40df8695f56695ad815dda"}
    

Processing initialisation errors

The Sips server checks each field received individually. The following list contains the error codes that can be returned during the verification step, as well as the solutions to be implemented.

redirectionStatusCode Description
00 Standard situation followed by standard call process to the cardOrder function.
03 The merchant ID or acquirer contract are not correct.
12 The transaction parameters are not correct. Check the request parameters (the error is indicated in the redirectionStatusMessage ).
30 The request format is not correct (the error is indicated in the redirectionStatusMessage ).
34 Security issue: for example the calculated seal is not correct.
94 The transaction already exists.
99 Service temporarily unavailable.

4 cases are possible:

  • redirectionStatusCode  = 00

This case must be followed by the call to the cardOrder function by the mobile.

  • redirectionStatusCode  = 03, 12, 30, 34

These error codes indicate that the request has an issue that must be resolved. The payment process must then be interrupted.

  • redirectionStatusCode  = 94

The transaction reference has already been used. You must try again with another transaction reference.

  • redirectionStatusCode  = 99

Payment service availability issue. You must try to resend the request. A new transaction reference should be used to avoid a 94 response code.

Importing the SDK into an Android project

To use this library in your Java application, add the JAR of the SDK to the project compilation folder.

Example with Eclipse IDE:

  • right-click on your project;
    • select Properties
    • click on Java Build Path
    • click on Add JARS in the Libraries folder
    • select the JAR of the SDK then click on OK.

To use this library in your Android Studio and Gradle applications, add the AAR file of the SDK to the libs folder.

Example with Android Studio:

  • in the build.gradle file, add the following code to the repositories section.
        flatDir {
   dirs 'libs'
}
      
  • add the following dependencies:
      compile(name: 'wl-sips-inapp-sdk-1.4.0', ext: 'aar')
compile 'com.google.code.gson:gson:2.2.2'
compile 'com.squareup.okhttp3:okhttp:3.9.1'
compile 'com.google.guava:guava:16.0.1'
    

Manifest permissions

Add the following entries to the Android manifest of the application:

          <uses-permission android:name="android.permission.INTERNET"/>
    <uses-permission android:name="android.permission.READ_PHONE_STATE"/>
    <uses-permission android:name="android.permission.GET_ACCOUNTS"/>
    
Note: the GET_ACCOUNTS and READ_PHONE_STATE permissions are optional.

The SDK needs these permissions to retrieve the telephone information:

Device information As from version Comments
Android ID 1.0
Debugger detector 1.0
Device name 1.0
E-mail address 1.0
Emulator detector 1.0
Service provider 1.0
Rooted telephone 1.0
SIM serial number 1.0
Hash of the SSL library 1.0
Hash of System Core 1.0
Hash of the In-App SDK 1.0
Hash of the WebKit library 1.0
Blacklisted applications 1.0
IMEI 1.0
Screen switched on? 1.0

Importing the SDK into an iOS project

The SDK is published in the form of a framework file.

Simply drag and drop the InAppSdk.framework file into your poroject to import it.

Linking the binary with libraries

In your project, you must link the SDK file.

To do this, in XCode:

  • click on your project
    • click on your target application
    • click on the Build phases tab
    • expand the Link Binary With Libraries section
      • click on the " + " symbol
      • select the InAppSdk.framework file

This is sometimes done automatically.

Linking embedded binaries

In your merchant project, you must link embedded binaries.

To do this, in XCode :click on your project

    • click on your target application,
    • click on the General tab
    • in the Embedded Binaries section:
      • click on the " + " symbol
      • select the InAppSdk.framework file

You should have the following configuration:

Validating mobile-side payment withAndroid

All the necessary methods are in the PaymentManager public class.

Note: these methods carry out network calls, so they must be called asynchronously.

cardOrder function

This function is used to carry out a card payment. It is called after the orderInitialize initialisation request on your server with sdkOperationName=CARDORDER .

cardOrder request format

Parameters Type Comments
context Context Android context
cardNumber String Card number
cardCSCValue String Security code
cardExpiryDate String Expiry date
paymentMeanBrand String Selected payment means
paymentMeanBrandSelectionStatus String Payment means selection status
publicKeyValue String Encrypted value of the public key Retrieved from the initialisation request
redirectionData String Unique token containing the context of the transaction
redirectionUrl String URL address provided on completion of orderInitialize
redirectionVersion String Interface version

Format of the response via the OrderResponse object

Field name Format Comment
acquirerResponseCode String
amount String
authorisationId String
captureDay String
captureMode String
cardExpiryDate String (yyyyMM)
currencyCode String
customerId String
errorFieldName String
inAppResponseCode String
invoiceReference String
maskedPan String
merchantId String
merchantWalletId String
orderChannel String
orderId String
panEntryMode String
paymentMeanBrand String
paymentMeanBrandSelectionStatus String
paymentMeanType String
paymentPattern String
returnContext String
s10TransactionReference S10TransactionReference
statementReference String
transactionDateTime Date
transactionOrigin String
transactionPlatform String
transactionReference String
walletType String
issuerWalletInformation String

Optional fields pertaining to transactionId Sips 1.0

Content of s10TransactionReference  :

Field Presence Comments
s10TransactionId String
s10TransactionIdDate String This field is computed by our server. There is no need to set a value in this field (as it will be ignored if set).

walletOrder function

This function is used to carry out a wallet payment. It is called after the orderInitialize initialisation request on your server with sdkOperationName=WALLETORDER .

walletOrder request format

Parameters Type Comments
context Context Android context
paymentMeanId Integer ID of the selected card
redirectionVersion String Interface version
cardCSCValue String Security code (optional)
publicKeyValue String Encrypted value of the public key Retrieved from the initialisation request
redirectionData String Unique token containing the context of the transaction
redirectionUrl String M2M URL address

Format of the response via the OrderResponse object

Field name Format Comment
acquirerResponseCode String
amount String
authorisationId String
captureDay String
captureMode String
cardExpiryDate String (yyyyMM)
currencyCode String
customerId String
errorFieldName String
inAppResponseCode String
invoiceReference String
maskedPan String
merchantId String
merchantWalletId String
orderChannel String
orderId String
panEntryMode String
paymentMeanBrand String
paymentMeanBrandSelectionStatus String
paymentMeanType String
paymentPattern String
returnContext String
s10TransactionReference S10TransactionReference
statementReference String
transactionDateTime Date
transactionOrigin String
transactionPlatform String
transactionReference String
walletType String
issuerWalletInformation String

paymentProviderOrder function

This function is used to carry out a BCMC payment and get the BCMC Intent URL to be called. The function is called after the orderInitialize initialisation request on your server with sdkOperationName=PAYMENTPROVIDERORDER and paymentMeanBrand=BCMCMOBILE .

paymentProviderOrder request format

Parameters Type Comments
context Context Android context
publicKeyValue String Encrypted value of the public key Retrieved from the initialisation request
redirectionData String Unique token containing the context of the transaction
redirectionUrl String M2M URL address
redirectionVersion String Interface version

Format of the response via the paymentProviderOrderResponse request

Field name Format Description
outerRedirectionUrl String URL Intent aimed at waking up the BCMC application
errorFieldName String Name of the field causing the error
inAppResponseCode String Sips response code
redirectionUrl String Redirection URL for next call
transactionContextData String Transaction context
transactionContextVersion String Transaction context version

getTransactionData function

This function is used to check the status of the BCMC transaction after the BCMC application has been called. The function is called following a call to paymentProviderOrder , when the BCMC application calls the merchant application again.

getTransactionData request format

Parameters Type Comments
context Context Android context
transactionContextData String Unique token containing the context of the transaction Retrieved from the paymentProviderOrder request
transactionContextVersion String Version of the transaction context
redirectionUrl String M2M URL address

Format of the response via the getTransactionDataResponse response

Field name Format Description
acquirerResponseCode String Acquirer response code
originAmount String Transaction amount
authorisationId String Authorisation ID
captureLimitDate String Capture limit date
captureMode String Capture mode
panExpiryDate String (yyyyMM) Card expiry date
currencyCode String Currency code
customerId String
errorFieldName String Name of the field causing the error
inAppResponseCode String Sips server response code
invoiceReference String
maskedPan String Masked card number
merchantId String Merchant ID
orderChannel String Order channel
orderId String Order ID
panEntryMode String
paymentMeanBrand String Payment mean brand
paymentMeanType String
paymentPattern String Payment method (simple, recurring, etc.)
s10TransactionReference INAPPS10TransactionReference
statementReference String
transactionDateTime Date
transactionReference String Transaction ID
transactionStatus String
holderAuthentProgram String Available values: SUCCESS / ATTEMPT
holderAuthentMethod String Available values: PASSWORD / NOT_SPECIFIED / OTP_SMS
holderAuthentStatus String
walletType String Wallet type

cardCheckEnrollment function

This function is used to prepare a 3-D Secure payment and to get the paReq (Payer Authentication Request) message and the URL of the 'ACS (Access Control Server) to be called. The function is called after the orderInitialize initialisation request on your server with sdkOperationName=THREEDSECUREANDORDER .

cardCheckEnrollment request format

Parameters Type Comments
context Context Android context
cardNumber String Card number
cardCSCValue String Security code
cardExpiryDate String Expiry date
paymentMeanBrand String Card brand
paymentMeanBrandSelectionStatus String Card brand selection status
publicKeyValue String Encrypted value of the public key Retrieved from the initialisation request
redirectionData String Unique token containing the context of the transaction
redirectionUrl String M2M URL address
redirectionVersion String Interface version

Format of the response via the checkEnrollmentResponse object

Field name Format Description
authentRedirectionUrl String ACS redirection URL
errorFieldName String Name of the field causing the error
redirectionStatusCode String Sips response code
paReqMessage String PaReq message used ACS authentication
redirectionUrl String Redirection URL for next call
transactionContextData String Transaction context
transactionContextVersion String Transaction context version

Depending on this response, your application must redirect to the ACS by calling the authentRedirectionUrl received with POST parameters:

  • PaReq message returned by the cardCheckEnrollment function in the paReqMessage field.
  • MD (Merchant Data): this field contains merchant status data that must be returned to the merchant. This field must be used to retrieve the session on your website.
  • TermUrl : the merchant URL the final response is to be sent to following end user authentication ( PaRes and MD response fields). This must be a URL of your website the end user must be redirected to.

On Android, an Android function can be called in a WebView from JavaScript code. Therefore, TermUrl can be a webpage that pushes the received POST fields to the Android application of the merchant, using a JavascriptInterface method.

Sample Acs WebViewActivity that gets the PaRes from an ACS authentication:

      public class AcsWebViewActivity extends Activity {
  public static final String EXTRA_ACS_URL = "EXTRA_ACS_URL";
  public static final String EXTRA_PARES = "EXTRA_PARES";
  public static final String EXTRA_PAREQ = "EXTRA_PAREQ";
  public static final String EXTRA_MD = "EXTRA_MD";
  private WebView webView;
  final Handler myHandler = new Handler();

  public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_acs_web_view);

    final JavaScriptInterface myJavaScriptInterface = new JavaScriptInterface();

    webView = (WebView) findViewById(R.id.webView);
    webView.getSettings().setJavaScriptEnabled(true);
    webView.addJavascriptInterface(myJavaScriptInterface, "AndroidFunction");
    webView.getSettings().setLoadWithOverviewMode(true);
    webView.setWebViewClient(new WebViewClient() {
       @Override
       public boolean shouldOverrideUrlLoading(WebView  view, String  url) {
         return false;
        }
    });
    
    String data = "<script>window.onload = function(){"
        + "document.forms['acs'].submit();}</script>"
        + "Please wait..."
        + "<form method=\"POST\" name=\"acs\" action=\"" + getIntent().getStringExtra(EXTRA_ACS_URL) + "\" style=\"display:none;\">"
        + "<input type=\"text\" name=\"MD\" value=\"" + getIntent().getStringExtra(EXTRA_MD) + "\">"
        + "<input type=\"text\" name=\"TermUrl\" value=\"http://inappmerchantserverdemo-mobilepayments.apps.zone52.org/displayAcsResponse.jsp\">"
        + "<input type=\"text\" name=\"PaReq\" value=\"" + getIntent().getStringExtra(EXTRA_PAREQ) + "\">"
        + "<input type=\"submit\" value=\"Submit\">" 
        + "</form>";
    webView.loadDataWithBaseURL(null, data, "text/html", "utf-8", null);
  }

  public class JavaScriptInterface {

    @JavascriptInterface
    public void putPaRes(String paRes) {
      // Url encode algorithm to apply on the pares received
      // Call cardValidateAuthentication with paRes message encoded
    }
  }
}
    

cardValidateAuthenticationAndOrder function

This function is used to validate the ACS authentication. The function is called following a call to cardCheckEnrollment , when the 'ACS returns the PaRes message. The "URL encode" algorithm must be applied to the PaRes message before the latter is supplied to the SDK.

cardValidateAuthenticationAndOrder request format

Parameters Type Commentss
context Context Android context
paResMessage String Customer authentication response. The default "Url Encode" algorithm must be applied to the paResMessage field received from the ACS.
transactionContextData String Unique token containing the transaction context Retrieved from the cardCheckEnrollment request
transactionContextVersion String Transaction context version
redirectionUrl String M2M URL address

Format of the response via the OrderResponse object

Field name Format Comment
acquirerResponseCode String
amount String
authorisationId String
captureDay String
captureMode String
cardExpiryDate String (yyyyMM)
currencyCode String
customerId String
errorFieldName String
inAppResponseCode String
invoiceReference String
maskedPan String
merchantId String
merchantWalletId String
orderChannel String
orderId String
panEntryMode String
paymentMeanBrand String
paymentMeanBrandSelectionStatus String
paymentMeanType String
paymentPattern String
returnContext String
s10TransactionReference S10TransactionReference
statementReference String
transactionDateTime Date
transactionOrigin String
transactionPlatform String
transactionReference String
walletType String
issuerWalletInformation String

Validating mobile-side payment with iOS

All the necessary methods are in the InAppSdk public class.

Note: unlike the Android version of the SDK, on the iOS version the asynchronism is managed within the SDK itself. There is therefore no need to to call these functions asynchronously, the response is received using a handler at the end of the call.

cardOrder function

This function is used to carry out a card payment. It is called after the orderInitialize initialisation request on your server with sdkOperationName=CARDORDER .

cardOrder request format

Parameters Type Comments
cardNumber NSString Card number
cardCSCValue NSString Security code
cardExpiryDate NSString Expiry date
paymentMeanBrand NSString Payment mean brand
paymentMeanBrandSelectionStatus NSString Payment mean brand selection status
publicKeyValue NSString Encrypted value of the public key Retrieved from the initialisation request
redirectionData NSString Unique token containing the transaction context
redirectionUrl NSString M2M URL address
redirectionVersion NSString Interface version
handler void (^)(INAPPOrderResponse * response) Handler supplied at the end of the call

Format of the response via the INAPPOrderResponse object

Field name Format Description
acquirerResponseCode NSString Acquirer response code
amount NSString Transaction amount
authorisationId NSString Authorisation ID
captureDay NSString Capture limit date
captureMode NSString Capture mode
cardExpiryDate NSString (yyyyMM) Card expiry date
currencyCode NSString Currency code
customerId NSString
errorFieldName NSString Name of the field causing the error
inAppResponseCode NSString Sips server response code
invoiceReference NSString
maskedPan NSString Masked card number
merchantId NSString Merchant ID
merchantWalletId NSString Merchant wallet ID
orderChannel NSString Order channel
orderId NSString Order ID
panEntryMode NSString
paymentMeanBrand NSString Selected payment mean brand
paymentMeanBrandSelectionStatus NSString
paymentMeanType NSString
paymentPattern NSString
returnContext NSString
s10TransactionReference INAPPS10TransactionReference
statementReference NSString
transactionDateTime NSString
transactionOrigin NSString Transaction origin
transactionPlatform NSString Future usage (currently systematically set to ‘PROD’)
transactionReference NSString Transaction ID
walletType NSString
issuerWalletInformation NSString

walletOrder function

This function is used to carry out a wallet payment. It is called after the orderInitialize initialisation request on your server with sdkOperationName=WALLETORDER .

walletOrder request format

Parameters Type Comments
paymentMeanId NSInteger ID of the selected card
cscValue NSString Confidential code (optional)
redirectionVersion NSString Interface version
publicKeyValue NSString Encrypted value of the public key Retrieved from the initialisation request
redirectionData NSString Unique token containing the transaction context
redirectionUrl NSString M2M URL address
handler void (^)(INAPPOrderResponse * response) Handler supplied at the end of the call

Format of the response via the INAPPOrderResponse object

Field name Format Description
acquirerResponseCode NSString Acquirer response code
amount NSString Transaction amount
authorisationId NSString Authorisation ID
captureDay NSString Capture limit date
captureMode NSString Capture mode
cardExpiryDate NSString (yyyyMM) Card expiry date
currencyCode NSString Currency code
customerId NSString
errorFieldName NSString Name of the field causing the error
inAppResponseCode NSString Sips server response code
invoiceReference NSString
maskedPan NSString Masked card number
merchantId NSString Merchant ID
merchantWalletId NSString Merchant wallet ID
orderChannel NSString Order channel
orderId NSString Order ID
panEntryMode NSString
paymentMeanBrand NSString Selected payment mean brand
paymentMeanBrandSelectionStatus NSString
paymentMeanType NSString
paymentPattern NSString
returnContext NSString
s10TransactionReference INAPPS10TransactionReference
statementReference NSString
transactionDateTime NSString
transactionOrigin NSString Transaction origin
transactionPlatform NSString Future usage (currently systematically set to ‘PROD’)
transactionReference NSString Transaction ID
walletType NSString
issuerWalletInformation NSString

paymentProviderOrder function

This function is used to carry out a BCMC payment and to get the Intent BCMC URL to be called. The function is called after the orderInitialize initialisation request on your server with sdkOperationName=PAYMENTPROVIDERORDER and paymentMeanBrand=BCMCMOBILE .

paymentProviderOrder request format

Parameters Type Comments
publicKeyValue NSString Encrypted value of the public key Retrieved from the initialisation request
redirectionData NSString Unique token containing the transaction context
redirectionUrl NSString M2M URL address
redirectionVersion NSString Interface version
handler void (^)(void (^)(INAPPPaymentProviderResponse * response)) Handler supplied at the end of the call

Format of the response via the INAPPPaymentProviderOrderResponse object

Field name Format Description
outerRedirectionUrl NSString URL Intent aimed at waking up the BCMC application
errorFieldName NSString Name of the field causing the error
inAppResponseCode NSString Sips response code
redirectionUrl NSString Redirection URL for next call
transactionContextData NSString Transaction context
transactionContextVersion NSString Transaction context version

getTransactionData function

This function is used to check the BCMC transaction status after the BCMC application has been called. The function is called after a call to paymentProviderOrder , when the BCMC application calls the merchant application again.

getTransactionData request format

Parameters Type Comments
transactionContextData NSString Unique token containing the transaction context Retrieved from the paymentProviderOrder request
transactionContextVersion NSString Transaction context version
redirectionUrl NSString M2M URL address
handler void (^)(INAPPGetTransactionDataResponse * response) Handler supplied at the end of the call

Format of the response via the INAPPGetTransactionDataResponse object

Field name Format Description
acquirerResponseCode NSString Acquirer response code
originAmount NSString Transaction amount
authorisationId NSString Authorisation ID
captureLimitDate NSString Capture limit date
captureMode NSString Capture mode
panExpiryDate NSString (yyyyMM) Card expiry date
currencyCode NSString Currency code
customerId NSString
errorFieldName NSString Name of the field causing the error
inAppResponseCode NSString Sips server response code
invoiceReference NSString
maskedPan NSString Masked card number
merchantId NSString Merchant ID
orderChannel NSString Order channel
orderId NSString Order ID
panEntryMode NSString
paymentMeanBrand NSString Selected payment mean brand
paymentMeanType NSString
paymentPattern NSString
s10TransactionReference INAPPS10TransactionReference
statementReference NSString
transactionDateTime NSString
transactionReference NSString Transaction ID
transactionStatus NSString
holderAuthentProgram NSString Available values: SUCCESS / ATTEMPT
holderAuthentMethod NSString Available values: PASSWORD / NOT_SPECIFIED / OTP_SMS
holderAuthentStatus NSString
walletType NSString Wallet type

cardCheckEnrollment function

This function is used to prepare a 3-D Secure payment and to get the paReq (Payer Authentication Request) message and the ACS (Access Control Server) URL to be called. The function is called after the orderInitialize initialisation request on your server with sdkOperationName=THREEDSECUREANDORDER .

cardCheckEnrollment request format

Parameters Type Comments
cardNumber NSString Card number
cardCSCValue NSString Confidential code
cardExpiryDate NSString Expiry date
paymentMeanBrand String Selected payment mean brand
paymentMeanBrandSelectionStatus String Payment mean brand selection status
publicKeyValue NSString Encrypted value of the public key Retrieved from the initialisation request
redirectionData NSString Unique token containing the transaction context
redirectionUrl NSString M2M URL address
redirectionVersion NSString Interface version
handler void (^)(INAPPCheckEnrollmentResponse * response) Handler supplied at the end of the call

Format of the response via theINAPPCardCheckEnrollmentResponse object

Field name Format Description
authentRedirectionUrl NSString ACS redirection URL
errorFieldName NSString Name of the field causing the error
redirectionStatusCode NSString Sips response code
paReqMessage NSString PaReq message used for the ACS authentication
redirectionUrl NSString Redirection URL for next call
transactionContextData NSString Transaction context
transactionContextVersion NSString Transaction context version

Depending on this response, your application must redirect to the ACS by calling the authentRedirectionUrl received with POST parameters:

  • PaReq message returned by the cardCheckEnrollment function in the paReqMessage field.
  • MD (Merchant Data) : this field contains merchant status data that must be returned to the merchant. This field must be used to retrieve the session on your website.
  • TermUrl : the merchant URL the final response is to be sent to following end user authentication ( PaRes and MD response fields). This must be a URL of your website the end user must be redirected to.

On iOS, a function can be called in a UIWebView from JavaScript code. Therefore, TermUrl can be a merchant webpage that pushes the received POST fields to the iOS application of the merchant, using a UIWebViewDelegate shouldStartloadWithRequest method.

Sample Acs WebViewController that gets the PaRes from an ACS authentication:

      @implementation MERCHANTAPPAcsWebViewController

- (void)viewDidLoad {
    [super viewDidLoad];   
    self.webView.delegate = self;     
    NSMutableString *s = [NSMutableString stringWithCapacity:0];
    [s appendString: [NSString stringWithFormat:@"<html><body onload=\"document.forms[0].submit()\">"
                      "<form method=\"post\" action=\"%@\">", self.acsUrl]];
    if([self.acsPostParams count] % 2 == 1) { NSLog(@"UIWebViewWithPost error: params don't seem right"); return; }
    for (int i=0; i < [self.acsPostParams count] / 2; i++) {
        [s appendString: [NSString stringWithFormat:@"<input type=\"hidden\" name=\"%@\" value=\"%@\" >\n", [self.acsPostParams objectAtIndex:i*2], [self.acsPostParams objectAtIndex:(i*2)+1]]];
    }
    [s appendString: @"</input></form></body></html>"];
    [self.webView loadHTMLString:s baseURL:nil];
}

// This function is called on all location change :
- (BOOL)webView:(UIWebView *)webView2 shouldStartLoadWithRequest:(NSURLRequest *)request navigationType:(UIWebViewNavigationType)navigationType {
    
    // Intercept custom location change, URL begins with “putpares l:"
    if ([[[request URL] absoluteString] hasPrefix:@"putpares:"]) {
        
        // Extract the selector name from the URL
        NSArray *components = [[[request URL] absoluteString] componentsSeparatedByString:@":"];
        NSString * paRes = [components objectAtIndex:1];
        NSLog(@"paRes : %@", paRes);
        
        [UIApplication sharedApplication].networkActivityIndicatorVisible = YES;
        UIAlertView *alert = [[UIAlertView alloc] initWithTitle:[[NSBundle mainBundle] localizedStringForKey:@"wait" value:@"" table:nil] message:@"" delegate:nil cancelButtonTitle:nil otherButtonTitles:nil];
        [alert show];
        
        [InAppSdk
         cardValidateAuthenticationAndOrderWithPaResMessage:paRes
         andTransactionContextData:self.transactionContextData
         andRedirectionUrl:self.redirectionUrl
         andTransactionContextVersion:self.transactionContextVersion
         andHandler:^(NSDictionary *result) {
             //Do something with cardValidateAuthentication response
         }];
        // Cancel the location change
        return NO;
    }    
    // Accept this location change
    return YES;    
}

@end
    

cardValidateAuthenticationAndOrder function

This function is used to validate authentication after authentication by the 'ACS. The function is called following a call to cardCheckEnrollment , when the ACS returns the PaRes message. The "URL encode" algorithm must be applied to the PaRes  message before the latter is supplied to the SDK. The function returns an INAPPOrderResponse object.

cardValidateAuthenticationAndOrder request format

Parameters Type Comments
paResMessage NSString Customer authentication response. The default "URL encode" algorithm must be pplied to the paResMessage field received from the ACS.
transactionContextData NSString Unique token containing the transaction context Retrieved from the cardCheckEnrollment request
transactionContextVersion NSString Transaction context version
redirectionUrl NSString M2M URL address
handler void (^)(INAPPOrderResponse * response) Handler supplied at the end of the call

Processing the payment response server-side

The response is an HTTP(S) POST response sent to the automaticResponseUrl  URL (optional) specified in the request.

You must set up the system that will decode this response so you can know the payment outcome.

The following four data elements are defined in the responses:

Field name Comments/rules
Data Fields concatenation in the response
Encode Type of encoding used to encode the Data field
Seal Response message signature
InterfaceVersion Connector interface version

If the value of the Encode field is "base64" or "base64url", the Data field should be decoded in Base64/Base64Url to obtain the concatenated string of fields.

The concatenated string is structured as follows: key1=value1|key2=value2, etc.

The seal ( Seal field) of both responses is hashed with the same algorithm as the one supplied as input in the sealAlgorithm field. If no value was defined, SHA-256 is used by default.

Note: for a seal to be computed with the HMAC-SHA-256 algorithm, the input parameters of the request must include the sealAlgorithm field populated with the following value: “HMAC-SHA-256”.

The value of the Seal field is computed as follows:

For the HMAC-SHA algorithm:

  • use of the shared secret key to generate the HMAC variant of the message
  • use of the Data field only (encoded if the corresponding option is selected)
  • UTF-8 encoding of the data constituting the result of the previous operation
  • HMAC-SHA hashing of the bytes obtained

This procedure can be summarised as follows:

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

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

  • concatenation of the Data field and of the secret key (encoded if the corresponding option is selected)
  • UTF-8 encoding of the data constituting the result of the previous operation
  • SHA256 hashing of the bytes obtained

This procedure can be summarised as follows:

      SHA256( UTF-8(Data+secretKey ) )
    

Providing the response URL

The main objective of the response with the payment outcome is to let you know what happened on the customer's mobile.

The response is sent only if the automaticResponseUrl field has been sent in the payment request to your server. If this is the case, the Sips server sends an HTTP(S) POST response to the received URL address.

It is your responsibility to retrieve the various data from the response, to check the signature so as to ensure the integrity of the response fields and, consequently, to update your back office.

Note: the current version of InterfaceVersion is HP_ 2.27 . Please refer to the Sips data dictionary for a comprehensive description of the parameters included in the response.

Retrieving the response fields

The content of the response may vary depending on the payment outcome (successful or other).

Field name As from version Comments
acquirerNativeResponseCode HP_2.12
acquirerResponseCode HP_1.0
acquirerResponseIdentifier HP_2.8
acquirerResponseMessage HP_2.8
additionalAuthorisationNumber HP_2.8
amount HP_1.0 Value submitted in the payment request
authorisationId HP_1.0
captureDay HP_1.0 Value submitted in the payment request
captureLimitDate HP_1.0
captureMode HP_2.0 Value submitted in the payment request
cardCSCResultCode HP_1.0
cardProductCode HP_2.12
cardProductName HP_2.12
cardProductProfile HP_2.12
complementaryCode* HP_2.0
complementaryInfo* HP_1.0
creditorId HP_2.7
currencyCode HP_2.0 Value submitted in the payment request
customerEmail HP_2.0 Value submitted in the payment request. Available in the HP_2.0 version only
customerId HP_2.0 Value submitted in the payment request
customerIpAddress HP_2.1 Value submitted in the payment request
customerMobilePhone HP_2.0 Value submitted in the payment request. Available in the HP_2.1 version only
dccAmount HP_2.0
dccCurrencyCode HP_2.0
dccExchangeRate HP_2.0
dccExchangeRateValidity HP_2.0
dccProvider HP_2.0
dccStatus HP_2.0
dccResponseCode HP_2.0
guarantheeIndicator HP_2.0
hashPan1 HP_2.0
hashPan2 HP_2.0
holderAuthentMethod* HP_2.0
holderAuthentProgram HP_2.5
holderAuthentRelegation* HP_2.0
holderAuthentStatus* HP_2.0
instalmentAmountsList HP_2.6
instalmentDatesList HP_2.6
instalmentNumber HP_2.6
instalmentTransactionReferencesList HP_2.6
interfaceVersion* HP_2.0
invoiceReference HP_2.10
issuerCode HP_2.12
issuerCountryCode HP_2.12
issuerEnrollementIndicator* HP_2.1
issuerWalletInformation HP_2.9
keyVersion HP_2.0 Value submitted in the payment request
mandateAuthentMethod HP_2.0
mandateCertificationType HP_2.7
mandateId HP_2.0
mandateUsage HP_2.0
maskedPan* HP_2.0
merchantId HP_1.0 Value submitted in the payment request
merchantSessionId HP_2.0 Value submitted in the payment request
merchantTransactionDateTime HP_2.0 Value submitted in the payment request
merchantWalletID HP_2.0 Value submitted in the payment request
orderChannel HP_2.0 Value submitted in the payment request
orderId HP_1.0 Value submitted in the payment request
panEntryMode* HP_2.0
panExpiryDate* HP_1.0
paymentMeanBrand* HP_2.2
paymentMeanBrandSelectionStatus HP_2.14
paymentMeanData* HP_1.0
paymentMeanId HP_2.6
paymentMeanTradingName HP_2.8
paymentMeanType* HP_2.0
paymentPattern HP_1.0 Value submitted in the payment request
preAuthenticationColor HP_2.10
preAuthenticationInfo HP_2.10
preAuthenticationProfile HP_2.10
preAuthenticationProfileValue HP_2.14
preAuthenticationRuleResultList HP_2.14 Liste of ruleResult objects. Please see below.
preAuthenticationThreshold HP_2.10
preAuthenticationValue HP_2.10
preAuthorisationProfile HP_2.14
preAuthorisationProfileValue HP_2.14
preAuthorisationRuleResultList HP_2.14 Liste of ruleResult objects. Please see below.
responseCode HP_1.0
returnContext HP_2.0 Value submitted in the payment request
s10TransactionId HP_2.9
s10TransactionIdDate HP_2.9
scoreColor* HP_2.0
scoreInfo* HP_2.0
scoreProfile* HP_2.0
scoreThreshold* HP_2.0
scoreValue* HP_1.0
settlementMode HP_2.7
settlementModeComplement HP_2.13
statementReference* HP_2.0
tokenPan* HP_2.0
transactionActors HP_2.2 Value submitted in the payment request
transactionDateTime HP_1.0
transactionOrigin HP_2.0 Value submitted in the payment request
transactionPlatform HP_2.16 Future usage (currently systematically set to ‘PROD’)
transactionReference HP_2.0 Value submitted in the payment request
walletType HP_2.2

* these fields are populated when they are available, depending on the transaction status and the selected payment method.

Optional fields pertaining to fraud checks

  • Content of ruleResult
Field Version Comments
ruleCode HP_2.14
ruleType HP_2.14
ruleWeight HP_2.14
ruleSetting HP_2.14
ruleResultIndicator HP_2.14
ruleDetailedInfo HP_2.14

Format of complex lists

The format of a list of complex objects in the automatic and manual responses is defined as follows ( bold text ):

      ..|amount=1000|currencyCode=978|      objectNameList=[{"field1":"value1a",
"field2":"value2a","field3":"value3a"…},{"field1":"value1b",
"field2":"value2b","field3":"value3b"}…]|transactionReference=1452687287828
|..
    
  • The content of the list is in square brackets [ ] .
  • Each entry of the list is in curly brackets { } .
  • Each list entry field is represented as "fieldName" = "fieldValue" .
  • Please note that the name and the value of the field are both in double quotes "" .
  • Pairs of adjacent names/values are separated by a comma .

Sample 10 euros payment with a fraud result

      amount=1000|currencyCode=978|preAuthenticationRuleResultList=[{“ruleDetailedInfo”:"SHIP_ZIP=A;BILL_ZIP=B",”ruleCode”:"A",”ruleType”:"BBB"},{“ruleDetailedInfo”:"SHIP_ZIP=C;BILL_ZIP=D",”ruleCode”:"A",”ruleType”:"BBB"}]|transactionReference=1452687287828
    

Analysing the payment response

If you carry out the authentication steps by means of an electronic seal, you should make sure the seal you received actually matches the seal you recomputed using the response fields.

In case the seal you received does not match the seal you recomputed, the transaction status is considered unknown, please leave the transaction as it is, contact the support and do not re-execute the transaction in any automated way.

Status Response fields Action to be carried out
Paiement accepted

responseCode  = 00

acquirerResponseCode  = 00

garanteeIndicator  = Y,N,U, empty

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

Sips fraud refusal
Go-No-Go

responseCode  = 05

complementaryCode  = XX

preAuthorisationRuleResultList

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

Do not deliver the goods. Analyse in detail the fraud rules executed by Sips to know the reason for the refusal ( preAuthorisationRuleResultList field).

Sips fraud refusal

Business Score

responseCode  = 05

scoreColor  = RED, BLACK

scoreValue  = X (transaction score)

scoreThreshold  = X,Y (orange threshold, green threshold)

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

Do not deliver the goods. Analyse in detail the fraud rules executed by Sips to know the reason for the refusal ( preAuthorisationRuleResultList field).

Sips fraud warning

Business Score

responseCode  = 05

scoreColor  = ORANGE

scoreValue  = X (transaction score)

scoreThreshold  = X,Y (orange threshold, green threshold)

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

Analyse in detail the fraud rules executed by Sips to know the reason for the warning ( preAuthorisationRuleResultList field).

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

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

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

3-D Secure refusal

reponseCode  = 05

holderAuthenStatus  = FAILURE

Customer authentication failed. This is not necessarily due to fraud. You can suggest to your customer to attempt the payment again with another means of payment, by generating a new request.

Banking refusal from the acquirer

responseCode  = 05

acquirerResponseCode  = XX

Authorisation refused for a reason not related to fraud.

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

Soft decline

responseCode  = 05

acquirerResponseCode  = A1

The payment has been refused by the acquirer because the 3-D Secure data is missing in the authorisation request.
Please try to pay again with a 3-D Secure payment process.

Fraud refusal from the acquirer

responseCode  = 34

acquirerResponseCode = XX

Authorisation refused because of fraud.

Do not deliver the order.

Refusal due to a technical issue

responseCode  = 90, 99

acquirerResponseCode  = 90 to 98

Temporary technical issue while processing the transaction.

Please tell your customer to attempt the payment again later.

Step 3: managing the customer wallet

Generating the wallet initialisation request server-side

This service allows you to manage your customers' wallets, for example by adding a payment method to a wallet or retrieving existing wallet information.

The value of the interfaceVersion field must be set to IR_MB_ 1.6 .

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

Request syntax

The request is structured in compliance with the JSON format, like a payment initialisation request.

Sample wallet management request to add a card :

      {"automaticResponseUrl": "http://urlofautomaticresponse.jsp","interfaceVersion" : "IR_MB_1.3","keyVersion" : "2","merchantId" : "12345678912345","merchantWalletId" : "SIM01","sdkOperationName" : "GETWALLETDATA","sdkVersion" : "SDK100","seal" : "482e4a0f89ec528d167af3113ce1b80d2c70a1df55ac749c789136481216f012"}
    

Populating the request fields

Generic fields
Field Presence As of Version Comments
automaticResponseUrl Optional IR_MB 1.0 Future use
interfaceVersion Mandatory IR_MB 1.0
merchantId Mandatory IR_MB 1.0
merchantWalletId Mandatory IR_MB 1.0
responseKeyVersion Optional IR_MB 1.0
sdkOperationName Mandatory IR_MB 1.0 ADDCARD or GETWALLETDATA or DELETEPAYMENTMEAN
sdkVersion Optional IR_MB 1.0 Value set at SDK100
intermediateServiceProviderId Optional IR_MB 1.2
seal Mandatory IR_MB 1.2
keyVersion Mandatory IR_MB 1.2
sealAlgorithm Optional IR_MB 1.2

Retrieving the response fields

Field As of version Comments
publicKeyValue IR_MB 1.0
redirectionData IR_MB 1.0
redirectionStatusCode IR_MB 1.0
redirectionStatusMessage IR_MB 1.0
redirectionUrl IR_MB 1.0
redirectionVersion IR_MB 1.0

  • Sample response to a walletInitialize request :
      redirectionStatusMessage":"Wallet management session successfuly initialized","redirectionUrl":"https://office-server.test.sips-atos.com/rs-services/v2/walletInApp/getWalletData","redirectionVersion":"IR_MB_1.0","seal":
"55df26a55d6a07ee87d57dc5dd8be5ba9125501086e1c2ca702a3f5e074f1954"}
    

Processing wallet initialisation errors

All fields received through the Sips server are checked individually. The table below lists the error codes that can be examined and the solutions to be implemented.

redirectionStatusCode Description
00 Standard situation followed by the standard process used to display the wallet management pages.
03 The merchant ID is not correct.
12 The transaction parameters are not correct. Please check the request parameters (the error is indicated in the redirectionStatusMessage ).
30 The request format is not correct (the error is indicated in the redirectionStatusMessage ).
34 Security issue: e.g. the computed seal is not correct.
40 Unsupported function.
99 Service temporarily unavailable.

There are three possible situations:

  • redirectionStatusCode  = 00

The user must be redirected to the wallet management page.

  • redirectionStatusCode  = 03, 12, 30, 34, 40

These error codes indicate that the request has an issue that needs to be fixed. The payment process must be stopped.

  • redirectionStatusCode = 99

Wallet management service availability issue. Try to submit the request again.

Managing the wallet mobile-side with Android

Note: these methods perform network calls, so they must be called asynchronously.

getWalletData function

This function is used to retrieve cards saved in the wallet. The function is called after a walletInitialize command.

getWalletData request format

Parameters Type Comments
context Context Android context
publicKeyValue String Encrypted value of the public key Retrieved from the initialisation request
redirectionData String Unique token containing the transaction context
redirectionUrl String M2M URL address
redirectionVersion String Interface version

Format of the response via the getWalletDataResponse object

Field name Format Description
inAppResponseCode String Sips response code
errorFieldName String Name of the field causing the error
walletCreationDateTime String Wallet creation date
walletPaymentMeanData List of walletPaymentMeanData List of cards saved in the wallet

Format in the response of the walletPaymentMeanData object

Field name Format Description
panExpiryDate Date Card expiry date
paymentMeanAlias String Card alias
paymentMeanBrand String Card type
paymentMeanId Integer Payment method identifier
maskedPan String Masked card PAN

addCard function

This function is used to store a card in a wallet. It is called after a walletInitialize command.

addCard request format

Parameters Type Comments
context Context Android context
cardNumber String Card number
paymentMeanAlias String Card alias
cardExpiryDate String Expiry date
paymentMeanBrand String Card brand (e.g. VISA)
publicKeyValue String Encrypted value of the public key Retrieved from the initialisation request
redirectionData String Unique token containing the transaction context
redirectionUrl String M2M URL address
redirectionVersion String Interface version

Format of the response via the addCardResponse object

Parameters Type Comments
inAppResponseCode String Response code
errorFieldName String Name of the field causing the error
paymentMeanId String Payment method identifier
maskedPan String Masked card PAN
walletActionDateTime Date Date of addition to the wallet

deletePaymentMean function

This function is used to delete a card from a wallet. It is called after a walletInitialize command.

deletePaymentMean request format

Parameters Type Comments
context Context Android context
paymentMeanId String Payment mean ID to be deleted
publicKeyValue String Encrypted value of the public key Retrieved from the initialisation request
redirectionData String Unique token containing the transaction context
redirectionUrl String M2M URL address
redirectionVersion String Interface version

Format of the response via the deletePaymentMeanResponse object

Parameters Type Comments
inAppResponseCode String Response code
errorFieldName String Name of the field causing the error
walletActionDateTime Date Date of addition to the wallet

Managing the wallet mobile-side with iOS

Note: unlike the Android version of the SDK, on the iOS version the asynchronism is managed within the SDK itself. There is therefore no need to call these functions asynchronously, the response is received using a handler at the end of the call.

getWalletData function

This function is used to retrieve cards saved in the wallet. The function is called after a walletInitialize command.

getWalletData request format

Parameters Type Comments
redirectionVersion NSString Interface version
NSString NSString Encrypted value of the public key Retrieved from the initialisation request
redirectionData NSString Unique token containing the transaction context
redirectionUrl NSString M2M URL address
handler void (^)(INAPPGetWalletDataResponse * response) Handler supplied at the end of the call

Format of the response via the INAPPgetWalletDataResponse object

Parameters Type Comments
inAppResponseCode NSString Sips response code
errorFieldName NSString Name of the field causing the error
walletCreationDateTime NSString Wallet creation date
walletPaymentMeanData List of INAPPGetWalletDataResponseItem List of cards saved in the wallet

Format in the response of the walletPaymentMeanData object

Field name Format Description
panExpiryDate NSString Card expiry date
paymentMeanAlias NSString Card alias
paymentMeanBrand NSString Card type
paymentMeanId NSString Payment method identifier
maskedPan NSString Masked card PAN

addCard function

This function is used to store a card in a wallet. It is called after a walletInitialize command.

addCard request format

Parameters Type Comments
cardNumber NSString Card number
paymentMeanAlias NSString Card alias
cardExpiryDate NSString Expiry date
paymentMeanBrand NSString Card brand (e.g. VISA)
publicKeyValue NSString Encrypted value of the public key Retrieved from the initialisation request
redirectionData NSString Unique token containing the transaction context
redirectionUrl NSString M2M URL address
redirectionVersion NSString Interface version
handler void (^)(INAPPAddCardResponse * response) Handler supplied at the end of the call

Format of the response via the INAPPAddCardResponse object

Parameters Type Comments
inAppResponseCode String Response code
errorFieldName String Name of the field causing the error
paymentMeanId String Payment method identifier
maskedPan String Masked card PAN
walletActionDateTime Date Date of addition to the wallet

deletePaymentMean function

This function is used to delete a card from the wallet. The function is called after a walletInitialize command.

deletePaymentMean request format

Parameters Type Comments
paymentMeanId NSString Payment mean ID to be deleted
publicKeyValue NSString Encrypted value of the public key Retrieved from the initialisation request
redirectionData NSString Unique token containing the transaction context
redirectionUrl NSString M2M URL address
redirectionVersion NSString Interface version

Format of the response via the deletePaymentMeanResponse object

Parameters Type Comments
inAppResponseCode String Response code
errorFieldName String Name of the field causing the error
walletActionDateTime Date Date of addition to the wallet

Analysing the wallet management response

If you carry out the authentication steps by means of an electronic seal, you should make sure the seal you received actually matches the seal you recomputed using the response fields.

In case the seal you received does not match the seal you recomputed, the transaction status is considered unknown, please contact the support.

Status Response fields Action to be carried out
Wallet management operation taken into account walletLastActionDateTime populated with the date/time of the last action carried out on the wallet.

walletPaymentMeanDataList
contains the payment methods in the wallet after-update

Store the following wallet data in your customer database:
  • paymentMeanAlias
  • paymentMeanId
  • paymentMeanBrand
  • PanExpiryDate
  • maskedPan
Wallet management operation not taken into account walletLastActionDateTime not populated with current date/time

walletPaymentMeanDataList
contains the payment methods in the wallet

If the wallet update is required then submit a request again

Step 4: testing in the validation environment

The test and integration steps can be implemented using the test environment.

The URL for the test environment is:

Payment service name /rs-services/v2/checkoutInApp/orderInitialize
Wallet management service name /rs-services/v2/walletInApp/walletInitialize
Merchant ID 201040027570001
Key version 1
Secret key H6znJWqPj9cTRFe9eT62ulurkb_Lrksbw4PFtMSVb74

The authorisation process is simulated in the validation environment. This means you do not need to use real payment methods to carry out tests.

You can use the following VISA card to simulate an accepted payment:

test card see " Test cards " page
Security code 123
Validity date must be greater than the current month
Note:

The test shop is configured in "transactionReference mode", without automatic generation of the transactionReference . Therefore, you must set the transactionRefence field in your test requests.

Step 5: validating the switch to the production environment

Once you have tested the connection from your mobile application to Sips In-App , you can validate the connection to the production version of Sips In-App .

Prior to this, we recommend you block public access to your website to prevent customers from carrying out transactions during this validation phase.

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

URL https://office-server.sips-atos.com
merchantId Shop identifier received by e-mail
SecretKey Secret key you can retrieve from the Sips Download extranet
keyVersion Secret key version retrieved from Sips Download (obviously 1 for the first key)
Note: forgetting one of these 4 parameters is a common mistake that systematically results in an error.

How to validate the proper functioning in the production environment

Immediately:

  • Make a transaction using a real payment card (your own, if possible). If the transaction is accepted, it will be sent to the bank to credit your merchant account and to debit the card account.
  • Check that your payment pages include your customisation settings.
  • Check the transaction via Sips Office Extranet , using the transactionReference.

The next day:

  • Make sure the transaction is in the Transactions report.
  • Check your account to make sure the operation was credited.
  • Refund the transaction via Sips Office Extranet (optional).

Two days later:

  • Check that the refund transaction is in the Operations report.
  • Make sure the debited amount has been refunded to your merchant account.

This validation process is also applicable to the PayPal means of payment.

Step 6: launching live operation

Once the validation for the transition to live operation has been carried out, make your site public so your customers can make purchases and payments.

On the same day:

  • Monitor acceptance rates (number of responseCode  00 per total number of transactions).
  • Check the nature of non-banking refusals:
    • Technical issue: responseCode  90, 97, 99
    • Fraud: responseCode  34
    • Max. number of payment attempts reached: responseCode  75

The next day:

  • Check that all transactions processed (accepted and refused) are in the Transactions report.
  • Check the operations you have carried out and remittances (report option) in the Operations report.