La valeur de la donnée Seal est calculée comme suit :

• concaténation des valeurs des champs de données dans l’ordre alphabétique (respectant le code de caractères ASCII) des noms des champs, sauf pour les champs keyVersion et sealAlgorithm. Donnant la donnée data, mentionnée dans les exemples ci-dessous.
  • exemple : un champ nommé authorResponseMessage est à positionner avant un champ nommé authorisationId ;
• obtention de l’encodage UTF-8 des données du résultat précédent ;
• HMAC avec chiffrement SHA256 des octets obtenus avec la clé secrète.

Cette procédure peut être résumée comme suit :

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

• Exemple d’encodage Hmac Sha256 en 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 et secretKey doivent utiliser un jeu de caractères UTF-8. Référez-vous à la fonction utf8_encode pour la conversion de caractères ISO-8859-1 en UTF-8.

• Exemple d’encodage Hmac Sha256 en 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();
  }
  }
  
  }

• Exemple d’encodage Hmac Sha256 en .net

  (Exemple effectué à l’aide d’un simple formulaire nommé « Form1 » contenant deux champs texte pour saisir data et txtSecretKey, ainsi qu’un autre champ pour afficher 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();
          }
  
      }
  }

Une fois votre calcul de seal mis en place, voici un exemple de requête vous permettant de vérifier que vous retrouvez bien le bon 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"
}

Pour la requête ci-dessus, la chaîne concaténée que vous devez calculer est la suivante :

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

Avec un algorithme de hachage HMAC-SHA-256 et une clé secrète valant :

secret123

Le seal attendu est :

c4372c03a0d678fcf5a401d6a7d8625785580d07257208b8c0dc098e0109963a

Une cinématique de paiement carte sans authentification porteur via In-App se déroule en 2 étapes :

• Initialiser la cinématique de paiement auprès du serveur Mercanet via le service orderInitialize (avec sdkOperationName=CARDORDER) ;
• Une fois les informations carte saisies par le porteur, effectuer le paiement en appelant le service cardOrder depuis l'application mobile via le SDK In-App.

Une cinématique de paiement carte avec authentification porteur via In-App se déroule en 4 étapes :

• Initialiser la cinématique de paiement auprès du serveur Mercanet via le service orderInitialize (avec sdkOperationName=THREEDSECUREANDORDER) ;
• Une fois les informations carte saisies par le porteur, effectuer une demande de vérification de l'enrôlement du porteur en appelant le service cardCheckEnrollment depuis l'application mobile via le SDK In-App ;
• Rediriger le porteur vers l'ACS pour authentification ;
• Effectuer le paiement en appelant le service cardValidateAuthenticationAndOrder depuis l'application mobile via le SDK In-App.

Une cinématique de paiement par Wallet client sans authentification porteur via In-App se déroule en 2 étapes :

• Initialiser la cinématique de paiement auprès du serveur Mercanet via le service orderInitialize (avec sdkOperationName=WALLETORDER) ;
• Une fois le moyen de paiement choisi par le porteur, effectuer le paiement en appelant le service walletOrder depuis l'application mobile via le SDK In-App.

Une cinématique de paiement par Wallet client avec authentification porteur via In-App se déroule en 4 étapes :

• Initialiser la cinématique de paiement auprès du serveur Mercanet via le service orderInitialize (avec sdkOperationName=THREEDSECUREANDWALLETORDER) ;
• Une fois le moyen de paiement choisi par le porteur, effectuer une demande de vérification de l'enrôlement du porteur en appelant le service walletCheckEnrollment depuis l'application mobile via le SDK In-App ;
• Rediriger le porteur vers l'ACS pour authentification ;
• Effectuer le paiement en appelant le service cardValidateAuthenticationAndOrder depuis l'application mobile via le SDK In-App.

Une cinématique de paiement avec moyen de paiement déporté via In-App se déroule en 4 étapes :

