Inapp

De Documentation Mercanet
Aller à : navigation, rechercher

Sommaire

Introduction

Objet du document

Ce document a pour but d’expliquer

  • Comment mettre en œuvre les échanges entre les sites Web des commerçants, les applications mobiles et la solution Mercanet (Cf. Côté serveur).

    Ce document s’adresse à tous les commerçants qui souhaitent souscrire à l’offre Mercanet et avoir recours à un connecteur à base d’échanges JSON via le protocole REST entre les sites des commerçants et les serveurs Mercanet, le tout en utilisant Mercanet comme passerelle.
    L'interface checkout permet de créer une transaction à l'aide d'une carte ou d'un portefeuille électronique.
    L'interface wallet permet de gérer les portefeuilles commerçants pour y ajouter des cartes ou obtenir des informations

  • Comment mettre en œuvre le SDK Android dans l'application commerçant (Cf. 4. [Intégration du SDK Android Intégration du SDK Android]).

    Ce chapitre s’adresse à tous les commerçants qui souhaitent souscrire à l’offre Mercanet et avoir recours à un connecteur à base d’échanges JSON via le protocole REST entre les sites des commerçants et les serveurs Mercanet. Ce chapitre est spécifique à la plateforme Android pour ce qui concerne le développement d’applications mobiles. La version minimale requise du SDK Android est la version 2.3.3.

  • Comment mettre en œuvre le SDK iOS dans l'application commerçant. (Cf. 5. [Intégration du SDK iOS Intégration du SDK iOS]).

    Ce chapitre s’adresse à tous les commerçants qui souhaitent souscrire à l’offre Mercanet et avoir recours à un connecteur à base d’échanges JSON via le protocole REST entre les sites des commerçants et les serveurs Mercanet. Ce chapitre est spécifique à la plateforme Android pour ce qui concerne le développement d’applications mobiles. La version minimale requise du SDK iOS est la version 7.0.

Démonstrations

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

Prérequis

Une connaissance normale des langages de développement Web standard de l’industrie tels que Java, PHP ou .Net est nécessaire pour pouvoir développer un client capable de se connecter à la passerelle Mercanet.
De plus, il est obligatoire de posséder une connaissance approfondie de Java pour développer des applications mobiles pour Android et iOS.
Cette solution garantit que les messages circulant entre le site Internet du commerçant et les serveurs Mercanet sont sécurisés à l’aide de clés secrètes.
Il appartient au commerçant de stocker et gérer ces clés de manière sécurisée.
Remarque

En cas de compromission réelle ou supposée de la clé secrète, il appartient au commerçant de la renouveler par le biais de Mercanet Téléchargement.


Prestataires de services intermédiaires effectuant des opérations Mercanet pour le compte de commerçants

Si vous êtes un prestataire de services intermédiaire qui effectue des opérations Mercanet pour le compte d’un commerçant, vous devez indiquer votre identifiant unique de prestataire de services intermédiaire dans le champ intermediateServiceProviderId. De plus, le sceau devra être calculé avec votre propre clé secrète plutôt qu’avec celle du commerçant que vous représentez.

Veuillez vous référer au guide de configuration des fonctionnalités pour de plus amples informations sur les prestataires de services. En outre, des informations détaillées sur le calcul du sceau sont fournies au chapitre intitulé « Comment signer un message » de ce document.


Principes Généraux

Fichier:Schema inapp.PNG

Toutes les opérations (ordres par carte et portefeuille, gestion des données de portefeuille) utilisent le même principe.

1 & 2. L'application mobile contacte le serveur Mercanet par le biais de son serveur commerçant pour initier une requête en fournissant des données pour effectuer des ordres de paiement ou des opérations de gestion de portefeuille. La requête est alors vérifiée. Si elle est valide, elle est chiffrée (Son nom dans le système est redirectionData.).

3 & 4. De plus, l'application commerçant reçoit l'URL du service Mercanet et la clé publique pour chiffrer les données de la carte durant le paiement.

5. L'application mobile commerçant appelle le SDK pour effectuer un paiement par carte ou gérer un portefeuille et lui fournir la donnée redirectionData reçue. Le SDK chiffre ces données sensibles avec la clé publique fournie.

6. redirectionData et les données carte chiffrées sont envoyés à la plateforme Mercanet.

7 & 8. Le serveur Mercanet traite l'opération requise. En retour, la plateforme Mercanet notifie le statut de l'opération au serveur commerçant et à l'application mobile.

Remarque

Il appartient au commerçant d’éviter les attaques «de l’homme du milieu» (en anglais: man-in-the-middle) entre les flux 1 et 4 (Cf. ).


Côté serveur

Description du protocole

Protocole REST et champs JSON

JSON est une syntaxe utilisée pour le stockage et l’échange d’informations textuelles. Très similaire au XML, JSON est plus compact et s’avère plus facile et plus rapide à analyser.

La manière la plus simple d’accéder à n’importe quel service est d’utiliser cURL.

Exemple de requête cURL en PHP :

<?php

…

// Open cURL session and data are sent to server 
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL,            $url_of_service );
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true );
curl_setopt($ch, CURLOPT_POST,           true );
curl_setopt($ch, CURLOPT_POSTFIELDS,     $data_to_send);
curl_setopt($ch, CURLOPT_HTTPHEADER,     array('Content-Type: application/json', 'Accept: application/json'));
curl_setopt($ch, CURLOPT_PROXY,          $name_and_proxy_port);
$result = curl_exec($ch);
$info = curl_getinfo($ch);

// Manage errors
if ($result == false || $info['http_code'] != 200) {
  echo $result;
  if (curl_error($ch))
    $result .= "\n". curl_error($ch);
}

