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

Cas PHP

jm ntepp

Le but de ce tutoriel est de vous apprendre à intégrer l'API de paiement mobile Abyster sur un site web marchand, développé en PHP.

Commentez

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

- Auteur : jm ntepp

- Parution : 25 juin 2016

- Mise à jour : 25 juin 2016

- Public visé :

- Licence : Les sources présentées sur cette page sont libres de droits et vous pouvez les utiliser à votre convenance. Par contre, la page de présentation constitue une œuvre intellectuelle protégée par les droits d'auteur. Copyright ® 2016 ntepp_marcus. Aucune reproduction, même partielle, ne peut être faite de ce site et de l'ensemble de son contenu : textes, documents, images, etc. sans l'autorisation expresse de l'auteur. Sinon vous encourez selon la loi jusqu'à trois ans de prison et jusqu'à 300 000 € de dommages et intérêts.

Sommaire

- I. Introduction

- II. Définitions

- III. Prérequis

- IV. Cas d'étude

- V. Transactions en mode démo

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

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

- VI. Transaction en mode réel

- VII. Simulateur Mobile Money

- VIII. Utilisation d'un terminal mobile

- IX. Liens et ressources

I - Introduction

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-Pesa3 par exemple. La solution de paiement fonctionne actuellement au Cameroun et au Sénégal.

Figure 1 : Zone de chalandise de AByster

