Manuel d intégration du service AByster

Transcription

1 Manuel d intégration du service AByster PHP API Version février

2 Table des matières 01. Objet Définitions Introduction Le Core Organisation du dossier abyster Configuration de l API Marchande URL du service de paiement Clef de chiffrement Le Marchand Les infos de la commande Le client payeur L URL de retour Envoi d une demande de paiement Les paramètres d identification du client payeur Les paramètres liés à la commande client Récupération du Statut de la Commande Logs et Historisations Gestion des erreurs Les intégrateurs et partenaires certifiés Liens et resources

3 01. Objet Le présent document a pour objet de présenter l API AByster. Il donne aux web masters et développeurs des informations utiles leur permettant de d intégrer facilement l API AByster sur des sites web. Ce document présent la distribution PHP de l API AByster abyster-php-api-1.0 ; Le présent document fait partie intégrante des ressources soumises aux CGU (Conditions Générales d Utilisation) du service AByster. 02. Définitions AByster API CGU MM URI désigne la société AByster. Application Programming Interface Conditions Générales d Utilisation du service AByster Compte Mobile Money Uniform Resource Identifier 3

4 03. Introduction AByster fournit des composants prêts à l emploi permettant de gérer les appels depuis une application ou un site web vers la plateforme de paiement AByster. L API la mieux adaptée pour votre situation dépend de la nature de votre l applicatif marchand, AByster fournit deux types d API : API dites «riches» pour des applicatifs Riches : applications en Java SE et Microsoft principalement API Web pour l intégration sur des plateformes Web : (PHP, J2EE,.Net, Python) click bouton payer appel 2 appel N Site Marchan d API AByster Platform Figure 1 Positionnement de l'api L API est un composant intermédiaire entre le site marchand et la plateforme AByster Il reçoit les requêtes de paiement émis par les clients sur le site marchand, chiffre les requêtes puis les transmet à la plateforme serveur AByster pour traitement. Déployée dans le périmètre applicatif marchand, l API est la passerelle de communication entre le client (Site Marchand) et le serveur AByster. Ainsi, l API AByster est distribuée sous forme de librairies.jar,.dll dans les environnements riches et sous forme de dossier de scripts dans le cas du WEB. Bien que les fonctionnalités et l architecture générale de fonctionnement soit similaires sinon identiques, Nous vous conseillons de vous référer à la documentation spécialisée de chaque distribution ainsi qu à la section consacrée sur le site Le présent document présente la distribution PHP de l API AByster. 4

5 04. Le cœur de l API L API abyster-php-api-xxx est un sous dossier de script à placer à la racine du site marchand. Afin de réaliser un paiement direct via la plateforme AByster lorsque l utilisateur déclenche le processus de paiement, le site marchand appelle un script du sous dossier abyster. Toute modification de la position du dossier api abyster entraine donc une mise à jour des chemins d appels. Figure 2: Emplacement de la librairie abyster 04.1 Organisation du dossier abyster 5

6 04.2 Configuration de l API Marchande Le fichier principal de configuration est abyster_payment_handler.php <?php include("abyster_proxy_api.php"); /* Copyright (c) 2013 AByster Inc. All rigths reserved. Proxy API v1.0.1 Release Date:11/02/2013 PHP Client */ Il fait usage la librairie statique abyster_proxy_api.php Toutes vos modifications et configurations doivent se faire uniquement dans le fichier abyster_payment_handler.php URL du service de paiement //#1 AByster API URL configuration $abyster_api_host = " $abyster_api_uri = "/API/V1/Payment/action.do"; L URL du service de paiement AByster varie selon que vous travaillez sur des environnements sandbox, de recette ou en production. Ne changez ces configurations que si vous passez d un environnement à un autre. Les tests en environnement de recette se passent sur le protocole http ; par contre en production le HTTPS est requis Clef de chiffrement //#2 Consumer Secret Key provided by AByster $ab_consumer_id ="commmandes@monsite.com"; $ab_consumer_secret = "LHcjm3C2FKTCJK8RN4pI7NN2Pot43-e63ebeef-be78-47b8-a180-7a235feddaf1"; Lors de la création de votre compte marchand avec l adresse commmandes@monsite.com, un mail contenant votre clé sécrète vous a été envoyé à cette adresse. Renseignez votre dans la variable ab_consumer_id puis votre clef sécrète dans information confidentielle dans la variable ab_consumer_secret. Ces informations permettent de vous identifier et de signer vos communications avec la plateforme AByster 6