// Close cURL session
curl_close($ch);
…

?>

Dans les exemples suivants, les données passées au serveur via la requête JSON dépendent entièrement du service auquel vous essayer d’accéder et des champs que nécessite ce dernier.

Pour obtenir des exemples spécifiques, référez-vous à la documentation fournie par chaque service.

Remarque

Les noms des champs sont sensibles à la casse.



Syntaxe de la requête

Le format du champ data est le suivant :

{“<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” }

Tous les champs nécessaires à la transaction (consultez le dictionnaire des données pour en connaître les détails) doivent être présents dans cette chaîne de caractères. L’ordre des champs n’a pas d’importance.

Exemple d’une requête d’initialisation d’ordre:

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


La valeur du champ seal est calculée ainsi :

  • 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 ainsi:

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


Syntaxe d’une liste

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.

  • Liste de champs simples :

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

  • Liste d’objets :

…,“nom du champ” : [{“nom sous-champ1”:”valeur1”,“nom sous-champ2”:”valeur2”},{“nom sous-champ1”:”valeur3”, “nom sous-champ2”:”valeur4”}],…


Syntaxe de concaténation pour les champs composites

Si des champs composites comportant une sous-structure sont utilisés, un calcul de champ spécifique doit être effectué :

  • Concaténation du champ composite et du nom de champ de la sous-structure avec sensibilité à la casse ;
  • Tri de la totalité des champs de la sous-structure, puis tri de ces champs et des autres champs.

Exemple:
Le nom de champ à utiliser pour une byPassCrtList de fraudData doit être fraudDatabyPassCtrlList et sa valeur sera triée avec les autres champs.
Si elle contient All,ForeignBinCard, sa valeur devient AllForeignBinCard pour le calcul du sceau.


Exemple de calcul du champ «seal»

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

…
?>


Requête d’initialisation

Champs d’une requête d’initialisation

Toutes les données d’une requête d’initialisation telles que décrites à la section 3.1 doivent être fournies.La valeur d’interfaceVersion doit être fixée à IR_MB_1.3. Le dictionnaire des données et le chapitre décrivant les messages explicitent tous les paramètres de la requête de paiement, leur format, et leur caractère obligatoire ou facultatif.

L’appel du SDK est en fait une requête JSON envoyée à l’URL indiquée par le paramètre redirectionUrl. Les paramètres à soumettre sont les champs redirectionData et redirectionVersion de la réponse à une requête de paiement.


Exemple de réponse

Un exemple de réponse en JSON est donné ci-dessous :

{"publicKeyValue":"318…010231","redirectionData":"4Agb…x9mCns9Z3E","redirectionStatusCode":"00","redirectionStatusMessage":"INITIALISATION REQUEST ACCEPTED","redirectionUrl":"https://office-server.sips-atos.com/rs-services/v2/checkoutInApp/cardOrder","redirectionVersion":"IR_MB_1.3","seal":"838918a27f8c43935e3cc1d3a86ff61a462b42b580f56b9cd1350e80787044fb"}


Gestion des erreurs

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

redirectionStatusCode

Description

00

Situation normale suivie du processus normal d'affichage des pages mobiles.

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.

30

Le format de la requête est invalide.

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

Tableau n° 1 : Codes de réponse d’une requête d’initialisation

4 cas sont possibles :

  • redirectionStatusCode = 00
    Ce cas doit être suivi de la redirection de l’utilisateur vers la page de paiement.
  • 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. Le commerçant doit réessayer avec une autre référence de transaction.
  • redirectionStatusCode = 99
    Problème de disponibilité du service de paiement. Le commerçant doit 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.


Réponses de paiement

Un seul type de réponse est possible : la notification de paiement. Cette notification n'est pas envoyée lors des opérations de gestion de portefeuille.


Notification

Une réponse automatique n’est envoyée que si le champ automaticResponseUrl a été envoyé dans la requête de paiement. Si c'est le cas, le serveur Mercanet envoie une réponse HTTP POST à l'URL reçue. La seule différence entre les deux procédures est que la réponse automatique est envoyée directement par le serveur Mercanet sans passer par le navigateur Internet de l'utilisateur. Elle est donc plus fiable car systématiquement envoyée. Autre conséquence : la procédure chargée de la réception de la réponse ne doit pas tenter de répondre à l'application appelante. Le serveur Mercanet ne doit attendre aucune réponse suite à la transmission de la réponse automatique. Il appartient au commerçant de récupérer les paramètres de réponse, de les enregistrer sous forme cryptée, de vérifier la signature assurant l'intégrité des champs de réponse, et en conséquence, de mettre à jour le back office commerçant. La réponse contient les quatre champs suivants (sensibles à la casse) :

Nom du champ

Commentaires / Règles

data

Concaténation des champs dans la réponse

encode

Type d’encodage utilisé

seal

Signature du message

interfaceVersion

Version du message contextuel

Tableau n° 2 : Champs de la réponse automatique

Si la valeur d'Encode est “base64” ou “base64url”, le champ data doit être décodé en Base64/Base64Url pour pouvoir récupérer la chaîne concaténée.
La chaîne concaténée possède la structure suivante : clé1=valeur1|clé2=valeur2… Les sceaux des deux réponses sont chiffrés avec le même algorithme que celui utilisé en entrée, lequel est fourni dans le champ sealAlgorithm. Si aucune valeur n’a été définie, l’algorithme par défaut (SHA256) est utilisé. Le contenu du champ data est décrit dans l'annexe 7.8.
Remarque

Les noms des paramètres de la réponse automatique sont sensibles à la casse. La version actuelle de la réponse automatique est HP_2.16. Consultez le Dictionnaire des Données Mercanet pour obtenir la description complète des paramètres contenus dans la réponse.