(cliquez ici pour aggrandir l'image)

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.

II - Définitions

Termes

Signification

AByster

désigne la société AByster

API

Application Programming Interface

CGU

Conditions Générales d'Utilisation du service AByster

MM

Compte Mobile Money

URI

Uniform Resource Identifier

URL

Uniform Resource Location

JSON

JavaScript Object Notation

${ABYSTERURL}

Fait référence à l'environnement AByster avec lequel le site marchand communique

III - Prérequis

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

IV - Cas d'étude

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.

Demoshop

(cliquez ici pour aggrandir l'image)

V - Transactions en mode démo

É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

(cliquez ici pour aggrandir l'image)

(cliquez ici pour aggrandir l'image)

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.

Création du compte

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

Paramètres d'authentification

(cliquez ici pour aggrandir l'image)

É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

1. <?php

4. $ApiUrl='http://sandbox-abyster.appspot.com/rest/api/v2';

5. $consumerId='5671831268753408';

6. $consumerName='employeur';

7. $consumerEmail='demoshop@demoshop.com';

8. $consumerSecret='CA1764U8MRL4E65H5EIA19K0FIAFL-e21a6b31-6f9e-4163-b6d6-41a230ceaac9';//'8EE5GRNUTM2CVVE8C7KRIUS4UEMVP-b0b3c3a7-7b62-4a2f-afd0-4ce3320226d4';

9. $consumerTimestamp=substr(date('Ymdhisu'),0,17);

10. //echo $consumerTimestamp."<br/>";

11. //Calcule du consumerToken

12. $consumerToken=$consumerId.$consumerTimestamp.$consumerSecret;

13. $consumerToken=md5($consumerToken);

14. //echo $consumerToken.'<br/>';

15. //Configuration de l'entête

16. $header=array();

17. $header[]="Accept:application/json";

18. $header[]="Accept-Encoding:deflate";

19. $header[]="Content-Type:application/json";

20. $header[]="Authorization:AUTH consumerEmail=\"".$consumerEmail.

21. "\",consumerTimestamp=\"".$consumerTimestamp."\",consumerToken=\"".$consumerToken."\",consumerName=\"".$consumerName."\"";

23. $racine=array();

24. $order=array();

25. $amount=array();

26. $buyer=array();

27. $receiver=array();

28. $receiver1=array();

29. $receivers=array();

32. //information sur la commande

33. $order["reference"]="V0Y01";

34. $order["redirectUrl"]='http://localhost/demoshop.com/traitement.php';

37. $amount["amountTTC"]=$_POST["prix"];

38. $amount["currency"]="XAF";

39. $amount["paymentMethod"]="TRANSFERT_MOBILE_MONEY";

41. //information sur le client

42. $buyer["msisdn"]="00237".$_POST["phone_mobile"];

43. $buyer["email"]="tatampion@yahoo.fr";

44. $buyer["name"]=$firstname = $_POST["firstname"];

45. $buyer["operateur"]="OrangeMoney";

47. //debut information sur le destinataire du paiement

48. $buyer1["msisdn"]="00237666666666";

49. $buyer1["email"]="tatampion@yahoo.fr";

51. $amount1["amountTTC"]=$_POST["prix"];

52. $amount1["currency"]="XAF";

53. $amount1["paymentMethod"]="TRANSFERT_MOBILE_MONEY";

55. //cas 1 receiver

56. $receiver1["buyer"] = $buyer1;

57. $receiver1["amount"] = $amount1;

58. $receiver1["description"] = "paiement de la commande à un bénénéficiaire";

60. $receivers[] = $receiver1;

62. $racine["order"]=$order;

63. $racine["amount"]=$amount;

64. $racine["buyer"]=$buyer;

65. $racine["receivers"]=$receivers;

66. $data_string=json_encode($racine);

67. echo '</br>-------- MSG SEND --------</br>'.$data_string.'</br>';

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

71. $ch = curl_init();

72. curl_setopt($ch, CURLOPT_URL , 'http://sandbox-abyster.appspot.com/rest/api/v2/transaction/bill');

73. curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

74. curl_setopt($ch, CURLOPT_POST, true);

75. curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);

76. curl_setopt($ch, CURLOPT_POSTFIELDS, $data_string);

77. curl_setopt($ch, CURLOPT_HEADER, true);

78. curl_setopt($ch, CURLOPT_HTTPHEADER, $header);

79. $result = curl_exec($ch);

80. echo '</br>'.'</br>-------- RESULT --------</br>'.$result.'</br>';

82. if (curl_errno($ch)> 0)die('There was a cURL error: ' . curl_error($ch));

83. else{

84. curl_close($ch);

85. echo 'data= ';

86. var_dump($result);

87. }

88. $ch1 = curl_init();

89. curl_setopt($ch1, CURLOPT_URL , 'http://sandbox-abyster.appspot.com/rest/api/v2/transaction/3294/status');

90. curl_setopt($ch1, CURLOPT_RETURNTRANSFER, true);

92. curl_setopt($ch1, CURLOPT_SSL_VERIFYPEER, false);

94. curl_setopt($ch1, CURLOPT_HEADER, true);

95. curl_setopt($ch1, CURLOPT_HTTPHEADER, $header);

96. $result = curl_exec($ch1);

97. echo "</br></br>---Statut vente --------</br>".$result;

98. ?>

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

1. //information sur la commande

2. $order["reference"]="V0Y01";

3. $order["redirectUrl"]='http://localhost/demoshop.com/traitement.php';

Renseigner les informations sur le montant de la commande

voir ligne  :

montant de la commande

1. $amount["amountTTC"]=$_POST["prix"];

2. $amount["currency"]="XAF";

3. $amount["paymentMethod"]="TRANSFERT_MOBILE_MONEY";

Renseigner les informations sur le montant du client

voir ligne :

information sur le client

1. //information sur le client

2. $buyer["msisdn"]="00237".$_POST["phone_mobile"];

3. $buyer["email"]="tatampion@yahoo.fr";

4. $buyer["name"]=$firstname = $_POST["firstname"];

5. $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

(cliquez ici pour aggrandir l'image)

contenu final avec un bénéficiaire.

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

(cliquez ici pour aggrandir l'image)

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

(cliquez ici pour aggrandir l'image)

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

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

Dès que le processus de paiement est initié, le marchand peut à tout moment consulter le statut de la transaction côté AByster. Ceci est possible via une requête GET sur l'URL : http://${ABYSTERURL}/rest/api/v2/transaction/{transactionReference}/status

Où transactionReference représente le numéro de la transaction côté AByster. Cette URL correspond à la valeur du paramètre « statusUrl » de la réponse reçue par le site marchand quand ce dernier a initié le processus de paiement.

- Instance d'une requête

Pour vérifier le statut de la transaction, il faut appeler le web service fourni dans la réponse:

http://sandbox-abyster.appspot.com/rest/api/v2/transaction/8781/status voir la ligne  :

instance d'une requête

1. curl_setopt($ch1, CURLOPT_URL , 'http://sandbox-abyster.appspot.com/rest/api/v2/transaction/3294/status');

(cliquez ici pour aggrandir l'image)

- Instance d'une réponse et interprétation

Quand le client a déjà réglé sa facture, la valeur de l'attribut « status » est à « DONE »

Quand le client n'a pas entièrement réglé sa facture le statut est à « INCOMPLETED »

N.B. Si le statut vaut « PENDING », alors la demande est toujours en cours de traitement.

- Erreur potentielle

Raison

Message de l'erreur

Description

DEF-5

TRANSACTION_INEXISTANTE

La transaction dont on recherche le statut n'existe pas ou n'a pas été sauvegardée

VI - Transaction en mode réel

- Le Web Service à appeler ici est http://www.abyster.com/rest/api/v2/transaction/bill 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.

VII - Simulateur Mobile Money

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

(cliquez ici pour aggrandir l'image)

VIII - Utilisation d'un terminal mobile

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.

IX - Liens et ressources

[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.com

Retour à l'article

Retour à l'article

Retour à l'article

Retour à l'article

Retour à l'article

Retour à l'article

Retour à l'article

Retour à l'article

Retour à l'article

Retour à l'article

Retour à l'article