7 Le Marchand //#3 Merchant ab parameters $params['ab_consumer_ ']= $params['ab_consumer_name']= "Monsite SARL"; Renseignez également le paramètre d index 'ab_consumer_ ' par votre marchand et éventuellement votre nom de société. Ces informations sont également utilisées dans le processus de confirmation d identité des consommateurs de services de l API Les infos de la commande //#4 Commands Infos $params['ab_order_id']= if (isset($_request['ab_param_order_type'])){ $_REQUEST["ab_param_order_id"]; $params['ab_order_type']=$_request["ab_param_order_type"]; }else{ ablog('$_request[ab_order_type] not set','info'); $params['ab_order_type']=""; } if (isset($_request['ab_param_order_currency'])){ //Franc CFA - BEAC XAF (code Numerique 950) //Franc CFA - BCEAO XOF (code Numerique 952) $params['ab_order_currency']=$_request["ab_param_order_currency"]; }else{ ablog ('$_REQUEST[ab_param_order_currency] not set. default value XAF','INFO'); $params ['ab_order_currency']="xaf"; } $params['ab_order_description']= $params['ab_order_amount_ht']= $params['ab_order_amount_taxes']= $params['ab_order_amount_ttc']= $_REQUEST["ab_param_order_description"]; $_REQUEST["ab_param_order_amount_ht"]; $_REQUEST["ab_param_order_amount_taxes"]; $_REQUEST["ab_param_order_amount_ttc"]; C est à ce niveau que sont provisionnés les paramètres à envoyer à la plateforme de paiement, Si vous avez un script particulier pour générer les numéros de commandes, vous pourrez être tenter de l l invoquer à ce niveau afin de remplir la variable $params ['ab_order_id']. AByster recommande de ne pas modifier cette section et de fournir les paramètres attendus en entrée de la requête (POST/GET) invoquant le script abyster_payment_handler.php Le client payeur Ensuite sont remplis les données liées au payeur. //Buyer informations $params['ab_user_ ']= $params['ab_user_firstname']= $params['ab_user_lastname']= $_REQUEST["ab_param_client_ "]; $_REQUEST["ab_param_client_lastname"]; $_REQUEST["ab_param_client_firstname"]; L URL de retour La passation d une commande directe (Direct Payement) sur la plateforme AByster depuis un site marchand redirige temporairement l utilisateur sur abyster.com afin qu il puisse effectuer ledit paiement; par la suite, la plateforme AByster retourne le contrôle à l application appelante ; //#callbackurl Transaction Management parameters $params['ab_callback_url']=" 7

8 L url de callback est l url à laquelle le navigateur client sera redirigé à la fin du processus de paiement. Renseignez correctement l url à laquelle vous souhaiter récupérer les notifications à la fin du processus de paiement sur votre site web. AByster redirige le client vers cette URL via une requête POST portant les paramètres sur le statut de l opération. La section 04.4 parle en détails de la récupération et du traitement des statuts de commande Envoi d une demande de paiement L envoi d une demande de paiement se fait par une requête http(s) POST à l URI locale Abyster/abyster_payment_handler.php Cette requête est accompagnée des paramètres suivants : Les paramètres d identification du client payeur ab_param_client_ ab_param_client_firstname ab_param_client_lastname Paramètre Type Requis Description ab_param_client_ Oui Désigne l du client désirant acheter un produit ou service sur votre site web ab_param_client_firstname String Recommandé Prénom du client payeur ab_param_client_lastname String Recommandé Nom du client Payeur 8