Syntaxe du champ «seal» de la réponse

Pour qu’un sceau soit calculé avec l'algorithme HMCA-SHA-256, les paramètres d'entrée de la requête doivent contenir le champ sealAlgorithm avec la valeur suivante : “HMAC-SHA-256”. Si aucune valeur n’a été définie, l’algorithme par défaut (SHA256) est utilisé.

Contrairement à celui de la requête Mercanet, le sceau de la réponse est calculé sur la totalité du champ data reçu dans la réponse. La valeur du champ seal est calculée ainsi :

Pour l’algorithme HMAC-SHA256

  • La clé secrète partagée est utilisée pour générer la variante HMAC du condensat.
  • Seul le champ data est utilisé.
  • Obtention de l’encodage UTF-8 des données du résultat précédent
  • Chiffrement des octets obtenus avec l'algorithme HMAC-SHA256

Cette procédure peut être résumée ainsi:

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

Pour l’algorithme SHA256 (valeur par défaut)

  • Concaténation du champ data et de la clé secrète
  • Obtention de l’encodage UTF-8 des données du résultat précédent
  • Chiffrement SHA256 des octets obtenus

Cette procédure peut être résumée ainsi: SHA256( UTF-8(Data+secretKey ) )


Problème de réception des réponses Mercanet
Vous trouverez ci-dessous la liste des problèmes qui empêchent le plus fréquemment la réception des réponses automatiques et manuelles. Assurez-vous de les avoir vérifiés avant d'appeler le service d'assistance technique.
  • Vérifiez que les URL de réponse sont fournies dans la requête de paiement et qu'elles sont valides. Vous pouvez tout simplement copier-coller ces URL dans la barre d'adresse de votre navigateur pour en vérifier la validité.
  • Les URL fournies être accessible à distance, c'est à dire via Internet. Un contrôle d'accès (nom d'utilisateur/mot de passe ou filtre IP) ou un pare-feu peuvent bloquer l'accès à votre serveur.
  • Les accès aux URL de réponse doivent apparaître dans le journal de notifications de votre serveur Web.
  • Si vous utilisez un port non standard, il doit être faire partie de la plage [80-9999] pour être compatible avec Mercanet.
  • Il n’est pas possible d’ajouter des paramètres contextuels aux URL de réponse. Le champ orderID est conçu pour recevoir des paramètres supplémentaires. Alternativement, un «sessionID» permettra au commerçant de retrouver les informations du client à la fin du processus de paiement.


Gestion des erreurs - Absence de signature dans la réponse

Dans certains cas d'erreur, le serveur Mercanet est incapable de signer le message de réponse. C'est le cas par exemple lors d'une erreur Unknown Merchant ID ou si la clé secrète est inconnue de Mercanet.

Pour ces raisons, le serveur de paiement enverra dont le champ seal ne contiendra pas de signature.


Comment SIGNER un MESSAGE

Motifs de signature d'un message

Une vérification concluante de signature nécessite deux éléments :

  • l’intégrité des messages de la requête et de la réponse : aucune altération ne doit avoir eu lieu pendant l’échange.
  • l’authentification de l’émetteur et du destinataire, car ils partagent la même clé secrète.

Remarque

En cas de compromission réelle ou supposée de la clé utilisée pour la signature, il appartient au commerçant d’obtenir son renouvellement par le biais de Mercanet Téléchargement.


Méthode de signature d’un message

L’opération de signature est effectuée en calculant une valeur cryptée basée sur les paramètres de la transaction (valeurs des champs) à laquelle est ajoutée la clé secrète (inconnue de l’internaute). Toutes les chaînes de caractères sont converties en UTF8 avant chiffrement.

L’algorithme de chiffrement (HMAC-SHA256) produit un résultat irréversible. Généralement, lorsqu’un message de cette nature est reçu, son destinataire doit recalculer la valeur cryptée afin de la comparer à la valeur reçue. Toute différence indique que les données échangées ont été falsifiées.

Le résultat au format hexadécimal doit être envoyé dans le champ nommé Seal.


Exemples de code

Php 5
<?php

…

echo hash_mac('sha256', $data, $secretKey);

…

?>

«data» 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.


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

}


.net

(Effectué à l’aide d’un simple formulaire nommé « Form1 » contenant deux champs texte pour saisir txtSips, 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 = txtSips.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();
        }

    }
}


TESTS

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

Afin de pouvoir l’utiliser, vous devez contacter l'assistance technique en indiquant les services dont vous avez besoin. L'assistance technique vous enverra un identifiant commerçant (merchantId) et une clé secrète.

Les détails techniques nécessaires pour utiliser l’environnement de recette sont fournis ci-dessous :

Service URL
URL de recette https://office-server-mercanet.test.sips-atos.com
Nom du service de paiement /rs-services/v2/checkoutInApp
Nom du service de gestion de portefeuilles /rs-services/v2/walletInApp


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.


Tester les transactions par carte

Pour connaître les cartes utilisables sur l'environnement de recette, veuillez vous rendre sur la page : [Cartes de test|https://documentation.mercanet.bnpparibas.net/index.php/Cartes_de_test Cartes de test]


Mise en production

L'étape suivante consiste à se connecter à l'environnement de production pour la mise en production effective. Pour réaliser cette opération, le commerçant doit modifier l'URL du serveur Office et utiliser les identifiants commerçant reçus durant la phase d’inscription.


Identifiants commerçant

L'URL du serveur de paiement de production est suivante : https://office-server.mercanet.bnpparibas.net