• Initialiser la cinématique de paiement auprès du serveur Mercanet via le service orderInitialize (avec sdkOperationName=PAYMENTPROVIDERORDER) ;
• Effectuer un appel au service paymentProviderOrder depuis l'application mobile via le SDK In-App pour lancer le paiement et récupérer l'URL-intent permettant de déclencher l'ouverture de l'application mobile du moyen de paiement déporté ;
• Rediriger le porteur sur l'application mobile du moyen de paiement déporté ;
• Une fois le porteur de retour sur l'application mobile commerçant, effectuer un appel au service getTransactionData depuis l'application mobile via le SDK In-App pour connaitre le statut de la transaction (paiement réussi ou échoué).

La requête et la réponse de la fonction orderInitialize sont décrites sur cette page dédiée.

Tous les champs reçus par In-App à travers le connecteur font l’objet d’une vérification individuelle. Le tableau ci-dessous présente la liste des codes d’erreur pouvant être reçus lors de cette étape ainsi que les solutions à mettre en œuvre.

4 cas sont possibles :

• redirectionStatusCode = 00

Ce cas doit être suivi par l'appel, par votre application mobile, du service souhaité (cardOrder, cardCheckEnrollment, walletOrder, walletCheckEnrollment ou paymentProviderOrder).

• redirectionStatusCode = 03, 12, 30, 34

Ces codes d’erreur indiquent que la requête comporte un problème qui doit être résolu. Le processus de paiement doit alors être interrompu.

• redirectionStatusCode = 94

La référence de transaction a déjà été utilisée. Vous devez réessayer avec une autre référence de transaction.

• redirectionStatusCode = 99

Problème de disponibilité du service de paiement. Vous devez essayer de renvoyer la requête. Il convient d’utiliser une nouvelle référence de transaction pour éviter un code de réponse 94.

En fin de cinématique de paiement, en plus de la réponse fournie par le serveur Mercanet à votre application mobile via le SDK In-App, vous avez également la possibilité de recevoir une réponse directement sur votre serveur. Cette réponse automatique est une réponse HTTP(S) POST envoyée sur l'URL automaticResponseUrl précisée optionnellement dans la requête.

Vous devez mettre en place le système permettant de décoder cette réponse, afin de connaître le résultat du paiement.

Les quatre données suivantes sont définies dans les réponses :

Si la valeur du champ Encode est "base64" ou "base64url", la donnée Data doit-être décodée en Base64/Base64Url pour retrouver la chaîne des champs concaténée. La chaîne concaténée est structurée comme suit : clé1=valeur1|clé2=valeur2…

Le sceau (donnée Seal) de la réponse est « hashé » avec le même algorithme utilisé en entrée et fourni dans le champ sealAlgorithm. Si aucune valeur n’a été définie, la valeur SHA-256 est utilisée par défaut.

La valeur de la donnée Seal est calculée comme suit :

Pour l'algorithme HMAC-SHA :

• utilisation de la clé secrète partagée pour générer la variante HMAC du message ;
• utilisation de la donnée Data uniquement (encodée si l’option correspondante est choisie) ;
• codage UTF-8 des données constituant le résultat de l’opération précédente ;
• « Hashage » HMAC-SHA des octets obtenus.

Cette procédure peut être résumée comme suit :

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

Pour l’algorithme SHA-256 (bien que celui-ci soit la valeur par défaut, cet algorithme n’est plus recommandé à ce jour) :

• concaténation de la donnée Data et de la clé secrète (encodée si l’option correspondante est choisie) ;
• codage UTF-8 des données constituant le résultat de l’opération précédente ;
• « Hashage » SHA256 des octets obtenus.

Cette procédure peut être résumée comme suit :

SHA256( UTF-8(Data+secretKey) )

Une fois la cinématique de paiement terminée, vous devez analyser la réponse reçue pour connaitre le résultat. Cette réponse est fournie à l'application mobile en retour de l'appel à la fonction de paiement, ainsi que via l'URL de réponse automatique si vous avez renseigné celle-ci en requête d'initialisation.

