Inapp

From Documentation Mercanet
Jump to: navigation, search

Contents

Introduction

Mercanet est une solution de paiement e-commerce multicanale sécurisée conforme à la norme PCI DSS. Elle permet à tout commerçant d’accepter et de gérer des transactions de paiement en prenant en compte les règles métiers liées à son activité (paiement à la livraison, paiement différé, paiement récurrent, paiement fractionné, …). L’objectif du présent document est d’expliquer la mise en œuvre de la solution Mercanet In-App JSON jusqu’au démarrage en production.

A qui s’adresse ce document

Ce document s’adresse aux commerçants qui souhaitent souscrire à l’offre Mercanet et proposer le paiement intégré à leur application mobile. Le connecteur In-App est basé sur des échanges JSON via le protocole REST, en mode machine à machine. C’est un guide d’implémentation qui s’adresse à votre équipe technique. Pour avoir une vue d’ensemble de la solution Mercanet, nous vous conseillons de consulter les documents suivants:

Prérequis

Une connaissance des standards relatifs aux langages de programmation Web pratiqués aujourd’hui, tels que Java, PHP ou .Net, est nécessaire pour pouvoir développer un client capable de se connecter à la passerelle Mercanet In-App JSON. De plus, il est obligatoire de posséder une connaissance approfondie de Java pour développer des applications mobiles pour Android et iOS.

Remarque

Tous les exemples de code de ce document sont fournis à titre d’exemple, il convient de les adapter à votre site Web afin qu’ils soient pleinement exploitables. Le SDK In-App doit être utilisé avec une version 7.0 du système iOS au minimum ou une version 4.4 du système Android.

Gestion de la clé secrète

Lors de votre inscription, Worldline met à disposition sur l’extranet Mercanet Download, une clé secrète qui permet de sécuriser les échanges entre votre site et le serveur Mercanet. Vous êtes responsable de sa conservation et devez prendre toutes les mesures pour:

  • en restreindre l’accès,
  • la sauvegarder de manière chiffrée,
  • ne jamais la copier sur un disque non sécurisé,
  • ne jamais l’envoyer (e-mail, courrier) de manière non sécurisée.

La compromission de la clé secrète et son utilisation par un tiers malveillant perturberait le fonctionnement normal de votre boutique, et pourrait notamment générer des transactions et des opérations de caisse injustifiées (des remboursements par exemple). En cas de compromission d’une clé secrète, vous êtes tenu d’en demander au plus vite la révocation puis le renouvellement via l’extranet Mercanet Download.

Remarque

C’est la même clé secrète qui est utilisée sur les différents connecteurs Mercanet Essentiel PayPage, Mercanet Gestion Plus, In-App et Walletpage.

Contacter l’assistance technique