Pour accéder à l’environnement de production, trois éléments sont nécessaires :

  • l’identifiant commerçant (merchantID) qui identifie le site de commerce électronique sur le serveur Mercanet
  • la version (keyVersion) de la clé secrète
  • la clé secrète (secretKey) utilisée pour signer les requêtes et vérifier les réponses.

L’identifiant commerçant (merchantID) est fourni par l’assistance technique à l’issue de l’inscription du commerçant. La version de la clé (keyVersion) et la clé secrète (secretKey) peuvent être téléchargées depuis l’extranet Mercanet Téléchargement à l’aide du nom d’utilisateur et du mot de passe fournis par l’assistance technique à l’issue de l’inscription du commerçant.


Validation en production

À partir du moment où le commerçant utilise ses propres identifiants sur le serveur de production, toutes les transactions et opérations de gestion de caisse sont réelles (par exemple, les transactions de paiement sont réelles de bout en bout, c’est-à-dire jusqu'à ce que les fonds soient crédités sur le compte du commerçant et débités de celui de l'acheteur). Avant l'ouverture réelle de la boutique au public, le commerçant peut soumettre une requête pour valider le paiement de bout en bout, c’est à dire jusqu'à ce que les fonds soient crédités sur son compte et débités de celui de l'acheteur.


Description des services d’initialisation

Description du service checkoutInApp

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

Ce service permet de réaliser un ordre de paiement à l'aide d'une carte ou d'un portefeuille électronique.


Service orderInitialize

L’URL en est https://office-server.mercanet.bnpparibas.net/rs-services/v2/checkoutInApp/orderInitialize

Une requête d’initialisation de commande par carte ou portefeuille inclut les éléments suivants :

  • Paramètres d’entrée par défaut

Champ

Présence

A partir de la version

Commentaires

amount

Obligatoire

MB_1.0

automaticResponseUrl

Facultatif

MB_1.0

captureDay

Facultatif

MB_1.0

captureMode

Facultatif

MB_1.0

currencyCode

Obligatoire

MB_1.0

customerEmail

Facultatif

MB_1.0

customerId

Facultatif

MB_1.0

customerLanguage

Facultatif

MB_1.0

interfaceVersion

Obligatoire

MB_1.0

Valeur fixée à IR_MB_1.1

intermediateServiceProviderId

Facultatif

MB_1.2

invoiceReference

Facultatif

MB_1.1

keyVersion

Obligatoire

MB_1.0

merchantId

Obligatoire

MB_1.0

merchantWalletId

Facultatif

MB_1.0

sdkOperationName

Obligatoire

MB_1.1

CARDORDER ou WALLETORDER ou PAYMENTPROVIDERORDER ou THREEDSECUREANDORDER

orderId

Facultatif

MB_1.0

paymentMeanBrand

Obligatoire

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

transactionReference

Facultatif

MB_1.0

Le champ s10TransactionId doit être rempli si celui-ci ne l’est pas.

seal

Obligatoire

MB_1.0

statementReference

Facultatif

MB_1.1

s10TransactionReference

Facultatif

MB_1.3

Cf. objet s10TransactionReference plus bas

Tableau n° 3 : Champs d’une requête orderInitialize

Paramètres d’entrée de s10TransactionReference

Champ

Présence

A partir de la version

Commentaires

s10TransactionId

Facultatif

MB_1.3

Le champ transactionReference doit être rempli si celui-ci ne l’est pas.

s10TransactionIdDate

Facultatif

MB_1.3

orderInitialize - Données de sortie

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

Tableau n° 4 : Champs de la réponse à une requête orderInitialize

orderInitialize - Exemples

Exemple de requête orderInitialize

{"amount" : "1000","automaticResponseUrl" : "http://urlofautomaticresp.jsp","currencyCode" : "978","interfaceVersion" : "IR_MB_1.0","keyVersion" : "1","merchantId" : "12345678912345","paymentMeanBrand" : "VISA","sdkOperationName" : "CARDORDER","sdkVersion" : "SDK100","transactionReference" : "SIM20140717163340","seal" : "1bcce4ffda76d7a72812e950fa2df05fe22f37594b627b9f1932a10be2401829"}

Exemple de réponse à une requête orderInitialize

{"publicKeyValue":"30820122…10001","redirectionData":"4AgbsrffvP…dfx9mCns9Z3E","redirectionStatusCode":"00","redirectionStatusMessage":"Validation succeed","redirectionUrl":"https://office-server.test.sips-atos.com/rs-services/v2/checkoutInApp/cardOrder","redirectionVersion":"IR_MB_1.0","seal":"0abbfebf740b09993ac36a9173a791809b7fd6c4cc40df8695f56695ad815dda"}


Description du service walletInApp

Service walletInitialize

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

Ce service vous permet de gérer les portefeuilles commerçant par ex. d’ajouter un moyen de paiement à un portefeuille ou de récupérer des informations de portefeuilles.

Requêtes de gestion de portefeuille commerçant:

  • Paramètres d’entrée par défaut

Champ

Présence

A partir de la version

Commentaires

automaticResponseUrl

Facultatif

MB_1.0

interfaceVersion

Obligatoire

MB_1.0

Valeur fixée à IR_MB_1.0

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 ou GETWALLETDATA

sealAlgorithm

Facultatif

MB_1.1

sdkVersion

Facultatif

MB_1.0

Valeur fixée à SDK100

keyVersion

Facultatif

MB_1.0

seal

Facultatif

MB_1.0

Tableau n° 5 : Champs d’une requête walletInitialize

  • Données de sortie

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

Tableau n° 6 : Champs de la réponse à une requête walletInitialize

walletInitialize - Exemples

Exemple de requête walletInitialize

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


