AByster SDP : Manuel d’intégration de la solution de...

Copyrights: © 2015 AByster. All rights reserved www.abyster.com 1

AByster SDP : Manuel d’intégration de la solution de

compensation

API Version 2.0


Version

Date

Emetteur

Commentaires

2.0 16/03/2017 Chris KAMTA Documentation initiale

Refund

Vérification de statut


Table des matières

01. Objet ........................................................................................................................................... 4

02. Définitions ................................................................................................................................. 4

03. Introduction ............................................................................................................................... 4

04. Environnements ........................................................................................................................ 4

05. Services ...................................................................................................................................... 5

06. Restrictions ................................................................................................................................ 5

07. Prérequis à l’utilisation de l’API .............................................................................................. 5

07.1 Création d’un compte AByster Entreprise ........................................................................................ 5

07.2 Souscription à un forfait Infinity ........................................................................................................ 6

08. Intégration ................................................................................................................................. 6

08.1 Entêtes HTTP ....................................................................................................................................... 6 a. Paramètres de l’entête Authorization .................................................................................................. 6 b. Calcul du consummerToken : ............................................................................................................. 7

08.2 Intégration dans un site web ou une application web ....................................................................... 7 a. Service de compensation ..................................................................................................................... 7 b. Service de vérification du statut d’une compensation ....................................................................... 10 c. Notification du marchand sur l’url de redirection ............................................................................. 11

09. Architecture globale .............................................................................................................. 12

10. Liens et ressources .................................................................................................................. 13


01. Objet

Le présent document a pour objet de présenter l’API AByster destinée aux compensations. Il

donne aux web masters et développeurs des informations utiles pour une intégration aisée de

l’API de compensation Mobile Money AByster dans 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.

02. Définitions

Termes Signification

AByster

désigne la société AByster.

API Application Programming Interface

CGU Conditions Générales d’Utilisation

MoMo

Mobile Money

URI

Uniform Resource Identifier

URL Uniform Resource Location

JSON Javascript Object Notation

${ABYSTERURL} sandbox-abyster.appspot.com ou www.abyster.com

03. Introduction

Certains marchand font fassent à des problématiques de remboursement ou de versement de

fonds à des clients. Pour résoudre cette problématique, AByster fournit une API RestFull

semblable à l’API de payement permettant aux marchands de réaliser ce type d’opérations via des

transferts Mobile Money.

04. Environnements

AByster fourni 02 environnements pour l’utilisation de ces services :