Si vous procédez à une authentification par sceau électronique (seal), vous devez impérativement vérifier que le sceau reçu correspond bien au sceau que vous recalculez avec les champs de la réponse.

Une cinématique de consultation des données du Wallet client via In-App se déroule en 2 étapes :

• Initialiser la cinématique de gestion du Wallet auprès du serveur Mercanet via le service walletInitialize (avec sdkOperationName=GETWALLETDATA) ;
• Effectuer un appel au service getWalletData depuis l'application mobile via le SDK In-App.

Une fois le contenu du Wallet client récupéré, vous pouvez le présenter au client pour que celui-ci le manipule (ajout ou suppression d'un moyen de paiement du Wallet) ou effectue un paiement à partir d'une carte enregistrée.

Une cinématique d'ajout d'une carte au Wallet client via In-App se déroule en 2 étapes :

• Initialiser la cinématique de gestion du Wallet auprès du serveur Mercanet via le service walletInitialize (avec sdkOperationName=ADDCARD) ;
• Effectuer un appel au service addCard depuis l'application mobile via le SDK In-App.

Une cinématique de suppression d'un moyen de paiement du Wallet client via In-App se déroule en 2 étapes :

• Initialiser la cinématique de gestion du Wallet auprès du serveur Mercanet via le service walletInitialize (avec sdkOperationName=DELETEPAYMENTMEAN) ;
• Effectuer un appel au service deletePaymentMean depuis l'application mobile via le SDK In-App.

La requête et la réponse de la fonction walletInitialize sont décrites sur cette page dédiée.

Tous les champs reçus par In-App à travers le connecteur font l’objet d’une vérification individuelle. Le tableau ci-dessous présente la liste des codes d’erreur pouvant être reçus lors de cette étape ainsi que les solutions à mettre en œuvre.

3 cas sont possibles :

• redirectionStatusCode = 00

Ce cas doit être suivi par l'appel, par votre application mobile, du service souhaité (getWalletData, addCard ou deletePaymentMean).

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

Ces codes d’erreur indiquent que la requête comporte un problème qui doit être résolu. Le processus de paiement doit alors être interrompu.

• redirectionStatusCode = 99

Problème de disponibilité du service. Vous devez essayer de renvoyer la requête.

Une fois la cinématique de gestion de Wallet terminée, vous devez analyser la réponse reçue pour connaitre le résultat du traitement. Cette réponse est fournie à l'application mobile en retour de l'appel à la fonction de gestion du Wallet.

Une cinématique de consultation des données carte via In-App se déroule en 2 étapes :

• Initialiser la cinématique de consultation des données carte auprès du serveur Mercanet via le service paymentMeanInfoInitialize (avec sdkOperationName=GETCARDDATA) ;
• Une fois le numéro de carte saisie par le porteur, effectuer un appel au service getCardData depuis l'application mobile via le SDK In-App.

Une fois les propriétés de la carte connues, vous pouvez, par exemple, présenter au porteur la ou les marques associées à sa carte, et lui proposer de choisir la marque souhaitée pour effectuer le paiement.

La requête et la réponse de la fonction paymentMeanInfoInitialize sont décrites sur cette page dédiée.

Tous les champs reçus par In-App à travers le connecteur font l’objet d’une vérification individuelle. Le tableau ci-dessous présente la liste des codes d’erreur pouvant être reçus lors de cette étape ainsi que les solutions à mettre en œuvre.

3 cas sont possibles :

• redirectionStatusCode = 00

Ce cas doit être suivi par l'appel, par votre application mobile, du service getCardData.

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

Ces codes d’erreur indiquent que la requête comporte un problème qui doit être résolu. Le processus de paiement doit alors être interrompu.

• redirectionStatusCode = 99

Problème de disponibilité du service. Vous devez essayer de renvoyer la requête.