Exemple de réponse à une requête walletInitialize

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


Intégration du SDK Android

Importation du SDK dans un projet

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

Le SDK peut être télécharger ici : [SDK Android]

Importation de la bibliothèque avec Eclipse

Pour utiliser cette bibliothèque dans l’application commerçant avec un JAR, ajoutez le JAR du SDK au dossier de compilation du projet.

Exemple avec Eclipse IDE :

  1. Faites un clic droit sur le projet commerçant.
  2. Sélectionnez Properties.
  3. Cliquez sur Java Build Path.
  4. Dans l’onglet Libraries, cliquez sur Add JARs.
  5. Sélectionnez le JAR du SDK et cliquez sur OK.


Importation de la bibliothèque avec Android Studio et Gradle

Pour utiliser cette bibliothèque dans l’application commerçant avec un fichier AAR, ajoutez le fichier AAR du SDK au dossier libs.

Exemple avec Android Studio :

  • Dans le fichier gradle,
    • ajoutez le code suivant dans la partie
flatDir {
    dirs 'libs'
}
  • ajoutez la dépendance suivante :
compile(name: 'wl-sips-inapp-sdk-1.3.1', ext: 'aar')
compile 'com.google.code.gson:gson:2.2.2'


Permissions du Manifeste

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

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

NB : la permission GET_ACCOUNTS et READ_PHONE_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

Utilisation du SDK

Méthodes exposées

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

Remarque

Ces méthodes doivent être appelées dans une AsyncTask.



cardOrder

Cette méthode est utilisée pour effectuer un paiement par carte. Elle est appelée après une commande OrderInitialize

Sa signature est la suivante :

PaymentManager.cardOrder(Context context, String cardNumber, String cardCSCValue, String cardExpiryDate, String publicKeyValue, String redirectionData, String redirectionUrl, String redirectionVersion)


Paramètres

Type

Commentaires

Context

Context

Contexte Android

cardNumber

String

Numéro de carte

cardCSCValue

String

Code confidentiel

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
(Récupérés à partie de la requête d’initialisation)

redirectionUrl

String

Adresse URL M2M
(Récupérés à partie de la requête d’initialisation)

redirectionVersion

String

Version de l’interface
(Récupérés à partie de la requête d’initialisation)

La méthode retourne un objet OrderResponse (Cf. annexes).


getWalletData

Cette méthode est utilisée pour récupérer les cartes sauvegardées dans le portefeuille. Elle est appelée après une commande WalletInitialize .

Sa signature est la suivante :

PaymentManager.getWalletData(String publicKeyValue, String redirectionData, String redirectionUrl, String redirectionVersion, Context context)


Paramètres

Type

Commentaires

Context

Context

Contexte Android

redirectionVersion

String

Version de l’interface

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

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

redirectionUrl

String

Adresse URL M2M

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

La méthode retourne un objet GetWalletDataResponse (Cf. annexes).


walletOrder

Cette méthode est utilisée pour effectuer un paiement par portefeuille. Elle est appelée après une commande OrderInitialize.

Sa signature est la suivante :

PaymentManager.walletOrder(Integer paymentMeanId, String publicKeyValue, String redirectionData, String redirectionUrl, String redirectionVersion, Context context)


Il est également possible de préciser cardCscValue :

PaymentManager.walletOrder(Integer paymentMeanId, String cardCscValue, String publicKeyValue, String redirectionData, String redirectionUrl, String redirectionVersion, Context context)

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

Code confidentiel (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

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

redirectionUrl

String

Adresse URL M2M
(Récupérés à partie de la requête d’initialisation)

La méthode retourne un objet OrderResponse (Cf. annexes).


addCard

Cette méthode est utilisée pour stocker une carte dans un portefeuille client. Elle est appelée après une commande WalletInitialize .

Sa signature est la suivante :

PaymentManager.addCard(Context context, String cardNumber, String paymentMeanAlias, String cardExpiryDate, String publicKeyValue, String redirectionData, String redirectionUrl, String redirectionVersion)


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

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
(Récupérés à partie de la requête d’initialisation)

redirectionUrl

String

Adresse URL M2M
(Récupérés à partie de la requête d’initialisation)

redirectionVersion

String

Version de l’interface

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

La méthode retourne un objet AddCardReponse (Cf. annexes).


paymentProviderOrder

Cette méthode est utilisée pour préparer un ordre BCMC et obtenir l'URL Intent BCMC à appeler. Elle est appelée après une commande OrderInitialize avec OperationType=PAYMENTPROVIDERORDER et paymentMeanBrand= BCMCMOBILE .

Sa signature est la suivante :

PaymentManager.paymentProviderOrder(Context context, String publicKeyValue, String redirectionData, String redirectionVersion, String redirectionUrl)

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
(Récupérés à partie de la requête d’initialisation)

redirectionUrl

String

Adresse URL M2M

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

redirectionVersion

String

Version de l’interface
(Récupérés à partie de la requête d’initialisation)

La méthode retourne un objet PaymentProviderResponse (Cf. annexes).


getTransactionData

Cette méthode 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.

Sa signature est la suivante :

PaymentManager.getTransactionData(Context context, String transactionContextData, String transactionContextVersion, String redirectionUrl)


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 d’initialisation)

transactionContextVersion

String

Version du contexte de la transaction
(Récupérés à partie de la requête d’initialisation)

redirectionUrl

String

Adresse URL M2M
(Récupérés à partie de la requête d’initialisation)

La méthode retourne un objet GetTransactionDataResponse (Cf. annexes).


cardCheckEnrollment

