Tutoriel pour apprendre l'intégration de l'API de paiement Mobile Money AByster sur un site marchand

La prolifération des sites web de e-commerce, amène plusieurs banques et entreprises à se lancer dans le développement des solutions de paiement en ligne. Aujourd'hui, il en existe plusieurs, notamment : Paypal, Visa et bien d'autres.

AByster est l'une de ces solutions de paiement en ligne, mais ayant la particularité d'utiliser le Mobile Money. Pour le moment, le système est disponible uniquement dans les pays d'Afrique représentés sur la figure 1 ci-dessous disposant des services Mobile Money, car dans d'autres pays notamment en Afrique de l'Est, d'autres opérateurs y sont présents et disposent d'un autre système de paiement par mobile : le M-Pesa3M-Pesa par exemple. La solution de paiement fonctionne actuellement au Cameroun et au Sénégal.

La solution ABYster fonctionne actuellement pour les opérateurs téléphoniques MTN et Orange.

Le présent tutoriel a pour objet de présenter comment intégrer la version 2.0 de l'API AByster sur un site web de e-commerce développé en PHP.

Il donne aux web masters et développeurs des informations utiles leur permettant d'utiliser facilement l'API AByster sur des sites et applications web.

Le présent document fait partie intégrante des ressources soumises aux CGU (Conditions Générales d'Utilisation) du service Abyster.

1. Un éditeur de code source PHP de votre choix. Nodepad++, SublimeTex…
2. Un compte Entreprise sur la plateforme AbysterURL.
   Un serveur Apache : l'outil EasyPHP est suffisant pour ce tutoriel.

Pour être autorisé à utiliser les API AByster, il faut posséder un compte AByster Entreprise (dit compte Marchand). Pour ce faire, clic sur le bouton Ouvrir un compte sur le site AByster et suivez les étapes.

À la fin du processus de création de compte, vous recevez par mail vos paramètres d'authentification pour l'utilisation des API.

· Clé privée (clé privée du compte AByster du marchand : consummerSecret).

· Identifiant (Identifiant du compte Abyster du marchand : consummerId).

Dans ce tutoriel, nous considérons un minisite marchand fournissant une vitrine permettant d'acheter via Mobile Money l'un de ses quatre produits phares.

Étape1 : Création de compte Marchand sur la plateforme de test

• Allez sur http://sandbox-abyster.appspot.com, cliquez sur le bouton Ouvrir un compte

Ici, le système vérifie si le numéro de téléphone ou l'e-mail ne sont pas encore alloués à un marchand.

• Complétez la création de votre compte si la vérification est positive.

• Vous recevez par e-mail vos paramètres d'authentification pour l'utilisation de l'API.

Étape2 : Configuration des paramètres d'appel

Une fois votre compte AByster créé, vous pouvez utiliser l'API moyennant le respect des structures des requêtes qui lui sont destinées.

Chaque appel à l'API doit se faire via une requête HTTP possédant les paramètres d'entête avec des valeurs spécifiques :

• Accept : « application/json»
• Accept-Encoding : « deflate »
• Content-Type : « application/json »

code php

Sélectionnez

1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21.
22.
23.
24.
25.
26.
27.
28.
29.
30.
31.
32.
33.
34.
35.
36.
37.
38.
39.
40.
41.
42.
43.
44.
45.
46.
47.
48.
49.
50.
51.
52.
53.
54.
55.
56.
57.
58.
59.
60.
61.
62.
63.
64.
65.
66.
67.
68.
69.
70.
71.
72.
73.
74.
75.
76.
77.
78.
79.
80.
81.
82.
83.
84.
85.
86.
87.
88.
89.
90.
91.
92.
93.
94.
95.
96.
97.
98.

<?php
    

$ApiUrl='http://sandbox-abyster.appspot.com/rest/api/v2';
$consumerId='5671831268753408';
$consumerName='employeur';
$consumerEmail='demoshop@demoshop.com';
$consumerSecret='CA1764U8MRL4E65H5EIA19K0FIAFL-e21a6b31-6f9e-4163-b6d6-41a230ceaac9';//'8EE5GRNUTM2CVVE8C7KRIUS4UEMVP-b0b3c3a7-7b62-4a2f-afd0-4ce3320226d4';
$consumerTimestamp=substr(date('Ymdhisu'),0,17);
//echo $consumerTimestamp."<br/>";
//Calcule du consumerToken
$consumerToken=$consumerId.$consumerTimestamp.$consumerSecret;
$consumerToken=md5($consumerToken);
//echo $consumerToken.'<br/>';
//Configuration de l'entête
$header=array();
$header[]="Accept:application/json";
$header[]="Accept-Encoding:deflate";
$header[]="Content-Type:application/json";
$header[]="Authorization:AUTH consumerEmail=\"".$consumerEmail.
"\",consumerTimestamp=\"".$consumerTimestamp."\",consumerToken=\"".$consumerToken."\",consumerName=\"".$consumerName."\"";

$racine=array();
$order=array();
$amount=array();
$buyer=array();
$receiver=array();
$receiver1=array();
$receivers=array();


//information sur la commande
$order["reference"]="V0Y01";
$order["redirectUrl"]='http://localhost/demoshop.com/traitement.php';


$amount["amountTTC"]=$_POST["prix"];
$amount["currency"]="XAF";
$amount["paymentMethod"]="TRANSFERT_MOBILE_MONEY";

//information sur le client
$buyer["msisdn"]="00237".$_POST["phone_mobile"];
$buyer["email"]="tatampion@yahoo.fr";
$buyer["name"]=$firstname = $_POST["firstname"];
$buyer["operateur"]="OrangeMoney";

//debut information sur le destinataire du paiement
$buyer1["msisdn"]="00237666666666";
$buyer1["email"]="tatampion@yahoo.fr";

$amount1["amountTTC"]=$_POST["prix"];
$amount1["currency"]="XAF";
$amount1["paymentMethod"]="TRANSFERT_MOBILE_MONEY";

//cas 1 receiver
$receiver1["buyer"] = $buyer1;
$receiver1["amount"] = $amount1;
$receiver1["description"] = "paiement de la commande à un bénénéficiaire";

$receivers[] = $receiver1;

$racine["order"]=$order;
$racine["amount"]=$amount;
$racine["buyer"]=$buyer;
$racine["receivers"]=$receivers;
$data_string=json_encode($racine);
echo '</br>-------- MSG SEND --------</br>'.$data_string.'</br>';

$url=$ApiUrl."/transaction/bill";

$ch = curl_init();  
curl_setopt($ch, CURLOPT_URL , 'http://sandbox-abyster.appspot.com/rest/api/v2/transaction/bill');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data_string);                                                                 
curl_setopt($ch, CURLOPT_HEADER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, $header);
$result = curl_exec($ch);
echo '</br>'.'</br>-------- RESULT --------</br>'.$result.'</br>';