L’environnement sandbox (https://sandbox-abyster.appspot.com) : environnement de test

où vous créez un compte AByster pour tester les différentes fonctionnalités de l’API depuis

http://sandbox-abyster.appspot.com/

http://www.abyster.com/

https://sandbox-abyster.appspot.com/


votre site web ou application. Aucun frais n’est facturé à l’intégrateur dans cet

environnement.

L’environnement de production (http://www.abyster.com) : quand vous êtes satisfait par

vos tests en sandbox vous passez en live, environnement effectif où vous réalisez de

véritables opérations avec vos clients, opérations sur lesquels vous êtes facturé suivant

votre forfait AByster.

05. Services

L’API met à disposition de l’intégrateur 02 services :

Service de compensation : http://${ABYSTERURL}/rest/api/v2/compensation/refund

Service de vérification de statut de la compensation: http://${ABYSTERURL}/rest/api/v2/compensation/{id}/status

06. Restrictions

La version actuelle de l’API ne supporte que les compensations pour l’opérateur Orange Money.

MTN Mobile Money est en cours de support

07. Prérequis à l’utilisation de l’API

07.1 Création d’un compte AByster Entreprise

Pour être autorisé à utiliser les APIs AByster, il faut posséder un compte AByster Entreprise (dit

compte Marchand). Pour ce faire, click sur le bouton « Ouvrir un compte » sur le site AByster et

suivez les étapes. A la fin de la création du compte, vous recevez par mail vos paramètres

d’authentification pour l’utilisation des APIs.

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

Identifiant (Identifiant du compte AByster du marchand : consummerId)

N.B : vous devez créer un compte sur chaque environnement (sandbox pour vos tests et

production avant le passage en live). Vous pouvez fournir les mêmes informations sur les 02

environnements lors de la création de ces comptes.

http://www.abyster.com/


07.2 Souscription à un forfait Infinity

La souscription au forfait Infinity est obligatoire pour l’utilisation de l’api de compensation.

08. Intégration

Une fois votre compte marchand AByster crée, vous pouvez utiliser l’API moyennant le respect des

structures des requêtes qui lui sont destinées. Le format d’échange des données est le JSON.

08.1 Entêtes HTTP

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 »

Authorization : cet entête est utilisé par AByster pour authentifier le marchand

a. Paramètres de l’entête Authorization

Paramètres

Description

consumerSecret Clé privée de votre compte AByster reçu par email à la création du compte

consumerId Identifiant de votre compte AByster reçu par email à la création du compte

consumerName Nom du site web marchand ou raison sociale.

consumerEmail Email avec lequel a été créé votre compte AByster.

consumerTimestamp Permet l’horodatage de chaque requête envoyée depuis le site marchand. Il doit obligatoirement tenir sur 17 digits. Ex : en PHP le format sera « Ymdhisu » et «yyyyMMddHHmmssSSS » en Java

consumerToken Code secret obtenu par génération via MD5 de la concaténation des valeurs des paramètres consumerId, consumerTimestamp et consumerSecret

Prenons l’exemple d’un compte marchand dont les paramètres ont pour valeur celles-ci-dessous:

consumerEmail= [email protected]

consumerName=Demo

mailto:[email protected]


consumerId= 6086896371367936

consumerSecret= MF3ES6A81RQ5MFATALCSDUF9NRNAJ-28ed4ef6-0e41-401f-bfa0

consumerTimestamp= 20150105023815000

b. Calcul du consummerToken :

consumerToken=MD5(consumerId+consumerTimestamp+consumerSecret)

consumerToken=MD5(608689637136793620150105023815000MF3ES6A81RQ5MFATALCSDUF9N

RNAJ-28ed4ef6-0e41-401f-bfa0)

consumerToken = 8e0f6287cf4ac76bf1f1e6735c1fc446

Vous pouvez vérifier que votre md5 est valide à l’adresse : http://www.md5.fr/

08.2 Intégration dans un site web ou une application web

a. Service de compensation

URL du service : http://${ABYSTERURL}/rest/api/v2/compensation/refund

Le site marchand fait appel à ce service pour initier la compensation.

Le temps moyen de réalisation d’une compensation demandée est de 04 minutes.

Header de la requête: voir §08.1

Description des paramètres de la requête: Le contenu de la requête est un objet JSON possédant un tableau de données JSON, ci-dessous sa

structure.

o receivers : paramètre obligatoire (tableau de données JSON) contenant les informations

sur la requête demandée. { "receivers":[ { "reference":"L11", "amount":500, "mode":"TRANSFERT_MOBILE_MONEY", "msisdn":"00237698029075", "callback":"http://monsite.com/callback", "operator":"OrangeMoney" },


http://www.md5.fr/


{ "reference":"L12", "amount":1000, "mode":"TRANSFERT_MOBILE_MONEY", "msisdn":"00237675330990", "callback":"http://monsite.com/callback", "operator":"MTNMMoney" } ] }

Paramètres Type Requis Description

reference

String Oui Représente l’identifiant de la compensation dans le système d’information du marchand. Exemple : L01

amount Float Oui Montant à transférer

mode String Oui Mode de transfert d’argent à utiliser. Valeurs possibles : TRANSFERT_MOBILE_MONEY VIREMENT_BANCAIRE

msisdn String Oui si mode vaut TRANSFERT_MOBILE_MONEY

Numéro de téléphone du client devant recevoir l’argent, utilisé le format international. Exemple : 00237xxxxxxxxx pour le Cameroun

iban String Oui si mode vaut VIREMENT_BANCAIRE

Numéro du compte bancaire de destination

callback String Oui url sur laquelle sera notifié le site marchand une fois la compensation réalisée.

operator String Oui Opérateur MoMo du destinataire. Valeurs possibles : MTNMMoney : MTN Mobile Money OrangeMoney : Orange Money

Instance d’une requête de compensation: POST http://${ABYSTERURL}/rest/api/v2/compensation/refund

//Http request header

Accept-Encoding: deflate

Accept: application/json

Content-Type: application/json

Authorization: AUTH


consumerEmail="[email protected]",consumerTimestamp="20150105023815000",consumerTok

en="8e0f6287cf4ac76bf1f1e6735c1fc446",consumerName=”Demo”

//Json body content

{ "receivers":[ { "reference":"L01", "amount":500, "mode":"TRANSFERT_MOBILE_MONEY", "msisdn":"00237698029075", "callback":"http://monsite.com/callback", "operator":"OrangeMoney" }, { "reference":"L02", "amount":1000, "mode":"TRANSFERT_MOBILE_MONEY", "msisdn":"00237675330990", "callback":"http://monsite.com/callback", "operator":"MTNMMoney" } ] }

Paramètres de la réponse

Paramètres Type Description

codeRetour String Code réponse de la requête Valeurs possibles : OK : tout s’est bien déroulé NOK : erreur survenue

content JSON Contient pour chaque compensation les informations de statut, url de suivi du statut, l’id de la compensation chez AByster et la référence de la requête chez le marchand

raison String Code de l’erreur. n’apparait que quand le codeRetour est NOK

description String Description de l’erreur. n’apparait que quand le codeRetour est NOK

Instance d’une réponse quand tout s’est bien passé {

"codeRetour": "OK",

"content": [ {

"id": "1WHBMTOBI5",

"referenceRequest": "L11",

"status": "PENDING",

"urlSuivi": "http://${ABYSTERURL}/rest/api/v2/compensation/1WHBMTOBI5/status"

},



{

"id": "KLJQB8KQVU",

"referenceRequest": "L12",

"status": "PENDING",

"urlSuivi": "http://${ABYSTERURL}/rest/api/v2/compensation/KLJQB8KQVU/status" }

] }

Instance d’une réponse quand une erreur est survenue

{

"codeRetour": "NOK",

"raison": "DEF-2",

"description": "mandatory parameters missing"

}

Erreurs Potentielles pouvant apparaitre dans une réponse Raison Message de l’erreur Description

DEF-1 Invalid Authentication or json poorly built

paramètre manquant ou espace potentiel dans le header Authorization

DEF-2 mandatory parameters missing l'objet receiver est vide ou les parametres obligatoire manquent dans le corps JSON de la requete

DEF-3 Merchant Account does not exist or Inactive

Compte marchand inexistant ou inactif

DEF-4 Inavlid Authorization Data Données du header Authorization non valide

b. Service de vérification du statut d’une compensation

Dès que le processus de compensation est initié, le marchand peut à tout moment consulter le

statut de la compensation coté AByster. Ceci est possible via une requête GET sur l’URL:

http://${ABYSTERURL}/rest/api/v2/compensation/{id}/status où id représente le numéro de la

compensation coté AByster.

Cette URL correspond à la valeur du paramètre « urlSuivi » de la réponse reçue par le site

marchand quand ce dernier a initié le processus.

Instance d’une requête

Pour vérifier le statut d’une des compensations de l’exemple du paragraphe précédent on va

utiliser la valeur de la variable de retour urlSuivi qui vaut :

GET http://${ABYSTERURL}/rest/api/v2/compensation/1WHBMTOBI5/status

http://localhost:8888/rest/api/v2/transaction/19/status





instance d’une réponse

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

{

"codeRetour": "OK",

"status": "PENDING"

}

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 COMPENSATION_INEXISTANTE La transaction dont on recherche le statut n’existe pas ou n’a pas été sauvegardée.

c. Notification du marchand sur l’url de redirection

Comme vu au §08.2.a, lors de l’appel de l’API, le marchand doit préciser l’URL (via le paramètre

callback) à laquelle il souhaite être notifier quand AByster aura réalisé la compensation. AByster

fait donc appel à cette URL via une requête http GET avec les paramètres suivants :

Reference : qui est la référence de la commande dont AByster a reçu le paiement ;

Statut : représente le statut de la commande chez AByster, les valeurs possibles sont celles

expliquées plus haut dans ce document (DONE, PENDING).

Avec l’exemple précédent, la notification sera de la forme :

http://monsite.com/callback?reference=”L11”&statut=”DONE”

http://monsite.com/callback?reference=


09. Architecture globale

Customer Merchant AByster AByster

Mobile Pro

Call Api http://${ABYSTERURL}/rest/api/v2/compensation/refund To initiate refund process

Perform a Mobile Money Payment action

Send notification when payment is done

Response of the refund Request

Notify when payment is done http://monsite.com/redirect?reference=”L11”&statut=”DONE”

Can check any time refund status via http://${ABYSTERURL}/rest/api/v2/compensation/{id}/status

Save request

Get refund request list

http://monsite.com/redirect?reference=

http://monsite.com/redirect?reference=


10. Liens et ressources

[1] Le site dédié à l’API AByster www.api.abyster.com [2] La communauté des développeurs AByster www.developpers.abyster.com

[3] Les réseaux sociaux

www.api.abyster.com

http://www.developpers.abyster.com/

https://www.facebook.com/pages/ABysterInc/461566270520677?fref=ts

http://www.youtube.com/user/ABysterInc

https://twitter.com/ABysterInc/

AByster SDP : Manuel d’intégration de la solution de...

Documents

Transcript of AByster SDP : Manuel d’intégration de la solution de...