La méthode est utilisée pour préparer un ordre 3D Secure et obtenir le message paReq («Payer Authentication Request») et l'URL de l'ACS (Access Control Server) à appeler. Elle est appelée après une commande OrderInitialize avec OperationType= THREEDSECUREANDORDER .

Sa signature est la suivante :

PaymentManager.cardCheckEnrollment(Context context, String cardNumber, String cardCSCValue, String cardExpiryDate, String publicKeyValue, String redirectionData, String redirectionUrl, String redirectionVersion)

Paramètres

Type

Commentaires

Context

Context

Contexte Android

cardNumber

String

Numéro de carte

cardCSCValue

String

Code confidentiel

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
(Récupérés à partie de la requête d’initialisation)

redirectionUrl

String

Adresse URL M2M
(Récupérés à partie de la requête d’initialisation)

redirectionVersion

String

Version de l’interface
(Récupérés à partie de la requête d’initialisation)

La méthode retourne un objet CardCheckEnrollmentResponse (Cf. annexes).

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

  • PAReq message retourné par la fonction checkEnrollment dans le champ redirectionData.
  • 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 le site Web du commerçant. Alternativement, il peut contenir le merchantSessionId retourné par checkEnrollment (ThreedSecureService).
  • 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 du site Web du commerçant 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 du commerçant 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
		}
	}
}


cardValidateAuthenticationAndOrder

Cette méthode est utilisée pour valider l'authentification et l'ordre de l'ordre 3DS après vérification par l'ACS. Elle est appelée après un appel à cardCheckEnrollment, lorsque l'ACS renvoie le message paRes.

Sa signature est la suivante :

PaymentManager.cardValidateAuthenticationAndOrder(Context context, String paResMessage, String transactionContextData, String redirectionUrl, String transactionContextVersion)

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.

transactionContextData

String

Token unique contenant le contexte de la transaction
(Récupérés à partie de la requête d’initialisation)

transactionContextVersion

String

Version du contexte de la transaction

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

redirectionUrl

String

Adresse URL M2M
(Récupérés à partie de la requête d’initialisation)

La méthode retourne un objet OrderResponse (Cf. annexes).


Intégration du SDK iOS

Importation du SDK dans un projet

Importation du projet

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écharger ici : [SDK iOS]

Lier le binaire aux bibliothèques

Dans le projet commerçant, vous devez lier le fichier SDK.

Pour ce faire, dans XCode :

  1. Cliquez sur le projet d’application commerçant.
  2. Cliquez sur l’application commerçant cible.
  3. Cliquez sur l’onglet Build phases.
  4. Développez la rubrique Link Binary With Libraries.
  5. Cliquez sur le symbole “+”.
  6. Sélectionnez le fichier InAppSdk.framework.

Cela est parfois fait automatiquement.


Lier des binaires intégrés

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

Pour ce faire, dans XCode :

  1. Cliquez sur le projet d’application commerçant.
  2. Cliquez sur l’application commerçant cible.
  3. Cliquez sur l’onglet General.
  4. 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

Utilisation du SDK

Méthodes exposées

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

Ces méthodes doivent être appelées dans une requête synchrone.

Pour générer le sceau dans les méthodes Initialize, vous pouvez utiliser la méthode sign de la classe INAPPHmac.

+ (NSData*) sign:(NSData *) data withKey:(NSData *) key;


cardOrder

Cette méthode est utilisée pour effectuer un paiement par carte. Elle est appelée après une commande OrderInitialize .

Sa signature est :

+ (void) cardOrderWithCardNumber:(NSString *) cardNumber
                 andCardCSCValue:(NSString *) CardCSCValue
               andCardExpiryDate:(NSString *) cardExpiryDate
               andPublicKeyValue:(NSString *) publicKeyValue
              andRedirectionData:(NSString *) redirectionData
               andRedirectionUrl:(NSString *) redirectionUrl
           andRedirectionVersion:(NSString *) redirectionVersion
                      andHandler:(void (^)(INAPPOrderResponse * response)) handler;

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
(Récupérés à partie de la requête d’initialisation)

redirectionUrl

NSString

Adresse URL M2M
(Récupérés à partie de la requête d’initialisation)

redirectionVersion

NSString

Version de l’interface
(Récupérés à partie de la requête d’initialisation)

handler

void (^)(INAPPOrderResponse * response)

Handler alimenté à la fin de l'appel

La méthode retourne un objet INAPPOrderResponse dans l'objet handler contenant la réponse du serveur Mercanet (Cf. annexes).


getWalletData

Cette méthode est utilisée pour récupérer les cartes sauvegardées dans le portefeuille. Elle est appelée après une commande WalletInitialize.

Sa signature est :

+ (void) getWalletDataWithPublicKeyValue:(NSString * ) publicKeyValue
                      andRedirectionData:(NSString *) redirectionData
                       andRedirectionUrl:(NSString *) redirectionUrl
                   andRedirectionVersion:(NSString *) redirectionVersion
                              andHandler:(void (^)(INAPPGetWalletDataResponse * response)) handler;

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
(Récupérés à partie de la requête d’initialisation)

redirectionUrl

NSString

Adresse URL M2M
(Récupérés à partie de la requête d’initialisation)

handler

void (^)(INAPPGetWalletDataResponse * response)

Handler alimenté à la fin de l'appel

La méthode retourne un objet INAPPGetWalletDataResponse dans l'objet handler contenant la réponse du serveur Mercanet (Cf. annexes).


walletOrder

Cette méthode est utilisée pour effectuer un paiement par portefeuille. Elle est appelée après une commande OrderInitialize.

Sa signature est :