9 Les paramètres liés à la commande client ab_param_order_id ab_param_order_amount_ht ab_param_order_amount_taxes ab_param_order_amount_ttc ab_param_order_currency ab_param_order_type ab_param_order_description Paramètre Type Requis Description Oui ab_param_order_id Libre (à la charge du marchand) Désigne la référence de l ordre, information capitale permettant au marchand d identifier de façon unique cette commande dans son système d information. Cette référence sera renvoyée au marchand à la fin de l opération avec le statut de l opération. Example : 1235, ORDER15, C0012 ab_param_order_amount_ht Float Recommandé Montant global hors taxe de la commande ; Ex ab_param_order_amount_taxes Float Recommandé Montant global des taxes imposées par le marchand. Ex ab_param_order_amount_ttc Float Oui Montant global Toutes Taxes Comprises de commande. Ex ab_param_order_currency String Oui Code alphabétique de la devise du paiement. Valeurs Actuellement supportées XAF : Franc CFA BEAC XOF : Franc CFA - BCEAO Par défaut le paiement sera traité en XAF. ab_param_order_type String Non Catégorie de la commande, permet au marchand de faire des tri/filtres dans son espace Marchand AByster ab_param_order_description String Non Description de la commande 9

10 <form id="paymentform" method="post" action="abyster/abyster_payment_handler.php"> <div> <label for="txtclient ">client </label> <input id="txtclient " name="ab_param_client_ " type="text"/> </div> <div> <label for="txtclientfname">client FirstName:</label> <input id="txtclientfname" name="ab_param_client_firstname" type="text"/> </div> <div> <label for="txtclientlname">client LastName:</label> <input id="txtclientlname" name="ab_param_client_lastname" type="text"/> </div> <div> <label for="txtamountht">montant HT:</label> <input id="txtamountht" name="ab_param_order_amount_ht" type="text" value="975.00"/> </div> <div> <label for="txttaxes">taxes:</label> <input id="txttaxes" name="ab_param_order_amount_taxes" type="text" value="25.00"/> </div> <div> <label for="txtamountttc">montant TTC:</label> <input id="txtamountttc" name="ab_param_order_amount_ttc" type="text" value=" "/> </div> <div> <label for="txtorderid">order ID:</label> <input id="txtorderid" name="ab_param_order_id" type="text" value=" "/> </div> Ce formulaire est un cas typique permettant à un Web master de recevoir des dons sur son site web. 10

11 04.4 Récupération du Statut de la Commande Comme vu à la section ci-dessus, le service AByster rend la main au site marchand par une requête http POST à l url de callback avec en retour les paramètres suivants //#callbackurl Transaction Management parameters $params['ab_callback_url']=" Paramètre ab_order_id ab_transaction_id ab_transaction_status Description Numéros de la commande envoyée par le marchand lors de l appel initial Numéros de transaction dans le système AByster associé à cette commande. Statut de la transaction Valeurs possibles o SUCCESS o CANCELED o FAILED o WAITING ab_transaction_amount ab_transaction_currency Montant reçu par le marchand Devise de la transaction ab_transaction_description Description : Champ ouvert et permettant à AByster de communiquer d éventuelles autres informations aux marchands. 11

12 04.5 Logs et Historisations AByster journalise les appels à l API pour vous permettre de diagnostiquer des troubles de fonctionnement. Un log est produit par jour avec la trace de tous les appels effectués. L instruction de log est le script ablog <?php /* Copyright (c) 2013 AByster Inc. All rigths reserved. contact@abyster.com ww.abyster.com Proxy API v1.0.1 PHP Client log function */ function ablog($data,$level) { //init logs $day = gmdate("y-m-d"); $logfile='./logs/abyster_'.$day.'.log'; error_log("\r\n".'['.gmdate("y-m-d H:i:s").'] '.$level.' '.$data, 3, $logfile); }?> Selon vos besoins vous pouvez modifier le cycle de rotation des fichiers logs qui est fixé à un jour. 05. Gestion des erreurs Au cours de votre expérience utilisateur (client payeur ou marchand) vous pourrez rencontrer l une des erreurs suivantes Code Diagnostic Raison Description 12

13 06. Les intégrateurs et partenaires certifiés. AByster accompagne les PME, PMI et grands compte à travers le monde entier dans la mise en œuvre des moyens de paiements. Direct Voyage permet à ses clients de payer des tickets d autobus sur son site web graçe à la plateforme AByster

14 07. Liens et ressources [1] Le site dédié à l API AByster [2] La communauté des développeurs AByster [3] Les réseaux sociaux 14