if (curl_errno($ch)> 0)die('There was a cURL error: ' . curl_error($ch));
    else{
        curl_close($ch);
        echo 'data= ';
        var_dump($result);
    }
$ch1 = curl_init();
curl_setopt($ch1, CURLOPT_URL , 'http://sandbox-abyster.appspot.com/rest/api/v2/transaction/3294/status');
curl_setopt($ch1, CURLOPT_RETURNTRANSFER, true);

curl_setopt($ch1, CURLOPT_SSL_VERIFYPEER, false);
                                                                
curl_setopt($ch1, CURLOPT_HEADER, true);
curl_setopt($ch1, CURLOPT_HTTPHEADER, $header);
$result = curl_exec($ch1);
echo "</br></br>---Statut vente --------</br>".$result;
?>

Le consumerToken est un token d'authentification à envoyer à chaque appel de service ; il est obtenu par application du MD5 à la chaine résultant de la concaténation des paramètres consumerId, ConsurmerTimestamp et consumerSecret,  consumerName ne peut être vide.

V-A. Service de paiement d'une commande▲

Appelez le web Service http://sandbox-abyster.appspot.com/rest/api/v2/transaction/bill avec l'entête défini plus haut et les paramètres suivants pour effectuer le paiement correspondant à la commande.

• Description des paramètres de la requête :

Renseigner les Informations sur la commande

Renseignez les informations sur la commande comme indiqué sur les lignes suivantes :

information sur la commande

Sélectionnez

1.
2.
3.

//information sur la commande
$order["reference"]="V0Y01";
$order["redirectUrl"]='http://localhost/demoshop.com/traitement.php';

Renseigner les informations sur le montant de la commande

voir ligne  :

montant de la commande

Sélectionnez

1.
2.
3.

$amount["amountTTC"]=$_POST["prix"];
$amount["currency"]="XAF";
$amount["paymentMethod"]="TRANSFERT_MOBILE_MONEY";

Renseigner les informations sur le montant du client

voir ligne :

information sur le client

Sélectionnez

1.
2.
3.
4.
5.

//information sur le client
$buyer["msisdn"]="00237".$_POST["phone_mobile"];
$buyer["email"]="tatampion@yahoo.fr";
$buyer["name"]=$firstname = $_POST["firstname"];
$buyer["operateur"]="OrangeMoney";

• Receivers : o   paramètre optionnel. C'est un tableau dont chaque élément contient les informations sur les éventuels destinataires du paiement qui sera reçu. Si le marchand désire que le montant qu'il va recevoir pour un achat soit directement envoyé vers un ou plusieurs bénéficiaires alors il spécifie tout simplement en fournissant les informations nécessaires et le traitement désiré sera effectué à la réception du paiement.
  Exemple :

"receivers": [{"buyer":{"msisdn":"002376666666","email":"tatampion@yahoo.fr"},"amount":{"amountTTC":100,"currency":"XAF","paymentMethod":"TRANSFERT_MOBILE_MONEY"},"description":"destinataire du paiement" 

}]