+ (void) walletOrderWithPaymentMeanId:(NSInteger) paymentMeanId
                    andPublicKeyValue:(NSString * ) publicKeyValue
                   andRedirectionData:(NSString *) redirectionData
                    andRedirectionUrl:(NSString *) redirectionUrl
                andRedirectionVersion:(NSString *) redirectionVersion
                           andHandler:(void (^)(INAPPOrderResponse * response)) handler;

Il est également possible de préciser cardCscValue :

+ (void) walletOrderWithPaymentMeanId:(NSInteger) paymentMeanId
                          andCscValue:(NSString *) cscValue
                    andPublicKeyValue:(NSString *) publicKeyValue                                                    
                   andRedirectionData:(NSString *) redirectionData
                    andRedirectionUrl:(NSString *) redirectionUrl
                andRedirectionVersion:(NSString *) redirectionVersion
                           andHandler:(void (^)(INAPPOrderResponse * response)) handler;

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
(Récupérés à partie de la requête d’initialisation)

redirectionUrl

NSString

Adresse URL M2M
(Récupérés à partie de la requête d’initialisation)

handler

void (^)(INAPPOrderResponse * response)

Handler alimenté à la fin de l'appel

La méthode retourne un objet INAPPOrderResponse dans l'objet handler contenant la réponse du serveur Mercanet (Cf. annexes).


addCard

Cette méthode est utilisée pour stocker une carte dans un portefeuille client. Elle est appelée après une commande WalletInitialize.

Sa signature est :

+ (void) addCardWithCardNumber:(NSString *) cardNumber
           andPaymentMeanAlias:(NSString *) paymentMeanAlias
             andCardExpiryDate:(NSString *) cardExpiryDate
             andPublicKeyValue:(NSString * ) publicKeyValue
            andRedirectionData:(NSString *) redirectionData
             andRedirectionUrl:(NSString *) redirectionUrl
         andRedirectionVersion:(NSString *) redirectionVersion
                    andHandler:(void (^)(INAPPAddCardResponse * response )) handler;

Paramètres

Type

Commentaires

cardNumber

NSString

Numéro de carte

paymentMeanAlias

NSString

Alias de la carte

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
(Récupérés à partie de la requête d’initialisation)

redirectionUrl

NSString

Adresse URL M2M
(Récupérés à partie de la requête d’initialisation)

redirectionVersion

NSString

Version de l’interface
(Récupérés à partie de la requête d’initialisation)

handler

void (^)(INAPPAddCardResponse * response)

Handler alimenté à la fin de l'appel

La méthode retourne un objet INAPPAddCardResponse dans l’objet handler contenant la réponse du serveur Mercanet (Cf. annexes).


paymentProviderOrder

Cette méthode est utilisée pour préparer un ordre BCMC et obtenir l'URL Intent BCMC à appeler. Elle est appelée après une commande OrderInitialize avec OperationType=PAYMENTPROVIDERORDER et paymentMeanBrand= BCMCMOBILE .

Sa signature est :

+ (void) paymentProviderOrderWithPublicKeyValue:(NSString * ) publicKeyValue
                             andRedirectionData:(NSString *) redirectionData
                              andRedirectionUrl:(NSString *) redirectionUrl
                          andRedirectionVersion:(NSString *) redirectionVersion
                                     andHandler:(void (^)(void (^)(INAPPPaymentProviderResponse * response))) handler

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
(Récupérés à partie de la requête d’initialisation)

redirectionUrl

NSString

Adresse URL M2M
(Récupérés à partie de la requête d’initialisation)

redirectionVersion

NSString

Version de l’interface
(Récupérés à partie de la requête d’initialisation)

handler

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

Handler alimenté à la fin de l'appel

La méthode retourne un objet INAPPPaymentProviderResponse dans l’objet handler contenant la réponse du serveur Mercanet (Cf. annexes).


getTransactionData

Cette méthode 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.

Sa signature est :

+ (void) getTransactionDataWithRedirectionUrl:(NSString *) redirectionUrl
                    andTransactionContextData:(NSString *) transactionContextData
                 andTransactionContextVersion:(NSString *) transactionContextVersion
                                   andHandler:(void (^)(INAPPGetTransactionDataResponse * response)) handler;

Paramètres

Type

Commentaires

transactionContextData

NSString

Token unique contenant le contexte de la transaction
(Récupérés à partie de la requête d’initialisation)

transactionContextVersion

NSString

Version du contexte de la transaction
(Récupérés à partie de la requête d’initialisation)

redirectionUrl

NSString

Adresse URL M2M
(Récupérés à partie de la requête d’initialisation)

handler

void (^)(INAPPGetTransactionDataResponse * response)

Handler alimenté à la fin de l'appel

La méthode retourne un objet INAPPGetTransactionDataResponse dans l’objet handler contenant la réponse du serveur Mercanet (Cf. annexes).


cardCheckEnrollment

La méthode est utilisée pour préparer un ordre 3D Secure et obtenir le message paReq («Payer Authentication Request») message et l'URL de l'ACS (Access Control Server) à appeler. Elle est appelée après une commande OrderInitialize avec OperationType= THREEDSECUREANDORDER.

Sa signature est la suivante :

+ (void) cardCheckEnrollmentWithCardNumber:(NSString *) cardNumber
                 andCardCSCValue:(NSString *) CardCSCValue
               andCardExpiryDate:(NSString *) cardExpiryDate
               andPublicKeyValue:(NSString *) publicKeyValue
              andRedirectionData:(NSString *) redirectionData
               andRedirectionUrl:(NSString *) redirectionUrl
           andRedirectionVersion:(NSString *) redirectionVersion
                      andHandler:(void (^)(INAPPCardCheckEnrollmentResponse * response)) handler;

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
(Récupérés à partie de la requête d’initialisation)