[Pour toute question technique ou demande d'assistance, nos services sont disponibles]

Etre en conformité avec PCI-DSS

Worldline a supprimé la contrainte PCI-DSS de votre côté car des données carte chiffrées transitent entre les applications mobiles et le serveur Mercanet.

En effet, les données carte ne transitent jamais par votre serveur et cela ne doit jamais être le cas.

Par conséquent, votre application n'a pas à se conformer à la norme PCI-DSS ; elle doit simplement respecter les pratiques d'excellence PCI-DSS décrites à cette adresse: https://www.pcisecuritystandards.org/security_standards/documents.php?association=PA-DSS

Démonstrations

Cliquer sur les liens ci-après pour voir des démonstrations réalisées avec le SDK Mercanet :

Téléchargement du SDK in-app

SDK in-app Android

La bibliothèque peut être importée via un fichier JAR ou AAR.

Le SDK peut être téléchargé depuis [Mercanet téléchargement]

SDK in-app iOS

Le SDK est publié sous la forme d’un fichier framework.

Il suffit de glisser-déposer le fichier InAppSdk.framework dans votre projet.

Le SDK peut être téléchargé depuis [Mercanet téléchargement]

Comprendre le paiement avec Mercanet In-App JSON

Le principe général d’un processus de paiement est le suivant:

Schema inapp.PNG

  1. Le client saisit les informations de son moyen de paiement. L'application mobile contacte alors votre serveur avec les données à envoyer au moteur Mercanet (hormis les données cartes).
  2. Votre serveur contacte le serveur Mercanet pour initialiser une requête de paiement.
  3. La requête est vérifiée. Si elle est valide, elle est chiffrée et retournée dans le champ redirectionData. Votre serveur reçoit aussi l'URL du moteur Mercanet servant au paiement et la clé publique pour chiffrer les données de la carte durant le paiement.
  4. Votre serveur renvoie toutes les données à l’application mobile.
  5. L'application mobile appelle le SDK pour effectuer un paiement par carte en lui fournissant la clé publique ainsi que la donnée redirectionData reçue. Le SDK chiffre ces données sensibles avec la clé publique fournie.
  6. Le champ redirectionData et les données carte chiffrées sont envoyés au moteur Mercanet via HTTPS.
  7. Le moteur Mercanet traite le paiement.
  8. En retour, il notifie le statut de l'opération à votre serveur ainsi qu’à l'application mobile.

Remarque

Il vous appartient d’éviter les attaques «de l’homme du milieu» (en anglais: man-in-the-middle) entre les flux 1 et 4 (Cf. https://fr.wikipedia.org/wiki/Attaque_de_l'homme_du_milieu).

Comprendre la gestion de Wallet avec Mercanet In-App JSON

Schema inapp.PNG

  1. Suivant le choix de la fonction de gestion de wallet choisie, l'application mobile contacte alors votre serveur avec les données à envoyer au moteur Mercanet.
  2. Votre serveur contacte le serveur Mercanet pour initialiser la fonction de gestion de wallet.
  3. La requête est vérifiée. Si elle est valide, elle est chiffrée et retournée dans le champ redirectionData. Votre serveur reçoit aussi l'URL du moteur Mercanet servant à la gestion du wallet et la clé publique pour chiffrer les données de la carte durant le paiement.
  4. Votre serveur renvoie toutes les données à l’application mobile.
  5. L'application mobile appelle le SDK pour effectuer la gestion de wallet souhaitée.
  6. Le champ redirectionData et les données carte chiffrées (dans le cas d’un ajout carte) sont envoyés au moteur Mercanet via HTTPS.
  7. Le moteur Mercanet traite la demande.
  8. En retour, il notifie le statut de l'opération à l'application mobile.

Démarrer avec Mercanet In-App en 6 étapes

Etape 1: Inscrire la boutique en production

Afin d’inscrire votre boutique en production, vous devez remplir le formulaire d’inscription. Pour cela veuiller contacter votre chargé d'affaire BNP Paribas.

Lors de la saisie du formulaire, vous désignez un contact administratif et un contact technique afin que BNP Paribas puisse vous communiquer les informations nécessaires pour démarrer votre boutique.

BNP Paribas procède alors à l’enregistrement de la boutique et vous retourne votre identifiant commerçant (MerchantId) ainsi que vos identifiants et mots de passe Mercanet Téléchargement (récupération de la clé secrète) et Mercanet Back office Marchand (gestion de caisse) par mail.

Remarque

Pour Mercanet Extranet l’identifiant et le mot de passe sont envoyés au contact administratif. Pour Mercanet Download, l’identifiant est envoyé au contact administratif et le mot de passe au contact technique.

L’inscription de la boutique n’est pas nécessaire pour commencer à intégrer le connecteur et à tester la connexion sur l’environnement de recette client. Vous pouvez ne demander l’inscription de votre boutique qu’au moment de faire les tests en production.


Etape 2: Effectuer un paiement

Comme indiqué au chapitre précédent, la requête de paiement consiste tout d’abord en un appel vers votre serveur depuis l’application mobile pour envoyer les données du moyen de paiement.

Ensuite, votre serveur doit initialiser la requête de paiement vers le serveur Mercanet via un service Web REST (JSON).

Initialiser la requête de paiement depuis votre serveur

L’URL est: https://office-server.mercanet.bnpparibas.net/rs-services/v2/checkoutInApp/orderInitialize
La valeur du champ interfaceVersion doit être fixée à IR_MB_1.3.

Syntaxe de la requête

La requête est construite conformément au format JSON:

{“<nom du champ>” : ”<nom de la valeur>”, “<nom du champ>” : “<nom de la valeur>”, “nom du champ” : “Nom de la valeur” etc., “seal” : “valeur de seal” }

Exemple d’une requête de paiement d’un montant de 20 euros :

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

La syntaxe utilisée pour créer une liste en JSON suit la norme. Voici un résumé de cette structure pour les deux principaux types de listes : les listes de champs simples (par ex. chaînes de caractères) et les listes d’objets. Il est possible d’avoir une liste de valeurs pour un même champ :

…,"nom du champ" : ["valeur1","valeur2"],…

Exemple avec le champ paymentMeanBrandList valorisé avec VISA et MASTERCARD:

…,"paymentMeanBrandList" : ["VISA","MASTERCARD"],…
Sécurisation de la requête

La requête de paiement contient les paramètres de la transaction et est envoyée par votre serveur. Théoriquement, il est possible pour un pirate d’intercepter la requête et de modifier son contenu avant que les données n’atteignent le serveur de paiement. De ce fait, il est nécessaire de renforcer la sécurité pour assurer l’intégrité des paramètres de la transaction envoyée. La solution Mercanet répond à ce besoin par échange de signatures. Un contrôle effectif de la signature comporte deux éléments:

  • l’intégrité des messages de requête et de réponse; l’absence de modifications lors de l’échange,
  • l’authentification de l’émetteur et du destinataire, car ils se partagent la même clé secrète.

Remarque

Si votre clé secrète est compromise, ou si vous supposez que c’est le cas, vous devez impérativement demander son renouvellement en vous connectant à Mercanet Download.

Comment sécuriser la requête

La sécurisation de la requête est effectuée en calculant la valeur «hashée» conformément aux paramètres de la transaction. Ensuite, la clé secrète y est ajoutée. Toutes les chaînes de caractères sont converties en UTF-8 avant le «hashage».

L’algorithme de «hashage» génère un résultat irréversible. Lorsqu’un tel message est reçu, le destinataire doit recalculer la valeur «hashée» pour la comparer à celle reçue. Toute différence indique que les données échangées ont été falsifiées ou que le destinataire et l’émetteur ne partage pas la même clé secrète.

Le résultat doit être envoyé sous forme hexadécimale dans une donnée nommée Seal.

Calcul de la donnée Seal

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

Pour l’algorithme HMAC-SHA :

  • Concaténation des valeurs des champs de données dans l’ordre alphabétique des noms de champs, sauf pour les champs keyVersion et sealAlgorithm
  • 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 de code
  • Exemple d’encodage Hmac Sha256 en Php 5
    <?php
    
    …
    
    // Seal computation thanks to hash sorted data hash with merchant key
    $data_to_send=$amount.$captureDay.$captureMode.$cardCSCValue.$cardExpiryDate.$cardNumber.$cardSeqNumber.$currency_code.$pb.$customerId.$customerIpAddress.$ivers.$mid.$merchantTransactionDateTime.$orderChannel.$orderId.$returnContext.$opeorig.$tref;
    
    $data_to_send= utf8_encode($data_to_send)
    
    $seal=hash_hmac('sha256', $data_to_send, $secretKey);
    
    …
    …
    
    ?> 
    

    «data_to_send» 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;
    
      hmacSHA256 = Mac.getInstance("HmacSHA256");
      SecretKeySpec keySpec = new SecretKeySpec(secretKey, "HmacSHA256");
      hmacSHA256.init(keySpec);
    
      return encodeHexString(hmacSHA256.doFinal(Data));
    	}
    	
    	/**
    	 * @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
    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 = txtMercanet.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();
            }
    
        }
    }
    
Renseigner les champs de la requête orderInitialize
Champs génériques

Champ

Présence

A partir de la version

Commentaires

amount

Obligatoire

MB_1.0

currencyCode

Obligatoire

MB_1.0

interfaceVersion

Obligatoire

MB_1.0

Valeur fixée à IR_MB_1.3

keyVersion

Obligatoire

MB_1.0

merchantId

Obligatoire

MB_1.0

paymentMeanBrand

Facultatif

MB_1.0

sdkOperationName

Obligatoire

MB_1.1

CARDORDER ou WALLETORDER ou PAYMENTPROVIDERORDER ou THREEDSECUREANDORDER

seal

Obligatoire

MB_1.0

transactionReference

Obligatoire

MB_1.0

Facultatif si vous utilisez s10TransactionReference.

s10TransactionReference

Obligatoire

MB_1.3

Facultatif si vous utilisez transactionReference. Voir ci-dessous

automaticResponseUrl

Facultatif

MB_1.0

captureDay

Facultatif

MB_1.0

captureMode

Facultatif

MB_1.0

customerEmail

Facultatif

MB_1.0

customerId

Facultatif

MB_1.0

customerLanguage

Facultatif

MB_1.0

intermediateServiceProviderId

Facultatif

MB_1.2

invoiceReference

Facultatif

MB_1.1

merchantWalletId

Facultatif

MB_1.0

orderId

Facultatif

MB_1.0

paymentMeanBrandSelectionStatus

Facultatif

MB_1.2

paymentPattern

Facultatif

MB_1.0

responseKeyVersion

Facultatif

MB_1.0

returnContext

Facultatif

MB_1.0

sealAlgorithm

Facultatif

MB_1.1

sdkVersion

Facultatif

MB_1.0

Valeur fixée à SDK100

statementReference

Facultatif

MB_1.1

Champs optionnels relatifs au transactionId Mercanet 1.0
  • Contenu de s10TransactionReference:

Champ

Présence

Version

Commentaires

s10TransactionId

Facultatif

MB_1.3

s10TransactionIdDate

Facultatif

MB_1.3

Récupérer les champs de la réponse

Champ

A partir de la version

Commentaires

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

  • Exemple de réponse à une requête orderInitialize
{"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":"0abbfebf740b09993ac36a9173a791809b7fd6c4cc40df8695f56695ad815dda"}
Traiter les erreurs lors de l’initialisation du paiement

Le serveur Mercanet vérifie individuellement chaque champ reçu. La liste suivante contient les codes d'erreur qui peuvent être retournés durant l'étape de vérification, ainsi que les solutions à mettre en œuvre.

redirectionStatusCode

Description

00

Situation normale suivie du processus normal d’appel à la fonction cardOrder.

03

L’identifiant commerçant ou le contrat acquéreur sont invalides.

12

Les paramètres de la transaction sont invalides. Vérifiez les paramètres de la requête (l’erreur est indiquée dans le redirectionStatusMessage).

30

Le format de la requête est invalide (l’erreur est indiquée dans le redirectionStatusMessage).

34

Problème de sécurité ; par exemple, le calcul du sceau de la requête est invalide.

94

La transaction existe déjà.

99

Service temporairement indisponible

4 cas sont possibles:

  • redirectionStatusCode = 00

Ce cas doit être suivi par l’appel à la fonction cardOrder par le mobile.

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

Importer le SDK dans un projet Android

Pour utiliser cette bibliothèque dans votre application Java, ajoutez le JAR du SDK au dossier de compilation du projet.

  • Exemple avec Eclipse IDE
Faites un clic droit sur votre projet.
Sélectionnez Properties.
Cliquez sur Java Build Path.
Dans l’onglet Libraries, cliquez sur Add JARs.
Sélectionnez le JAR du SDK et cliquez sur OK.

Pour utiliser cette bibliothèque dans votre application Android Studio et Gradle, ajoutez le fichier AAR du SDK au dossier libs.

  • Exemple avec Android Studio


Dans le fichier build.gradle,
Ajoutez le code suivant dans la partie repositories.

 flatDir {
           dirs 'libs'
 }

Ajoutez les dépendances suivantes :

 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'
 compile project(':InAppSdk-1.4.2')
Permissions du Manifeste

Ajoutez les entrées suivantes au manifeste Android de l’application :

 <uses-permission android:name=<em>"android.permission.INTERNET"</em>/>
 <uses-permission android:name=<em>"android.permission.READ_PHONE_STATE"</em>/>
 <uses-permission <span>android:name=<em>"android.permission.GET_ACCOUNTS"</em>/></span>

Remarque

Les permissions GET_ACCOUNTS et READ_PHOINE_STATE sont facultatives.

Le SDK a besoin de ces permissions pour récupérer les informations du téléphone :

Information de l’appareil

A partir de la version

Commentaires

Android ID

1.0

Détecteur de débogueur

1.0

Nom de l’appareil

1.0

Adresse de courrier électronique

1.0

Détecteur d’émulateur

1.0

Opérateur

1.0

Téléphone rooté

1.0

Numéro de série SIM

1.0

Condensat de la bibliothèque SSL

1.0

Condensat de System Core

1.0

Condensat du SDK In-App

1.0

Condensat de la bibliothèque WebKit

1.0

Applications sur liste noire

1.0

IMEI

1.0

Ecran allumé ?

1.0

Importer le SDK dans un projet iOS

Le SDK est publié sous la forme d’un fichier framework.

Il suffit de glisser-déposer le fichier InAppSdk.framework dans votre projet pour l’importer.

Lier le binaire aux bibliothèques

Dans votre projet, vous devez lier le fichier SDK.

  • Pour ce faire, dans XCode :


Cliquez sur votre projet.

Cliquez sur votre application cible.
Cliquez sur l’onglet Build phases.
Développez la rubrique Link Binary With Libraries.
Cliquez sur le symbole “+”.
Sélectionnez le fichier InAppSdk.framework.


Cela est parfois fait automatiquement.

Lier des binaires intégrés

Dans votre projet commerçant, vous devez lier les binaires intégrés.

  • Pour ce faire, dans XCode :


Cliquez sur votre projet.

Cliquez sur votre application cible.
Cliquez sur l’onglet General.
Dans la section Embedded Binaries :
Cliquez sur le symbole “+”.
Sélectionnez le fichier InAppSdk.framework.


Vous devriez avoir la configuration suivante :
Fichier:Xcode inapp.png

Valider le paiement côté mobile avec Android

Toutes les méthodes nécessaires se trouvent dans la classe publique PaymentManager.


Remarque

Ces méthodes effectuent des appels réseau, elles doivent donc être appelées de façon asynchrone.

Fonction cardOrder

Cette fonction est utilisée pour effectuer un paiement par carte.
Elle est appelée après la requête d’initialisation orderInitialize sur votre serveur avec sdkOperationName=CARDORDER.

Format de la requête cardOrder

Paramètres

Type

Commentaires

context

Context

Contexte Android

cardNumber

String

Numéro de carte

cardCSCValue

String

Cryptogramme visuel

cardExpiryDate

String

Date d’expiration

paymentMeanBrand

String

Moyen de paiement sélectionné

paymentMeanBrandSelectionStatus

String

Statut de sélection du moyen de paiement

publicKeyValue

String

Valeur cryptée de la clé publique

Récupérés à partie de la requête d’initialisation

redirectionData

String

Token unique contenant le contexte de la transaction

redirectionUrl

String

Adresse d'URL fournie en sortie de l’orderInitialize

redirectionVersion

String

Version de l’interface

Format de la réponse via l’objet OrderResponse

Nom du champ

Format

Commentaire

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

Champs optionnels relatifs au transactionId Mercanet 1.0
  • Contenu de s10TransactionReference:

Champ

Présence

Commentaires

s10TransactionId

String

s10TransactionIdDate

String

Fonction walletOrder

Cette fonction est utilisée pour effectuer un paiement par wallet.
Elle est appelée après la requête d’initialisation orderInitialize sur votre serveur avec sdkOperationName=WALLETORDER.

Format de la requête walletOrder

Paramètres

Type

Commentaires

context

Context

Contexte Android

paymentMeanId

Integer

Identifiant de la carte sélectionnée

redirectionVersion

String

Version de l’interface

cardCSCValue

String

Cryptogramme visuel (facultatif)

publicKeyValue

String

Valeur cryptée de la clé publique

Récupérés à partie de la requête d’initialisation

redirectionData

String

Token unique contenant le contexte de la transaction

redirectionUrl

String

Adresse URL M2M

Format de la réponse via l’objet OrderResponse

Voir le chapitre cardOrder pour la description de cette réponse.

Fonction paymentProviderOrder

Cette fonction est utilisée pour effectuer un paiement BCMC et obtenir l'URL Intent BCMC à appeler. Elle est appelée après la requête d’initialisation orderInitialize sur votre serveur avec sdkOperationName=PAYMENTPROVIDERORDER et paymentMeanBrand= BCMCMOBILE.

Format de la requête paymentProviderOrder

Paramètres

Type

Commentaires

context

Context

Contexte Android

publicKeyValue

String

Valeur cryptée de la clé publique

Récupérés à partie de la requête d’initialisation

redirectionData

String

Token unique contenant le contexte de la transaction

redirectionUrl

String

Adresse URL M2M

redirectionVersion

String

Version de l’interface

Format de la réponse via l’objet paymentProviderOrderResponse

Nom du champ

Format

Description

outerRedirectionUrl

String

URL Intent destiné à réveiller l'application BCMC

errorFieldName

String

Nom du champ à l'origine de l'erreur

inAppResponseCode

String

Code de réponse Mercanet

redirectionUrl

String

URL de redirection pour l’appel suivant

transactionContextData

String

Contexte de la transaction

transactionContextVersion

String

Fonction getTransactionData

Cette fonction est utilisée pour vérifier le statut de la transaction BCMC après l'appel de l'application BCMC. Elle est appelée après un appel à paymentProviderOrder, lorsque l'application BCMC rappelle l'application commerçant.

Format de la requête getTransactionData

Paramètres

Type

Commentaires

context

Context

Contexte Android

transactionContextData

String

Token unique contenant le contexte de la transaction

Récupérés à partie de la requête paymentProviderOrder

transactionContextVersion

String

Version du contexte de la transaction

redirectionUrl

String

Adresse URL M2M

Format de la réponse via l’objet getTransactionDataResponse

Nom du champ

Format

Description

acquirerResponseCode

String

Code de réponse acquéreur

originAmount

String

Montant de la transaction

authorisationId

String

Identifiant d’autorisation

captureLimitDate

String

Délai de capture

captureMode

String

Mode de capture

panExpiryDate

String (yyyyMM)

Date d’expiration de la carte

currencyCode

String

Code de la devise

customerId

String

errorFieldName

String

Nom du champ à l'origine de l'erreur

inAppResponseCode

String

Code de réponse du serveur Mercanet

invoiceReference

String

maskedPan

String

Numéro de carte masqué

merchantId

String

Identifiant commerçant

orderChannel

String

Canal de commande

orderId

String

Identifiant de commande

panEntryMode

String

paymentMeanBrand

String

Moyen de paiement sélectionné

paymentMeanType

String

paymentPattern

String

Mode de paiement (simple, récurrent, etc.)

s10TransactionReference

s10TransactionReference

statementReference

String

transactionDateTime

Date

transactionReference

String

Identifiant de la transaction

transactionStatus

String

holderAuthentProgram

String

Valeurs possibles : SUCCESS / ATTEMPT

holderAuthentMethod

String

Valeurs possibles : PASSWORD / NOT_SPECIFIED / OTP_SMS

holderAuthentStatus

String

walletType

String

Type de wallet

Fonction cardCheckEnrollment

Cette fonction est utilisée pour préparer un paiement 3DSecure et obtenir le message paReq («Payer Authentication Request») et l'URL de l'ACS (Access Control Server) à appeler. Elle est appelée après la requête d’initialisation orderInitialize sur votre serveur avec sdkOperationName= THREEDSECUREANDORDER.

Format de la requête cardCheckEnrollment

Paramètres

Type

Commentaires

context

Context

Contexte Android

cardNumber

String

Numéro de carte

cardCSCValue

String

Cryptogramme visuel

cardExpiryDate

String

Date d’expiration

publicKeyValue

String

Valeur cryptée de la clé publique

Récupérés à partie de la requête d’initialisation

redirectionData

String

Token unique contenant le contexte de la transaction

redirectionUrl

String

Adresse URL M2M

redirectionVersion

String

Version de l’interface

Format de la réponse via l’objet checkEnrollmentResponse

Nom du champ

Format

Description

authentRedirectionUrl

String

URL de redirection ACS

errorFieldName

String

Nom du champ à l'origine de l'erreur

redirectionStatusCode

String

Code de réponse Mercanet

paReqMessage

String

Message PaReq
utilisé pour l’authentification ACS

redirectionUrl

String

URL de redirection pour l’appel suivant

transactionContextData

String

Contexte de la transaction

transactionContextVersion

String

Version du contexte de la transaction

En fonction de cette réponse, votre application doit appeler l'ACS en appelant la redirectionUrl reçue avec des paramètres POST :

  • PAReq message retourné par la fonction cardCheckEnrollment dans le champpaReqMessage.
  • MD (”Merchant Data”): Ce champ comporte des données sur le statut du commerçant qui doivent être retournées à ce dernier. Ce champ doit être utilisé pour récupérer la session sur votre site Web.
  • TermUrl : l’URL du commerçant vers laquelle la réponse finale doit être envoyée après authentification de l’utilisateur final (champs de réponse PaRes et MD). Il doit s’agir d’une URL de votre site Web vers laquelle l’utilisateur final doit être redirigé.Sous Android, il est possible d'appeler une fonction Android dans une WebView depuis du code JavaScript. Dès lors, TermUrl peut être une page Web qui pousse les champs POST reçus vers l'application Android du commerçant à l'aide d'une méthode JavascriptInterface.
  • Exemple d'un Acs WebViewActivity qui obtient le PaRes à partir d'une authentification ACS :
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
		}
	}
}
Fonction cardValidateAuthenticationAndOrder

Cette fonction est utilisée pour valider l'authentification après authentification par l'ACS.
Elle est appelée après un appel à cardCheckEnrollment, lorsque l'ACS renvoie le message paRes. L'algorithme «URL encode» doit être appliqué au message paRes avant que celui-ci ne soit fourni au SDK.

Format de la requête cardValidateAuthenticationAndOrder

Paramètres

Type

Commentaires

context

Context

Contexte Android

paResMessage

String

Réponse d'authentification du payeur L'algorithme standard «Url Encode» doit être appliqué au champ paResMessage reçu de l’ACS.

paymentMeanBrand

String

Moyen de paiement sélectionné

paymentMeanBrandSelectionStatus

String

Statut de sélection du moyen de paiement

transactionContextData

String

Token unique contenant le contexte de la transaction

Récupérés à partie de la requête cardCheckEnrollment

transactionContextVersion

String

Version du contexte de la transaction

redirectionUrl

String

Adresse URL M2M

Format de la réponse via l’objet OrderResponse

Voir le chapitre cardOrder pour la description de cette réponse.

Valider le paiement côté mobile avec iOS

Toutes les méthodes nécessaires se trouvent dans la classe publique InAppSdk.

Remarque

Contrairement à la version Android du SDK, sur la version iOS l’asynchronisme est géré au sein du SDK lui-même. Il n’y a donc pas de nécessité de faire l’appel à ces fonctions de façon asynchrone, la réponse est reçue à l’aide d’un handler à la fin de l’appel.

Fonction cardOrder

Cette fonction est utilisée pour effectuer un paiement par carte.
Elle est appelée après la requête d’initialisation orderInitialize sur votre serveur avec sdkOperationName=CARDORDER.

Format de la requête cardOrder

Paramètres

Type

Commentaires

cardNumber

NSString

Numéro de carte

cardCSCValue

NSString

Cryptogramme visuel

cardExpiryDate

NSString

Date d’expiration

paymentMeanBrand

NSString

Moyen de paiement sélectionné

paymentMeanBrandSelectionStatus

NSString

Statut de sélection du moyen de paiement

publicKeyValue

NSString

Valeur cryptée de la clé publique

Récupérés à partie de la requête d’initialisation

redirectionData

NSString

Token unique contenant le contexte de la transaction

redirectionUrl

NSString

Adresse URL M2M

redirectionVersion

NSString

Version de l’interface

handler

void (^)(INAPPOrderResponse * response)

Handler alimenté à la fin de l'appel

Format de la réponse via l’objet INAPPOrderResponse

Nom du champ

Format

Description

acquirerResponseCode

NSString

Code de réponse acquéreur

amount

NSString

Montant de la transaction

authorisationId

NSString

Identifiant d’autorisation

captureDay

NSString

Délai de capture

captureMode

NSString

Mode de capture

cardExpiryDate

NSString (yyyyMM)

Date d’expiration de la carte

currencyCode

NSString

Code de la devise

customerId

NSString

errorFieldName

NSString

Nom du champ à l'origine de l'erreur

inAppResponseCode

NSString

Code de réponse du serveur Mercanet

invoiceReference

NSString

maskedPan

NSString

Numéro de carte masqué

merchantId

NSString

Identifiant commerçant

merchantWalletId

NSString

Identifiant de wallet commerçant

orderChannel

NSString

Canal de commande

orderId

NSString

Identifiant de commande

panEntryMode

NSString

paymentMeanBrand

NSString

Moyen de paiement sélectionné

paymentMeanBrandSelectionStatus

NSString

paymentMeanType

NSString

Moyen de paiement utilisé

paymentPattern

NSString

Mode de paiement (simple, récurrent, etc.)

returnContext

NSString

s10TransactionReference

s10TransactionReference

statementReference

NSString

transactionDateTime

NSString

transactionOrigin

NSString

Origine de la transaction

transactionPlatform

NSString

Usage futur (systématiquement valorisé à ‘PROD’ pour le moment)

transactionReference

NSString

Identifiant de la transaction

Fonction walletOrder

Cette fonction est utilisée pour effectuer un paiement par wallet. Elle est appelée après la requête d’initialisation orderInitialize sur votre serveur avec sdkOperationName=WALLETORDER.

Format de la requête walletOrder

Paramètres

Type

Commentaires

paymentMeanId

NSInteger

Identifiant de la carte sélectionnée

cscValue

NSString

Code confidentiel (facultatif)

redirectionVersion

NSString

Version de l’interface

publicKeyValue

NSString

Valeur cryptée de la clé publique

Récupérés à partie de la requête d’initialisation

redirectionData

NSString

Token unique contenant le contexte de la transaction

redirectionUrl

NSString

Adresse URL M2M

handler

void (^)(INAPPOrderResponse * response)

Handler alimenté à la fin de l'appel

Format de la réponse via l’objet INAPPOrderResponse

Voir le chapitre cardOrder pour la description de cette réponse.

Fonction paymentProviderOrder

Cette fonction est utilisée pour effectuer un paiement BCMC et obtenir l'URL Intent BCMC à appeler. Elle est appelée après la requête d’initialisation orderInitialize sur votre serveur avec sdkOperationName=PAYMENTPROVIDERORDER et paymentMeanBrand= BCMCMOBILE.

Format de la requête paymentProviderOrder

Paramètres

Type

Commentaires

publicKeyValue

NSString

Valeur cryptée de la clé publique

Récupérés à partie de la requête d’initialisation

redirectionData

NSString

Token unique contenant le contexte de la transaction

redirectionUrl

NSString

Adresse URL M2M

redirectionVersion

NSString

Version de l’interface

handler

void (^)(void (^)(INAPPPaymentProviderResponse * response))

Handler alimenté à la fin de l'appel

Handler alimenté à la fin de l'appel

Format de la réponse via l’objet INAPPPaymentProviderOrderResponse

Nom du champ

Format

Description

outerRedirectionUrl

NSString

URL Intent destiné à réveiller l'application BCMC

errorFieldName

NSString

Nom du champ à l'origine de l'erreur

inAppResponseCode

NSString

Code de réponse Mercanet

redirectionUrl

NSString

Message PaReq utilisé pour l’authentification ACS

transactionContextData

NSString

URL de redirection pour l’appel suivant

transactionContextVersion

NSString

Contexte de la transaction

Fonction getTransactionData

Cette fonction est utilisée pour vérifier le statut de la transaction BCMC après l'appel de l'application BCMC. Elle est appelée après un appel à paymentProviderOrder, lorsque l'application BCMC rappelle l'application commerçant.

Format de la requête getTransactionData

Paramètres

Type

Commentaires

transactionContextData

NSString

Token unique contenant le contexte de la transaction

Récupérés à partie de la requête paymentProviderOrder

transactionContextVersion

NSString

Version du contexte de la transaction

redirectionUrl

NSString

Adresse URL M2M

handler

void (^)(INAPPGetTransactionDataResponse * response)

Handler alimenté à la fin de l'appel

Handler alimenté à la fin de l'appel

Format de la réponse via l’objet INAPPGetTransactionDataResponse

Nom du champ

Format

Description

acquirerResponseCode

NSString

Code de réponse acquéreur

originAmount

NSString

Montant de la transaction

authorisationId

NSString

Identifiant d’autorisation

captureLimitDate

NSString

Délai de capture

captureMode

NSString

Mode de capture

panExpiryDate

NSString (yyyyMM)

Date d’expiration de la carte

currencyCode

NSString

Code de la devise

customerId

NSString

errorFieldName

NSString

Nom du champ à l'origine de l'erreur

inAppResponseCode

NSString

Code de réponse du serveur Mercanet

invoiceReference

NSString

maskedPan

NSString

Numéro de carte masqué

merchantId

NSString

Identifiant commerçant

orderChannel

NSString

Canal de commande

orderId

NSString

Identifiant de commande

panEntryMode

NSString

paymentMeanBrand

NSString

Moyen de paiement sélectionné

paymentMeanType

NSString

Moyen de paiement utilisé

paymentPattern

NSString

Mode de paiement (simple, récurrent, etc.)

s10TransactionReference

s10TransactionReference

statementReference

NSString

transactionDateTime

NSString

transactionReference

NSString

Identifiant de la transaction

transactionStatus

NSString

holderAuthentProgram

NSString

Valeurs possibles : SUCCESS / ATTEMPT

holderAuthentMethod

NSString

Valeurs possibles : PASSWORD / NOT_SPECIFIED / OTP_SMS

holderAuthentStatus

NSString

walletType

NSString

Type de wallet

Fonction cardCheckEnrollment

Cette fonction est utilisée pour préparer un paiement 3DSecure et obtenir le message paReq («Payer Authentication Request») et l'URL de l'ACS (Access Control Server) à appeler.
Elle est appelée après la requête d’initialisation orderInitialize sur votre serveur avec sdkOperationName=THREEDSECUREANDORDER.

Format de la requête cardCheckEnrollment

Paramètres

Type

Commentaires

cardNumber

NSString

Numéro de carte

cardCSCValue

NSString

Code confidentiel

cardExpiryDate

NSString

Date d’expiration

publicKeyValue

NSString

Valeur cryptée de la clé publique

Récupérés à partie de la requête d’initialisation

redirectionData

NSString

Token unique contenant le contexte de la transaction

redirectionUrl

NSString

Adresse URL M2M

redirectionVersion

NSString

Version de l’interface

handler

void (^)(INAPPCheckEnrollmentResponse * response)

Handler alimenté à la fin de l'appel

Handler alimenté à la fin de l'appel

Format de la réponse via l’objet INAPPCardCheckEnrollmentResponse

Nom du champ

Format

Description

authentRedirectionUrl

NSString

URL de redirection ACS

errorFieldName

NSString

Nom du champ à l'origine de l'erreur

redirectionStatusCode

NSString

Code de réponse Mercanet

paReqMessage

NSString

Message PaReq
utilisé pour l’authentification ACS

redirectionUrl

NSString

URL de redirection pour l’appel suivant

transactionContextData

NSString

Contexte de la transaction

transactionContextVersion

NSString

Version du contexte de la transaction

En fonction de cette réponse, votre application doit appeler l'ACS en appelant la redirectionUrl reçue avec des paramètres POST :

  • PAReq message retourné par la fonction cardCheckEnrollment dans le champ paReqMessage.
  • MD (”Merchant Data”): Ce champ comporte des données sur le statut du commerçant qui doivent être retournées à ce dernier. Ce champ doit être utilisé pour récupérer la session sur votre site Web.
  • TermUrl : l’URL du commerçant vers laquelle la réponse finale doit être envoyée après authentification de l’utilisateur final (champs de réponse PaRes et MD). Il doit s’agir d’une URL de votre site Web vers laquelle l’utilisateur final doit être redirigé.Avec iOS, il est possible d'appeler une fonction dans une UIWebView depuis du code JavaScript. Dès lors, TermUrl peut être une page Web du commerçant qui pousse les champs POST reçus vers l'application iOS du commerçant à l'aide d'une méthode UIWebViewDelegate shouldStartloadWithRequest.
  • Exemple de Acs WebViewController qui obtient le PaRes à partir d'une authentification ACS :
@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
         andPaymentMeanBrand:self.paymentMeanBrand
         andPaymentMeanBrandSelectionStatus:self.paymentMeanBrandSelectionStatus
         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
Fonction cardValidateAuthenticationAndOrder

Cette fonction est utilisée pour valider l'authentification de l'ACS. Elle est appelée après un appel à cardCheckEnrollment, lorsque l'ACS renvoie le message paRes. L'algorithme «URL encode» doit être appliqué au message paRes avant que celui-ci ne soit fourni au SDK.
Elle retourne un objet INAPPOrderResponse.

Format de la requête cardValidateAuthenticationAndOrder

Paramètres

Type

Commentaires

paResMessage

NSString

Réponse d'authentification du payeur L'algorithme standard «Url Encode» doit être appliqué au champ paResMessage reçu de l’ACS.

paymentMeanBrand

NSString

Moyen de paiement sélectionné

paymentMeanBrandSelectionStatus

NSString

Statut de sélection du moyen de paiement

transactionContextData

NSString

Token unique contenant le contexte de la transaction

Récupérés à partie de la requête cardCheckEnrollment

transactionContextVersion

NSString

Version du contexte de la transaction

redirectionUrl

NSString

Adresse URL M2M

handler

void (^)(INAPPOrderResponse * response)

Handler alimenté à la fin de l'appel

Handler alimenté à la fin de l'appel

Traiter la réponse de paiement côté serveur

La réponse de paiement est une réponse HTTP(S) POST envoyée vers l’URL automaticResponseUrl (optionnel) précisée dans la requête. Vous devez mettre en place le système permettant de décoder cette réponse, afin de connaitre le résultat du paiement. Les quatre données suivantes sont définies dans les réponses:

Données

Notes/règles

Data

Concaténation des champs en réponse

Encode

Type d’encodage utilisé pour la donnée Data

Seal

Signature du message réponse

interfaceVersion

Version de l’interface du connecteur

Table 1: Champs des réponses automatique et manuelle Si la valeur de la donnée 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.

Renseigner l’URL de la réponse

L’objectif principal de la réponse avec le résultat du paiement est de vous permettre de connaitre ce qui s’est passé sur le mobile du client. La réponse est envoyée seulement si le champ automaticResponseUrl a été transmis dans la requête de paiement vers votre serveur. Si tel est le cas, le serveur Mercanet envoie une réponse HTTP(S) POST à l’adresse URL reçue. Il vous appartient de récupérer les différentes données de la réponse, vérifier la signature pour vous assurer de l’intégrité des champs de la réponse et, par conséquent, mettre à jour votre back office.

Remarque

La version actuelle d’interfaceVersion est HP_2.19. Veuillez consulter le dictionnaire de données Mercanet pour une description complète des paramètres inclus dans la réponse.

Récupérer les champs des réponses

Le contenu de la réponse lui-même peut varier selon le résultat du paiement (réussi ou autre).

Nom du champ

A partir de la version

Commentaires

acquirerNativeResponseCode

HP_2.12

acquirerResponseCode

HP_1.0

acquirerResponseIdentifier

HP_2.8

acquirerResponseMessage

HP_2.8

additionalAuthorisationNumber

HP_2.8

amount

HP_1.0

Valeur communiquée dans la requête de paiement

authorisationId

HP_1.0

captureDay

HP_1.0

Valeur communiquée dans la requête de paiement

captureLimitDate

HP_1.0

captureMode

HP_2.0

Valeur communiquée dans la requête de paiement

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

Valeur communiquée dans la requête de paiement

customerEmail

HP_2.0

Valeur communiquée dans la requête de paiement. Disponible uniquement pour la version HP_2.0

customerId

HP_2.0

Valeur communiquée dans la requête de paiement

customerIpAddress

HP_2.1

Valeur communiquée dans la requête de paiement

customerMobilePhone

HP_2.0

Valeur communiquée dans la requête de paiement. Disponible uniquement pour la version HP_2.1

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

Valeur communiquée dans la requête de paiement

mandateAuthentMethod

HP_2.0

mandateCertificationType

HP_2.7

mandateId

HP_2.0

mandateUsage

HP_2.0

maskedPan*

HP_2.0

merchantId

HP_1.0

Valeur communiquée dans la requête de paiement

merchantSessionId

HP_2.0

Valeur communiquée dans la requête de paiement

merchantTransactionDateTime

HP_2.0

Valeur communiquée dans la requête de paiement

merchantWalletID

HP_2.0

Valeur communiquée dans la requête de paiement

orderChannel

HP_2.0

Valeur communiquée dans la requête de paiement

orderId

HP_1.0

Valeur communiquée dans la requête de paiement

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

Valeur communiquée dans la requête de paiement

preAuthenticationColor

HP_2.10

preAuthenticationInfo

HP_2.10

preAuthenticationProfile

HP_2.10

preAuthenticationProfileValue

HP_2.14

preAuthenticationRuleResultList

HP_2.14

Liste d’objets ruleResult
Voir ci-dessous.

preAuthenticationThreshold

HP_2.10

preAuthenticationValue

HP_2.10

preAuthorisationProfile

HP_2.14

preAuthorisationProfileValue

HP_2.14

preAuthorisationRuleResultList

HP_2.14

Liste d’objets ruleResult
Voir ci-dessous.

responseCode

HP_1.0

returnContext

HP_2.0

Valeur communiquée dans la requête de paiement

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

Valeur communiquée dans la requête de paiement

transactionDateTime

HP_1.0

transactionOrigin

HP_2.0

Valeur communiquée dans la requête de paiement

transactionPlatform

HP_2.16

Usage futur (systématiquement valorisé à ‘PROD’ pour le moment)

transactionReference

HP_2.0

Valeur communiquée dans la requête de paiement

walletType

HP_2.2

* : ces champs sont fournis lorsqu’ils sont disponibles, ce qui est fonction de l’état de la transaction et du moyen de paiement choisi.
Champs optionnels relatifs aux contrôles de fraude
  • Contenu de ruleResult

Champ

version

Commentaires

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 des listes complexes

Le format d'une liste complexe d'objets dans les réponses automatiques et manuelles est défini comme suit (surlignement en jaune):

amount=1000|currencyCode=978|objectNameList=[{"field1":"value1a", "field2":"value2a","field3":"value3a"…},{"field1":"value1b", "field2":"value2b","field3":"value3b"}…]|transactionReference=1452687287828
  • Le contenu de la liste est encadré par une paire de crochets [].
  • Chaque entrée de la liste est encadrée par une paire d'accolades { }.
  • Dans chaque entrée de la liste, chaque champ est représenté sous la forme “nom_du_champ”=”valeur_du_champ”.
  • Notez bien que le nom et la valeur du champ sont tous deux encadrées par une paire de guillemets doubles “ ”.
  • Les paires nom/valeur adjacentes sont séparées par une virgule,.
  • Exemple d’un paiement de 10 euros avec un résultat de fraude
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

Analyser la réponse de paiement

Etat

Champs de la réponse

Action à réaliser

Paiement accepté

responseCode = 00 acquirerResponseCode = 00 garanteeIndicator = Y,N,U, vide

Vous pouvez livrer la commande en fonction du niveau de garantie que vous souhaitez (champ garanteeIndicator)

Refus Fraude Mercanet GONOGO

responseCode = 05 complementaryCode = XX preAuthorisationRuleResultList

Le paiement a été refusé par le moteur de fraude Mercanet que vous avez configuré. Ne livrez pas la marchandise. Analysez le détail des règles fraudes exécutées par Mercanet pour connaitre la cause du refus (champ preAuthorisationRuleResultList).

Refus Fraude Mercanet BUSINESS SCORE

responseCode = 05 scoreColor = RED, BLACK
scoreValue = X (score de la transaction) scoreThreshold = X,Y (seuil orange, seuil vert)

Le paiement a été refusé par le moteur de fraude Mercanet que vous avez configuré Ne livrez pas la marchandise. Analysez le détail des règles fraudes exécutées par Mercanet pour connaitre la cause du refus (champ preAuthorisationRuleResultList).

Warning Fraude Mercanet BUSINESS SCORE

responseCode = 05 scoreColor = ORANGE scoreValue = X (score de la transaction) scoreThreshold = X,Y (seuil orange, seuil vert)

Le paiement a été autorisé par l’acquéreur mais le moteur de fraude Mercanet émet un warning par rapport aux règles que vous avez configurées. Analysez le détail des règles fraudes exécutées par Mercanet pour connaitre la cause du warning (champ preAuthorisationRuleResultList). Si transaction non risquée alors acceptez la avec la fonction acceptChallenge. Si transaction risquée alors refusez la avec la fonction refuseChallenge. Les fonctions acceptChallenge et refuseChallenge sont disponibles sur l’extranet et les connecteurs office.

Refus 3D Secure

reponseCode = 05 holderAuthenStatus = FAILURE

L’authentification de l’acheteur a échoué, ce n’est pas nécessairement un cas de fraude. Vous pouvez proposer à votre client de payer avec autre moyen de paiement en générant une nouvelle requête

Refus bancaire acquéreur

responseCode = 05 acquirerResponseCode = XX

L’autorisation est refusée pour un motif non lié à la fraude. Vous pouvez proposer à votre client de payer avec autre moyen de paiement en générant une nouvelle requête.

Refus fraude acquéreur

responseCode = 34 acquirerResponseCode = XX

Autorisation refusée pour cause de fraude. Ne livrez pas la commande.

Refus suite problème technique

responseCode = 90, 99 acquirerResponseCode = 90 à 98

Problème technique temporaire lors du traitement de la transaction. Proposez à votre client de refaire un paiement ultérieurement.

Etape 3: Gérer le wallet du client

Générer la requête d’initialisation du wallet côté serveur

Ce service vous permet de gérer les wallets de vos clients par ex. d’ajouter un moyen de paiement à un wallet ou de récupérer des informations de wallets existants.

La valeur du champ interfaceVersion doit être fixée à IR_MB_1.3.

L’URL est: https://office-server.mercanet.bnpparibas.net/rs-services/v2/walletInApp/walletInitialize

Syntaxe de la requête

La requête est construite conformément au format JSON, comme la requête d’initialisation d’un paiement.

  • Exemple d’une requête de gestion de wallet pour ajouter une carte :
{"automaticResponseUrl": "http://urlofautomaticresponse.jsp","interfaceVersion" : "IR_MB_1.3","keyVersion" : "2","merchantId" : "12345678912345","merchantWalletId" : "SIM01","sdkOperationName" : "GETWALLETDATA","sdkVersion" : "SDK100","seal" : "482e4a0f89ec528d167af3113ce1b80d2c70a1df55ac749c789136481216f012"}
Renseigner les champs de la requête
Champs génériques

Champ

Présence

A partir de la version

Commentaires

automaticResponseUrl

Facultatif

MB_1.0

Utilisation future

interfaceVersion

Obligatoire

MB_1.0

Valeur fixée à IR_MB_1.3

intermediateServiceProviderId

Facultatif

MB_1.2

merchantId

Obligatoire

MB_1.0

merchantWalletId

Obligatoire

MB_1.0

responseKeyVersion

Facultatif

MB_1.0

sdkOperationName

Obligatoire

MB_1.0

ADDCARD, GETWALLETDATA ou DELETEPAYMENTMEAN

sealAlgorithm

Facultatif

MB_1.1

sdkVersion

Facultatif

MB_1.0

Valeur fixée à SDK100

keyVersion

Facultatif

MB_1.0

seal

Facultatif

MB_1.0

Récupérer les champs de la réponse

Champ

A partir de la version

Commentaires

publicKeyValue

MB_1.0

redirectionData

MB_1.0

redirectionStatusCode

MB_1.0

redirectionStatusMessage

MB_1.0

redirectionUrl

MB_1.0

redirectionVersion

MB_1.0

  • Exemple de réponse à une requête walletInitialize
{"publicKeyValue":"30820122300d…Ydfx9mCns9Z3E","redirectionStatusCode":"00","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"}


Traiter les erreurs lors de l’initialisation du wallet

Tous les champs reçus par l’intermédiaire du serveur Mercanet sont vérifiés individuellement. La liste suivante contient les codes d'erreur qui peuvent être examinés, ainsi que les solutions à mettre en œuvre.

redirectionStatusCode

Description

00

Situation normale suivie du processus normal d'affichage des pages de gestion de wallet.

03

L’identifiant commerçant est invalide.

12

Les paramètres de la requête sont invalides. Vérifiez les paramètres de la requête (l’erreur est indiquée dans le redirectionStatusMessage).

30

Le format de la requête est invalide (l’erreur est indiquée dans le redirectionStatusMessage).

34

Problème de sécurité ; par exemple, le calcul du sceau de la requête est invalide.

40

Fonction non gérée

99

Service temporairement indisponible

3 cas sont possibles :

  • redirectionStatusCode = 00

Ce cas doit être suivi de la redirection de l’utilisateur vers la page de gestion du wallet.

  • 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 gestion de wallet doit alors être interrompu.

  • redirectionStatusCode = 99

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

Gérer le wallet côté mobile avec Android

Remarque

Ces méthodes effectuent des appels réseau, elles doivent donc être appelées de façon asynchrone.

Fonction getWalletData

Cette fonction est utilisée pour récupérer les cartes sauvegardées dans le wallet. Elle est appelée après une commande walletInitialize.

Format de la requête getWalletData

Paramètres

Type

Commentaires

context

Context

Contexte Android

publicKeyValue

String

Valeur cryptée de la clé publique

Récupérés à partie de la requête d’initialisation

redirectionData

String

Token unique contenant le contexte de la transaction

redirectionUrl

String

Adresse URL M2M

redirectionVersion

String

Version de l’interface

Format de la réponse via l’objet INAPPGetWalletDataResponse

Paramètres

Type

Commentaires

inAppResponseCode

String

Code de réponse Mercanet

errorFieldName

String

Nom du champ à l’origine de l’erreur

walletCreationDateTime

String

Date de création du wallet

walletPaymentMeanData

Liste de walletPaymentMeanData

Liste des cartes sauvegardées dans le wallet

Format dans la réponse de l’objet walletPaymentMeanData

Paramètres

Type

Commentaires

panExpiryDate

Date

Date d’expiration de la carte

paymentMeanAlias

String

Alias de la carte

paymentMeanBrand

String

Type de carte

paymentMeanId

Integer

Identifiant du moyen de paiement

maskedPan

String

PAN masqué de la carte

Fonction addCard

Cette fonction est utilisée pour stocker une carte dans un wallet. Elle est appelée après une commande walletInitialize.

Format de la requête addCard

Paramètres

Type

Commentaires

context

Context

Contexte Android

cardNumber

String

Numéro de carte

paymentMeanAlias

String

Alias de la carte

cardExpiryDate

String

Date d’expiration

paymentMeanBrand

String

String Marque (ex : VISA) de la carte

publicKeyValue

String

Valeur cryptée de la clé publique

Récupérés à partie de la requête d’initialisation

redirectionData

String

Token unique contenant le contexte de la transaction

redirectionUrl

String

Adresse URL M2M

redirectionVersion

String

Version de l’interface

Format de la réponse via l’objet addCardResponse

Paramètres

Type

Commentaires

inAppResponseCode

String

Code réponse

errorFieldName

String

Nom du champ à l’origine de l’erreur

paymentMeanId

String

Identifiant du moyen de paiement

maskedPan

String

PAN masqué de la carte

walletActionDateTime

Date

Date de réalisation dans le wallet de l’ajout

Fonction deletePaymentMean

Cette fonction est utilisée pour supprimer une carte du wallet. Elle est appelée après une commande walletInitialize.

Format de la requête deletePaymentMean

Paramètres

Type

Commentaires

context

Context

Contexte Android

paymentMeanId

String

Id du moyen de la carte à supprimer

publicKeyValue

String

Valeur cryptée de la clé publique

Récupérés à partie de la requête d’initialisation

redirectionData

String

Token unique contenant le contexte de la transaction

redirectionUrl

String

Adresse URL M2M

redirectionVersion

String

Version de l’interface

Format de la réponse via l’objet DeletePaymentMeanResponse

Paramètres

Type

Commentaires

inAppResponseCode

String

Code réponse

errorFieldName

String

Nom du champ à l’origine de l’erreur

walletActionDateTime

Date

Date de realization dans le wallet de l’ajout

Gérer le wallet côté mobile avec iOS

Remarque

Contrairement à la version Android du SDK, sur la version iOS l’asynchronisme est géré au sein du SDK lui-même. Il n’y a donc pas de nécessité de faire l’appel à ces fonctions de façon asynchrone, la réponse est reçue à l’aide d’un handler à la fin de l’appel.

Fonction getWalletData

Cette fonction est utilisée pour récupérer les cartes sauvegardées dans le wallet. Elle est appelée après une commande walletInitialize.

Format de la requête getWalletData

Paramètres

Type

Commentaires

redirectionVersion

NSString

Version de l’interface

publicKeyValue

NSString

Valeur cryptée de la clé publique

Récupérés à partie de la requête d’initialisation

redirectionData

NSString

Token unique contenant le contexte de la transaction

redirectionUrl

NSString

Adresse URL M2M

handler

void (^)(INAPPGetWalletDataResponse * response)

Handler alimenté à la fin de l'appel

Format de la réponse via l’objet INAPPgetWalletDataResponse

Paramètres

Type

Commentaires

inAppResponseCode

NSString

Code de réponse Mercanet

errorFieldName

NSString

Nom du champ à l’origine de l’erreur

walletCreationDateTime

NSString

Date de création du wallet

walletPaymentMeanData

Liste de INAPPGetWalletDataResponseItem

Liste des cartes sauvegardées dans le wallet

Format dans la réponse de l’objet walletPaymentMeanData

Paramètres

Type

Commentaires

panExpiryDate

NSString

Date d’expiration de la carte

paymentMeanAlias

NSString

Alias de la carte

paymentMeanBrand

NSString

Type de carte

paymentMeanId

NSString

Identifiant du moyen de paiement

maskedPan

NSString

PAN masqué de la carte

Fonction addCard

Cette fonction est utilisée pour stocker une carte dans un wallet. Elle est appelée après une commande walletInitialize.

Format de la requête addCard

Paramètres

Type

Commentaires

cardNumber

NSString

Numéro de carte

paymentMeanAlias

NSString

Alias de la carte

cardExpiryDate

NSString

Date d’expiration

paymentMeanBrand

NSString

Marque (ex : VISA) de la carte

publicKeyValue

NSString

Valeur cryptée de la clé publique

Récupérés à partie de la requête d’initialisation

redirectionData

NSString

Token unique contenant le contexte de la transaction

redirectionUrl

NSString

Adresse URL M2M

redirectionVersion

NSString

Version de l’interface

handler

void (^)(INAPPAddCardResponse * response)

Handler alimenté à la fin de l'appel

Format de la réponse via l’objet INAPPAddCardResponse

Paramètres

Type

Commentaires

inAppResponseCode

NSString

Date d’expiration de la carte

errorFieldName

NSString

Nom du champ à l’origine de l’erreur

paymentMeanId

NSString

Identifiant du moyen de paiement

maskedPan

NSString

PAN masqué de la carte

walletActionDateTime

NSString

Date de réalisation de l’ajout dans le wallet


Fonction deletePaymentMeanWithPaymentMeanId

Cette fonction est utilisée pour supprimer une carte du wallet. Elle est appelée après une commande walletInitialize.

Format de la requête deletePaymentMean

Paramètres

Type

Commentaires

paymentMeanId

NSInteger

Id du moyen de la carte à supprimer

publicKeyValue

NSString

Valeur cryptée de la clé publique

Récupérés à partie de la requête d’initialisation

redirectionData

NSString

Token unique contenant le contexte de la transaction

redirectionUrl

NSString

Adresse URL M2M

redirectionVersion

NSString

Version de l’interface

Format de la réponse via l’objet DeletePaymentMeanResponse

Paramètres

Type

Commentaires

inAppResponseCode

NSString

Code réponse

errorFieldName

NSString

Nom du champ à l’origine de l’erreur

walletActionDateTime

NSString

Date de realization dans le wallet de l’ajout

Analyser la réponse de gestion du wallet

Etat

Champs de la réponse

Action à réaliser

Opération de gestion Wallet prise en compte

walletLastActionDateTime renseignée avec la date/heure de la dernière action effectuée sur le wallet.

walletPaymentMeanDataList contient les moyens de paiement du wallet après mise à jour

Stockez dans votre base client les données suivantes du wallet: · paymentMeanAlias · paymentMeanId · paymentMeanBrand · PanExpiryDate · maskedPan

Opération de gestion wallet pas prise en compte

walletLastActionDateTime pas renseigné avec date/heure courante

walletPaymentMeanDataList contient les moyens de paiement du wallet

Si la mise jour wallet est requise alors Resoumettez une requête

Etape 4: Tester sur l’environnement de recette

Les étapes de test et d'intégration peuvent être réalisées à l’aide de l'environnement de recette.

L’URL de l’environnement de recette est:
https://office-server-mercanet.test.sips-atos.com/

Pour effectuer ce test, il faut utiliser ces identifiants :
Nom du service de paiement /rs-services/v2/checkoutInApp/orderInitialize
Nom du service de gestion de wallet /rs-services/v2/walletInApp/walletInitialize
ID du Commerçant 211000021310001
Version de la clé 1
Clé sécrète S9i8qClCnb2CZU3y3Vn0toIOgz3z_aBi79akR30vM9o

Dans l’environnement de recette, le processus d’autorisation est simulé. Cela signifie qu’il n’est pas nécessaire d’utiliser des moyens de paiement réels pour effectuer des tests.
Vous pouvez utiliser la carte VISA suivante, pour simuler un paiement accepté:
Carte de test 5017674000000002
Cryptogramme 123
Date de validité doit être supérieure au mois en cours

Etape 5: Valider le passage en production

Une fois la connexion de votre application mobile à Mercanet In-App testée, vous êtes à présent en mesure de valider la connexion à Mercanet In-App de production.

Au préalable, nous conseillons d’isoler votre application mobile du public pour éviter que des clients effectuent des transactions pendant cette phase de validation.

Pour basculer sur le serveur de production, vous devez changer l’URL pour vous connecter au serveur Mercanet de production en utilisant les identifiants reçus lors l’inscription merchantId, secretKey et keyVersion).

URL Mercanet https://office-server.mercanet.bnpparibas.net

merchantId Identifiant de la boutique reçu par mail

SecretKey: Clé secrète que vous récupérez via l’extranet Mercanet Download

KeyVersion: Version clé secrète récupérée sur Mercanet Download (logiquement 1 pour la 1ère clé)

Remarque

Une erreur fréquente est d’oublier un de ces 4 paramètres ce qui conduit systématiquement à une erreur.

Comment valider le bon fonctionnement d’un paiement en production

Immédiatement

  • Faîtes une transaction avec une carte de paiement réelle (si possible la vôtre)
  • Si la transaction est acceptée, elle sera envoyée en banque pour créditer votre compte commerçant et débiter le compte carte.
  • Vérifier que vos pages de paiement intègrent vos paramètres de personnalisation
  • Consultez la transaction via Mercanet Office Extranet à partir du transactionReference

Le lendemain

  • Vérifiez la présence de la transaction dans le journal des transactions
  • Vérifiez sur votre compte que l’opération a bien été créditée
  • Remboursez la transaction via Mercanet Office Extranet (optionnel)

Le surlendemain

  • Vérifiez que l’opération de remboursement apparait dans le journal des opérations
  • Vérifiez sur votre compte commerçant le débit suite au remboursement

Etape 6: Démarrer en production

Une fois la validation du passage en production effectuée, ouvrez votre site au public pour permettre à vos clients d’acheter et de payer.

Dans la journée

  • Surveillez le taux d’acceptation (nombre de responseCode 00/nombre total de transactions).
  • Vérifiez la nature des refus non bancaires
    • Problème technique: responseCode 90, 97, 99
    • Fraude: responseCode 34
    • Nombre max de tentatives de paiement atteint: responseCode 75


Le lendemain

  • Vérifiez dans le journal des transactions la présence de toutes les transactions traitées (acceptées et refusées)
  • Vérifiez dans le journal des opérations les opérations que vous avez effectuées ainsi que les remises (option du journal)