Description des champs :

Paramètres	Type	Requis	Description
amount	Json Object	oui	Objet json à la structure identique à celle présentée au §Amount,mais ici amountTTC est le montant à envoyer au destinataire
buyer	Json Object	Oui	Objet json à la structure identique à celle présentée au §Buyer,mais ici le msisdn et l'e-mail sont ceux du destinataire du paiement et non celui du client
Description	String	Nom	Description de la transaction à réaliser

• Exemple du contenu final avec tous les paramètres

contenu final avec un bénéficiaire.

Remarque : convertir toutes les informations au format json à l'aide de la fonction php json_encode()

• Instance d'une requête de paiement

Cette partie est la plus importante, elle nécessité votre attention. Le programme php ci-dessus se sert de la bibliothèque curldocumentation curl pour se connecter au serveur abysterurl en appelant le service web de paiement comme l'indique la ligne 60. si tout se passe bien, vous obtenez la réponse du serveur au format json.

• Instance de la réponse quand tout s'est bien passé et interprétation

Le marchand reçoit en retour l'objet JSON constitué du codeRetour de la requête qui vaut :

Le marchand reçoit en retour l'objet JSON constitué du codeRetour de la requête qui vaut :

• « OK » quand tout s'est bien passé et un SMS est envoyé au client ;
• « NOK » quand une erreur est survenue. Certainement l'entête a été mal défini.

La référence de la commande, le statut (« PENDING » signifie que la requête est en cours de traitement. Les autres valeurs possibles de ce statut sont « DONE » quand le client a effectivement réglé sa facture, « INCOMPLETED » quand la totalité de la somme due n'a pas été payée par le client et « FAIL » quand le paiement n'a pu être achevé) et l'URL via laquelle le marchand obtient le statut du paiement qu'il a initié.

• Instance d'une erreur pouvant survenir

• Erreurs potentielles pouvant apparaitre dans une réponse

Raison	Message de l'erreur	Description
DEF-1	Invalid or missing Json Parameters	Paramètre manquant ou mal défini
DEF-2	Merchant Account does not exist or Inactive	E-mail marchand défini dans l'entête Autorization incorrect ou compte marchand désactivé
DEF-3	Invalid or missing header Authorization	Entête Authorization mal défini
DEF-4	AUCUNE_PASSERELLE_TROUVE DE PAIEMENT	Aucun numéro de téléphone destinataire n'est compatible avec le numéro de téléphone utilisé par le client pour régler son achat par Mobile Money

V-B. Service de vérification du statut du paiement d'une commande▲

• Le Web Service à appeler ici est http://www.abyster.com/rest/api/v2/transaction/billAPI abyster au lieu de http://sandbox-abyster.appspot.com/rest/api/v2/transaction/bill.
• La configuration de l'entête, de la commande du client et l'appel du web service se font comme sur la démo.
• N.B.- Ne pas confondre la clé privée du compte démo avec celle du compte réel. Sinon l'API retourne la réponse NOK.
• Pour recevoir les transactions Mobile Money sur son site marchand, le client devra remplir le fichier d'abonnement B2B AByster ®. L'image suivante est une capture de la fiche d'abonnement.

Un marchand peut simuler le paiement d'une commande effectué en Sandbox, en utilisant le simulateur AByster. Pour simuler le paiement d'une commande, il faut se rendre à l'adresse :

http://sandbox-abyster.appspot.com/pages/utils/abysterTools.html

Description des champs du formulaire

• Pays : ce champ permet de sélectionner l'un des six pays à partir duquel la commande a été initiée.
• Émetteur : champ qui permet de saisir le numéro du client qui effectue le paiement. Il s'agit du client qui a passé la commande sur le site marchand.
• Destinateur : ce champ permet de sélectionner le destinataire du transfert. Sélectionner le numéro qui se trouve dans le SMS envoyé au client.
• Devise : ce champ contient une la valeur XAF qui est la monnaie de la zone CEMAC.
• Montant TTC : ce champ permet d'insérer le montant du paiement.
• Transaction Id : représente le numéro de la transaction.

Les champs obligatoires sont : Pays, Destinateur, Montant TTC.

Si le montant transféré est plus grand que le coût de la commande, le statut du paiement de la commande passe à DONE. Lorsque le paiement est effectué, un e-mail est envoyé au marchand pour le notifier du paiement.

Capture de l'e-mail

Lors que le paiement Mobile Money de la commande est effectué, le mail précédent est envoyé au client, en plus du statut qui change.

Contrainte  : la commande est annulée après 30 minutes si elle n'est pas payée par le client, par conséquent le statut passe à FAIL.

[1] Le site dédié à l'API AByster www.api.abyster.com

[2] Le lien de la documentation http://api.abyster.com/index.php/documentation/

[3] La communauté des développeurs AByster www.developpers.abyster.comcommunautés developer