redirectionUrl

NSString

Adresse URL M2M
(Récupérés à partie de la requête d’initialisation)

redirectionVersion

NSString

Version de l’interface
(Récupérés à partie de la requête d’initialisation)

handler

void (^)(INAPPCheckEnrollmentResponse * response)

Handler alimenté à la fin de l'appel

La méthode retourne un objet INAPPCheckEnrollmentResponse dans l’objet handler contenant la réponse du serveur Mercanet (Cf. annexes).

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

  • PAReq message retourné par la fonction checkEnrollment dans le champ redirectionData.
  • 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 le site Web du commerçant. Alternativement, il peut contenir le merchantSessionId retourné par checkEnrollment (ThreedSecureService).
  • 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 du site Web du commerçant 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
         andTransactionContextData:self.transactionContextData
         andRedirectionUrl:self.redirectionUrl
         andTransactionContextVersion:self.transactionContextVersion
         andHandler:^(NSDictionary *result) {
             //Do something with cardValidateAuthentication response
         }];
        // Cancel the location change
        return NO;
    }    
    // Accept this location change
    return YES;    
}

@end


cardValidateAuthenticationAndOrder

Cette méthode est utilisée pour valider l'authentification et l'ordre de l'ordre 3DS après vérification 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.
Sa signature est la suivante :

+ (void) cardValidateAuthenticationAndOrderWithPaResMessage:(NSString *) paResMessage
                             andTransactionContextData:(NSString *) transactionContextData
                                     andRedirectionUrl:(NSString *) redirectionUrl
                          andTransactionContextVersion:(NSString *) transactionContextVersion
                                            andHandler:(void (^)(INAPPOrderResponse * response)) handler

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.

transactionContextData

NSString

Token unique contenant le contexte de la transaction
(Récupérés à partie de la requête d’initialisation)

transactionContextVersion

NSString

Version du contexte de la transaction
(Récupérés à partie de la requête d’initialisation)

redirectionUrl

NSString

Adresse URL M2M
(Récupérés à partie de la requête d’initialisation)

handler

void (^)(INAPPOrderResponse * response)

Handler alimenté à la fin de l'appel

La méthode retourne un objet INAPPOrderResponse dans l'objet handler contenant la réponse du serveur Mercanet (cf. annexes).


PCI-DSS

Les contraintes PCI-DSS sont allégées du fait que les données carte chiffrées transitent entre les applications mobiles et le serveur Mercanet. Les données carte ne transitent jamais par le serveur du commerçant et cela ne doit jamais être le cas. Par conséquent, l'application commerçant n'a pas à se conformer à la norme PCI-DSS ; elle doit simplement respecter les pratiques d'excellence PCI-DSS ().


Annexes

Objet OrderResponse

Description de OrderResponse et INAPPOrderResponse :

Nom du champ

Format

Description

acquirerResponseCode

String

Code de réponse acquéreur

amount

String

Montant de la transaction

authorisationId

String

Identifiant d’autorisation

captureDay

String

Délai de capture

captureMode

String

Mode de capture

cardExpiryDate

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

merchantWalletId

String

Identifiant de portefeuille commerçant

orderChannel

String

Canal de commande

orderId

String

Identifiant de commande

panEntryMode

String

paymentMeanBrand

String

Moyen de paiement sélectionné

paymentMeanBrandSelectionStatus

String

paymentMeanType

String

Moyen de paiement utilisé

paymentPattern

String

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

returnContext

String

s10TransactionRefeence

INAPPS10TransactionReference

statementReference

String

transactionDateTime

Date

transactionOrigin

String

Origine de la transaction

transactionPlatform

String

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

transactionReference

String

Identifiant de la transaction


Objet getWalletData

Description de getWalletData et INAPPGetWalletData :

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 portefeuille

walletPaymentMeanData

Liste de walletPaymentMeanData

Liste des cartes sauvegardées dans le portefeuille

Les objets walletPaymentMeanData et INAPPWalletPaymentMeanData contiennent les champs suivants:

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


Objet addCardResponse

Description des objets addCardResponse et INAPPAddCardResponse :

Paramètres

Type

Commentaires

InAppResponseCode

String

Date d’expiration de la carte

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 d'action du portefeuille


Objet paymentProviderOrderResponse

Description des objets paymentProviderOrderResponse et INAPPPaymentProviderOrderResponse:

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

Message PaReq utilisé pour l’authentification ACS

transactionContextData

String

URL de redirection pour l’appel suivant

transactionContextVersion

String

Contexte de la transaction


Objet getTransactionDataResponse

Description de getTransactionDataResponse et INAPPGetTransactionDataResponse :

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

Moyen de paiement utilisé

paymentPattern

String

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

s10TransactionReference

INAPPS10TransactionReference

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 portefeuille


S10TransactionReference

S10TransactionReference et INAPP S10TransactionReference description:

Nom du champ

Format

Description

s10TransactionId

String

s10TransactionIdDate

String


Objet checkEnrollmentResponse

Description de checkEnrollmentResponse et INAPPCheckEnrollmentResponse :

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


Réponse automatique

Le contenu peut varier en fonction du résultat (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
Consultez les sections 7.8.1pour connaitre son contenu et 7.8.2 pour son format.

preAuthenticationThreshold

HP_2.10

preAuthenticationValue

HP_2.10

preAuthorisationProfile

HP_2.14

preAuthorisationProfileValue

HP_2.14

preAuthorisationRuleResultList

HP_2.14

Liste d’objets ruleResult Consultez les sections 7.8.1pour connaitre son contenu et 7.8.2 pour son format.

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.


Objet ruleResult

Champ

A partir de la 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 : 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