WL SIPS DOCS

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

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

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_2.38",
  "keyVersion" : "1",
  "merchantId" : "011223344550000",
  "sdkOperationName" : "CARDORDER",
  "sdkVersion" : "SDK100",
  "transactionReference" : "TREFEXA2021",
  "seal" : "c4372c03a0d678fcf5a401d6a7d8625785580d07257208b8c0dc098e0109963a"
}

For the above request, the concatenated string you must obtain is:

2500https://automatic-response-url.fr/0AUTHOR_CAPTURE978IR_MB_2.38011223344550000CARDORDERSDK100TREFEXA2021

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

secret123

The expected seal is:

c4372c03a0d678fcf5a401d6a7d8625785580d07257208b8c0dc098e0109963a

A card payment kinematic without holder authentication with Sips In-App is done in 2 steps:

• Initialize the payment kinematic on Worldline Sips server through orderInitialize service (with sdkOperationName=CARDORDER);
• Once customer has enter his card data, perform the payment by calling the cardOrder service from your mobile application, thanks to the Sips In-App SDK.

A card payment kinematic with holder authentication with Sips In-App is done in 4 steps:

• Initialize the payment kinematic on Worldline Sips server through orderInitialize service (with sdkOperationName=THREEDSECUREANDORDER);
• Once customer has enter his card data, perform a check of the card enrollment by calling the cardCheckEnrollment service from your mobile application, thanks to the Sips In-App SDK;
• Redirect the customer to the ACS for authentication;
• Perform the payment by calling the cardValidateAuthenticationAndOrder service from your mobile application, thanks to the Sips In-App SDK.

A wallet payment kinematic without holder authentication with Sips In-App is done in 2 steps:

• Initialize the payment kinematic on Worldline Sips server through orderInitialize service (with sdkOperationName=WALLETORDER);
• Once the customer has chosen his payment mean, perform the payment by calling the walletOrder service from your mobile application, thanks to the Sips In-App SDK.

A wallet payment kinematic with holder authentication with Sips In-App is done in 4 steps:

• Initialize the payment kinematic on Worldline Sips server through orderInitialize service (with sdkOperationName=THREEDSECUREANDWALLETORDER);
• Once the customer has chosen his payment mean, perform a check of the card enrollment by calling the walletCheckEnrollment service from your mobile application, thanks to the Sips In-App SDK;
• Redirect the customer to the ACS for authentication;
• Perform the payment by calling the cardValidateAuthenticationAndOrder service from your mobile application, thanks to the Sips In-App SDK.

An externalized payment kinematic on a payment provider with Sips In-App is done in 4 steps:

• Initialize the payment kinematic on Worldline Sips server through orderInitialize service (with sdkOperationName=PAYMENTPROVIDERORDER);
• Perform a call to the paymentProviderOrder service from your mobile application, thanks to the Sips In-App SDK, to launch the payment and get the Intent URL which permits to open the payment provider mobile application;
• Redirect the customer to the payment provider mobile application;
• Once the customer is back on the merchant mobile application, perform a call to the getTransactionData service from your mobile application, thanks to the Sips In-App SDK, to know the transaction status (payment in success or failure).

The request and response of the function orderInitiliaze are described on this page.

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

4 cases are possible:

• redirectionStatusCode = 00

This case must be followed by the call from your mobile application, of the wished service (cardOrder, cardCheckEnrollment, walletOrder, walletCheckEnrollment or paymentProviderOrder).

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

At the end of the payment kinematic, in addition to the response returned by Worldline Sips server to your mobile application through Sips In-App SDK, you have the possibility to receive a response directly on your server. This automatic response is a HTTP(S) POST message sent to the automaticResponseUrl URL you optionally set in the request.

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

The following four data elements are defined in the responses:

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.

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

Once the payment kinematic ended, you must analyse the response to know the payment result. This response is furnished to your mobile application in return of the payment function called, as well as to the automatic response URL if you filled it in the initialization request.

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.

A payment Token generation kinematic with Sips In-App is done in 2 steps:

• Initialize the payment Token generation kinematic on Worldline Sips server through paymentTokenInitialize service (with sdkOperationName=PAYMENTTOKENGENERATE);
• Once customer has enter his card data, perform the generation of the payment Token by calling the paymentTokenGenerate service from your mobile application, thanks to the Sips In-App SDK.

The paymentToken received in response permits you to perform the rest of the wished kinematic, directly from your server, without sensitive data.

The request and response of the function paymentTokenInitiliaze are described on this page.

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

3 cases are possible:

• redirectionStatusCode = 00

This case must be followed by the call from your mobile application, of the paymentTokenGenerate service.

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

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

• redirectionStatusCode = 99

Payment service availability issue. You must try to resend the request.

The kinematic to consult customer's Wallet with Sips In-App is done in 2 steps:

• Initialize the Wallet management kinematic on Worldline Sips server through walletInitialize service (with sdkOperationName=GETWALLETDATA);
• Perform a call to getWalletData service from your mobile application, thanks to the Sips In-App SDK.

Once the content of customer's Wallet collected, you can display it the your customer for him to manipulate it (add or delete a payment mean in the Wallet) or perform a payment from a registered card.

The kinematic to add a card to customer's Wallet with Sips In-App is done in 2 steps:

• Initialize the Wallet management kinematic on Worldline Sips server through walletInitialize service (with sdkOperationName=ADDCARD);
• Perform a call to addCard service from your mobile application, thanks to the Sips In-App SDK.

The kinematic to delete a payment mean from a customer's Wallet with via Sips In-App is done in 2 steps:

• Initialize the Wallet management kinematic on Worldline Sips server through walletInitialize service (with sdkOperationName=DELETEPAYMENTMEAN);
• Perform a call to deletePaymentMean service from your mobile application, thanks to the Sips In-App SDK.

The request and response of the function walletInitiliaze are described on this page.

The request and response of the function walletInitiliaze are described on this page.

Once the wallet management kinematic ended, you must analyse the response to know the processing result. This response is furnished to your mobile application in return of the wallet management function called.

The kinematic to consult card data with Sips In-App is done in 2 steps:

• Initialize the kinematic to consult card data on Worldline Sips server through paymentMeanInfoInitialize service (with sdkOperationName=GETCARDDATA);
• Once the card number is entered by the customer, perform a call to getCardData service from your mobile application, thanks to the Sips In-App SDK.

Once properties of the card are known, you are able to, for example, to display to the card holder the brands of the card, and propose him to choose his preferred brand to perform the payment.

The request and response of the function paymentMeanInfoInitiliaze are described on this page.

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

3 cases are possible:

• redirectionStatusCode = 00

This case must be followed by the call from your mobile application, of the getCardData service.

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

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

• redirectionStatusCode = 99

Payment service availability issue. You must try to resend the request.