Télécharger en format PDF

Transcription

Guide technique d’intégration
mPOS SDK ANDROID
PayZen mPOS
Version du document 0.9
Sommaire
1. HISTORIQUE DU DOCUMENT........................................................................................................ 3
2. PRÉSENTATION DE LA SOLUTION MPOS.................................................................................. 4
3. PRÉSENTATION DU SDK PAYZEN MPOS................................................................................... 5
3.1. Descriptif des fonctionnalités......................................................................................................................5
3.2. Étapes de l'intégration................................................................................................................................. 5
4. PRÉREQUIS.......................................................................................................................................... 6
5. S'AUTHENTIFIER SUR LE SERVEUR PAYZEN........................................................................... 7
5.1. Créer un jeton..............................................................................................................................................7
Créer un jeton d’authentification............................................................................................................7
Créer un jeton d’identification............................................................................................................. 10
Préconisations d'implémentation...........................................................................................................11
5.2. Récupérer l'identifiant de la boutique....................................................................................................... 12
5.3. Consulter un jeton d'authentification........................................................................................................ 13
6. INTÉGRER SDK PAYZEN MPOS SOUS ANDROID................................................................... 14
6.1. Vérifier l'authenticité du SDK.................................................................................................................. 14
6.2. Importer la librairie MPosSDK.................................................................................................................15
6.3. Identifier les opérations disponibles..........................................................................................................16
Gérer les permissions............................................................................................................................16
Initialiser le SDK.................................................................................................................................. 16
Configurer un thème.............................................................................................................................17
S’enregistrer.......................................................................................................................................... 17
Connaître l'état du lecteur de carte.......................................................................................................17
Initialiser le lecteur de carte.................................................................................................................18
Connaitre l'état du SDK....................................................................................................................... 18
Enregistrer des informations clients..................................................................................................... 19
Créer une transaction de Paiement/Annulation/Remboursement......................................................... 19
Récupérer l’historique des transactions du lecteur de carte.................................................................20
Réafficher un reçu................................................................................................................................ 20
Envoyer un reçu....................................................................................................................................20
Accéder aux informations sur le lecteur mPOS...................................................................................21
Mettre à jour le Numéro Logique du Point d’Acceptation (NLPA).................................................... 21
Configurer l'orientation du device........................................................................................................21
Arrêter le SDK......................................................................................................................................22
Gérer les erreurs du SDK.....................................................................................................................22
1. HISTORIQUE DU DOCUMENT
Version
Auteur
Date
Commentaire
0.9
Lyra Network
16/01/2017
Mise à jour des chapitres :
•
Prérequis
•
Créer un jeton
•
Créer un jeton d'identification
Ajout du chapitre Préconisations d'implémentation
0.8
Lyra Network
25/11/2016
Ajout chapitre Vérifier l'authenticité du SDK.
Ajout d'informations dans les Prérequis
0.7
Lyra Network
21/11/2016
Informations à propos de l'URL de démonstration et l'URL de
production
0.6
Lyra Network
15/11/2016
Mise à jour version du SDK
0.5
Lyra Network
26/07/2016
Création de deux guides distincts :
1. Android
2. iOS
0.4
Lyra Network
31/05/22016
Modification intégration du SDK Android V2
0.3
Lyra Network
14/03/2016
Mise à jour des noms de champs (références domaine
supprimées)
0.2
Lyra Network
29/01/2016
SDK iOS, MAJ Android
0.1
Lyra Network
12/12/2015
Version initiale du document
Ce document et son contenu sont strictement confidentiels. Il n’est pas contractuel. Toute reproduction
et/ou distribution de ce document ou de toute ou partie de son contenu à une entité tierce sont
strictement interdites ou sujettes à une autorisation écrite préalable de Lyra Network. Tous droits réservés.
Guide technique d’intégration mPOS SDK ANDROID - Version du document 0.9
Droit de propriété intellectuelle - 3 / 22
2. PRÉSENTATION DE LA SOLUTION MPOS
La solution mPOS désigne une solution d’acceptation de paiement en mobilité.
Elle repose sur les 3 éléments suivants :
• Un lecteur de carte à puce ou carte à piste magnétique, aussi appelé terminal mobile
• Un équipement mobile de type tablette ou smartphone
Permet d'héberger l’application de paiement.
• Un serveur d’acceptation
Prend en charge l’applicatif bancaire permettant de réaliser des transactions avec les systèmes
d’acquisition (bancaires).
3. PRÉSENTATION DU SDK PAYZEN MPOS
Le SDK PayZen mPOS permet d’intégrer le paiement de proximité simplement dans votre application
métier.
3.1. Descriptif des fonctionnalités
Après une étape d’authentification auprès de notre serveur d’acceptation, les fonctionnalités disponibles
via notre SDK sont les suivantes :
• Paiement
• Annulation
• Remboursement (crédit)
• Visualisation du ticket de transaction (paiement, annulation ou remboursement)
• Envoi du ticket au porteur (acheteur)
• Récupération de l’historique des transactions
Le SDK PayZen mPOS prend en charge l'ensemble des affichages règlementaires tels que :
• Messages sur l’état d’avancement d'un paiement
• Messages sur l’état d’avancement d'une annulation
• Messages sur l’état d’avancement d'un remboursement
• Messages lors de l'affichage du ticket CB
3.2. Étapes de l'intégration
L’intégration de la solution PayZen se réalise en 2 étapes :
• La récupération d'un jeton d'identification ou d'authentification via un appel web service à la
plateforme PayZen.
• L'intégration des fonctionnalités du SDK PayZen mPOS
Le jeton d'accès sera envoyé à l’API.
4. PRÉREQUIS
Plusieurs conditions sont requises pour intégrer le SDK PayZen mPOS :
• Souscrire à une offre contenant la fonctionnalité mPOS
• Posséder un login et un mot de passe PayZen.
Le login et le mot de passe sont envoyés par la plateforme de paiement par e-mail.
• Connaître son identifiant de boutique PayZen.
L'identifiant de la boutique est visible depuis le Back Office via le menu Paramétrage > Boutique >
onglet Configuration.
Remarque
Il est fortement conseillé d’obtenir un lecteur auprès de votre revendeur pour pouvoir vérifier la bonne
intégration.
En cas d'utilisation d'un réseau wifi protégé
Il est nécesaire d'autoriser les URLs suivants pour rendre la solution opérationnelle :
• https://mpos.payzen.eu/mpos-server/
• https://sentry.lyra-network.com/
• https://secure.payzen.eu/
5. S'AUTHENTIFIER SUR LE SERVEUR PAYZEN
L’authentification ou l'identification se fait par appel d’un service REST sur notre serveur PayZen.
Pour ce faire, le marchand doit :
• Créer un jeton
• Récupérer l'identifiant de sa boutique
Remarque :
2 URL sont renseignées pour générer le jeton, récupérer l'identifiant de la boutique et consulter le jeton
d'authentification :
• 1 URL de démonstration
• 1 URL de production
Pour de la production, l'URL de production est obligatoire. Dans d'autres cas, veuillez-vous rapprocher de
votre interlocuteur PayZen.
5.1. Créer un jeton
Il y a 2 possibilités:
• Le mode authentification :
Ce jeton donne un accès complet au fonctionnalités du SDK. Le login et le mot de passe de l'utilisateur
sont requis.
• Le mode identification:
Ce mode permet à l'utilisateur de ne pas avoir à se connecter toutes les 16 heures. Le jeton
d'identification n'a pas de délai d'expiration.
Cependant, il n'est pas possible d'effectuer les opérations sensibles telles que :
• l'annulation
• le remboursement
• la première association d'un terminal avec un contrat
Pour accéder à ces opérations, il sera nécessaire d'être authentifié.
Remarque
Il est important de rappeler qu'il est formellement interdit de stocker un mot de passe en dur dans
le code. Toute saisie du mot de passe doit se faire de façon manuelle par l'utilisateur via une fenêtre
modale.
Créer un jeton d’authentification
Pour créer un jeton d'authentification :
• Sur le domaine de production
Méthode
URL
POST
https://secure.payzen.eu/mpos-ws/tokens
• Sur le domaine de démonstration
Méthode
URL
POST
https://demo.payzen.eu/mpos-ws/tokens
Exemple de requête :
Header : Content-Type:application/json
Body : {"login" : "$login", "pwd" : "$pwd", "language" : "$language" }
Dans laquelle :
Champ
Format
login
an..30
Requis
Description
Le login a été envoyé par e-mail par la plateforme de paiement.
pwd
ans8..32
Le mot de passe a été envoyé par e-mail par la plateforme de paiement.
language
Code ISO
639 alpha 2
Langue utilisée.
Exemples :
•
fr
•
de
•
en
Types de réponses possibles :
Code
http
Message
200
401
401
401
401
401
Descriptif
Body :
{"id":"MyToken",
"href":"https://secure.payzen.eu/mpos-ws/tokens/MyToken",
"created_at":"2015-11-03T10:34:44.865+0000",
"expiry_date":"2015-11-04T10:34:44.870+0000",
"language":"fr",
"issuer":"PayZenMobile",
"firstname":"Prenom",
"lastname":"Nom",
"title":"Mr"}
Body : {"type":"LOGIN_FAILED"}
Body : {"type":"FIRST_LOGIN"}
Body : {"type":" LOCKED_ACCOUNT"}
Body : {"type":" DISABLED_ACCOUNT"}
Body : {"type":" EXPIRED_PASSWORD"}
Succès
Login et /ou mot de passe
incorrect(s).
Mot de passe temporaire utilisé.
Ce message nécessite une action
pour changer le mot de passe.
Compte bloqué suite à 3 échecs
successifs.
Cliquez sur le lien Mot de passe
oublié ou compte bloqué et suivez
la procédure indiquée.
Compte désactivé (cas rare).
Mot de passe expiré.
Dans lesquelles :
Champ
Format
Description
id
string
Valeur du jeton.
href
string
URL d'accès au jeton.
created_at
dateTime ISO Date et heure de création du jeton.
8601
Format attendu : YYYY-MM-ddThh:mm:ss.nnnzzzzz
expiry_date
dateTime ISO Date et heure d'expiration du jeton.
8601
language
Code ISO 639 Langue utilisée.
alpha2
issuer
string
Entité à l'origine de la création du jeton.
firstname
ans..60
Prénom de l'utilisateur.
lastname
ans..60
Nom de l'utilsateur.
title
an..63
Civilité de l’acheteur (Exemple Mr, Mme, Melle).
authenticated boolean
En mode création d'un jeton d'authentification, ce champ est valorisé à true.
Créer un jeton d’identification
Un jeton d'identification a l'avantage de ne pouvoir expirer. Pour plus d'informations voir le chapitre
Préconisations d'implémentation.
Attention
Le jeton d’identification ne permet d’utiliser qu’une partie des fonctionnalités du SDK.
Les opérations les plus sensibles nécessitent un jeton d’authentification :
• Première association d’un lecteur avec un contrat
• Remboursement
• Annulation
Il est donc important de pouvoir gérer le comportement du SDK dans le cas d’une action non autorisée.
Méthode
URL
POST
https://secure.payzen.eu/mpos-ws/identificationTokens
Méthode
URL
POST
https://demo.payzen.eu/mpos-ws/identificationTokens
Body : {"login" : "$login", "pwd" : "$pwd", "language" : "$language" }
Dans laquelle :
Champ
Format
Requis
Description
login
an..30
Le login a été envoyé par e-mail par la plateforme de paiement.
pwd
ans8..32
Le mot de passe a été envoyé par e-mail par la plateforme de paiement.
language
Code ISO
639 alpha2
Langue utilisée.
Exemples :
•
fr
•
de
•
en
Exemple de réponse :
Body :
{
"id":"MyToken",
"href":"https://secure.payzen.eu/mpos-ws/IdentificationTokens/MyToken",
"created_at":"2015-11-03T10:34:44.865+0000",
"expiry_date":"2015-11-04T10:34:44.870+0000",
"language":"fr",
"lastname":"Nom",
"title":"Mr",
"authenticated":false
}
Les paramètres de réponse sont les mêmes que ceux présents dans l'exemple de réponse Créer un jeton
d'authentification. Seul le champ authenticated le différencie.
Sa valeur est false si le jeton est un jeton d'identification.
Champ
Format
Description
id
string
Valeur du jeton.
Champ
Format
Description
href
string
URL d'accès au jeton.
created_at
dateTime ISO Date et heure de création du jeton.
8601
expiry_date
dateTime ISO Date et heure d'expiration du jeton.
8601
language
Code ISO 639 Langue utilisée.
alpha2
issuer
string
Entité à l'origine de la création du jeton.
firstname
ans..60
Prénom de l'utilisateur.
lastname
ans..60
Nom de l'utilsateur.
title
an..63
Civilité de l’acheteur (Exemple Mr, Mme, Melle).
authenticated boolean
En mode création d'un jeton d'identification, ce champ est valorisé à false.
Préconisations d'implémentation
Il est conseillé de procéder comme suit :
1. Lors du premier lancement de votre application, forcez l'entrée du login et mot de passe de
l'utilisateur afin de générer les 2 jetons :
• le jeton d'authentification qui permet d'effectuer la première association du lecteur avec le
contrat,
• le jeton d'identification pour éviter à l'utilisateur de saisir à nouveau ses identifiants.
Le message d'erreur MPOS_INVALID_TOKEN indique que la session d'authentification est expirée.
2. Basculez sur une session d'identification avec le jeton précédemment généré.
Une fois la session d'identification en cours d'usage, le message MPOS_AUTHENTICATION_ERROR
indique que l'opération demandée nécessite un jeton d'authentification.
3. Demandez à l'utilisateur de s'authentifier à nouveau avec ses identifants.
Il est conseillé de laisser la possibilité à l'utilisateur de se déconnecter afin de générer de nouveaux jetons.
5.2. Récupérer l'identifiant de la boutique
Pour récupérer l'identifiant de la boutique :
Méthode
URL
GET
https://secure.payzen.eu/mpos-ws/shops/
Méthode
URL
GET
https://demo.payzen.eu/mpos-ws/shops/
token: MyToken
Dans laquelle :
Champ
Format
token
string
Requis
Description
Jeton d'authentification créé dans la requête précédente.
Doit être envoyé dans le header de la requête.
Exemple de réponses en cas de succès:
[
{
"id":"12345678",
"created_at":"2014-09-22T12:46:57.000+0000",
"updated_at":"2014-09-22T12:46:57.000+0000",
"label":"Mpos shop"
},
{
"id":"11223344",
"created_at":"2016-02-11T10:08:35.000+0000",
"updated_at":"2016-02-11T10:09:51.000+0000",
"label":"Mpos Shop 2"
}
]
Où :
Champ
Format
Description
id
n8
Identifiant de la boutique
created_at
dateTime ISO Date de création de la boutique.
8601
updated_at
dateTime ISO Date de mise à jour de la boutique.
8601
label
ans..127
Nom de la boutique
Remarque :
En cas d'échec, un message d'erreur générique est retourné.
5.3. Consulter un jeton d'authentification
Pour consulter un jeton d'authentification :
Méthode
URL
GET
https://secure.payzen.eu/mpos-ws/tokens/MyToken
Méthode
URL
GET
https://demo.payzen.eu/mpos-ws/tokens/MyToken
Remarque :
MyToken
est la valeur du jeton d'authentification précédemment créé.
Codes retour pouvant être retournés dans la réponse :
Code
http
200
401
401
401
Exemples de messages
Descriptif
Body :
{"id":"MyToken",
"href":"https://secure.payzen.eu/mpos-ws/tokens/MyToken",
"created_at":"2015-11-03T10:34:44.865+0000",
"expiry_date":"2015-11-04T10:34:44.870+0000",
"language":"fr",
"lastname":"Nom",
"title":"Mr"}
Body : {"type":"NOT_LOGGED_IN","details":"INVALID_TOKEN"}
Body : {"type":"NOT_LOGGED_IN","details":"MISSING_TOKEN"}
Body : {"type":"NOT_LOGGED_IN","details":"TOKEN_BANNED"}
Succès
Jeton invalide
Jeton absent
Jeton expiré
Remarque :
Les champs présents dans la réponse sont identiques à ceux retournés pour la création d'un jeton
d'authentification.
6. INTÉGRER SDK PAYZEN MPOS SOUS ANDROID
La version Android minimale supportée est 4.2
Tous les paramètres renseignés dans les classes du SDK sont privés et sont accessibles via des méthodes
getters/setters.
6.1. Vérifier l'authenticité du SDK
Cette opération est facultative mais recommandée.
Elle permet de s’assurer que le SDK utilisé est authentique et non modifié par un tiers.
Pré-requis :
• Avoir installé GPG (https://www.gnupg.org/)
• Disposer du SDK (nommé ci-après mpos-sdk-x.y.z.aar)
• Disposer du fichier signature associé au SDK (nommé ci-après mpos-sdk-x.y.z.aar.asc)
Remarque :
Le fichier signature se trouve dans le même répertoire que le SDK (https://media.lyra-network.com/
mpos/android/sdk/maven-repo/).
Le numéro x.y.z est à remplacer par la dernière version disponible du SDK.
• Disposer de la clé publique de Lyra Network et l'insérer dans le fichier
mpos_android_sdk_signature.gpg tel que :
-----BEGIN PGP PUBLIC KEY BLOCK----Version: GnuPG v2.0.14 (GNU/Linux)
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
YBXb9nvC04kwUZQ=
=pfAd
-----END PGP PUBLIC KEY BLOCK-----
Tapez les commandes suivantes :
• Import et configuration (à faire une seule fois)
gpg2 --import mpos_android_sdk_signature.gpg
Remarque :
La commande ci-dessus permet d'importer la clé publique dans le trousseau.
gpg2 --edit-key [email protected] trust quit
Remarque :
Placez la confiance à 5.
• Vérification de la signature (à faire pour chaque version du SDK)
gpg2 --verify mpos-sdk-X.Y.Z.aar.asc mpos-sdk-X.Y.Z.aar
Important : doit afficher que la signature est OK.
6.2. Importer la librairie MPosSDK
Pour importer la librairie MPosSDK :
Ajoutez la dépendance dans le build.gradle du module qui utilisera la librairie MPosSDK :
repositories {
maven {
url 'https://media.lyra-network.com/mpos/android/sdk/maven-repo/'
}
maven {
url 'https://bright.github.io/maven-repo/'
}
}
android {
}dependencies {
compile 'com.lyranetwork:mpos-sdk:x.y.z'
}
Remarques :
• Le numéro de version est amené à évoluer au fur et à mesure des développements.
• Dans l'exemple de code proposé au dessus, le numéro x.y.z est à remplacer par la dernière version
disponible du SDK, les versions sont visibles via l’adresse :
http://media.lyra-network.com/mpos/android/sdk/maven-repo/com/lyranetwork/mpos-sdk/
• La licence du SDK est consultable à l'adresse suivante :
http://media.lyra-network.com/mpos/android/sdk/LICENSE
Il est fortement conseillé d'utiliser les versions de compilations suivantes :
compileSdkVersion 24
buildToolVersion "24"
Cela n'empêche en rien l'exécution de l'application sur des versions antérieures.
6.3. Identifier les opérations disponibles
Plusieurs opérations sont mises à disposition :
Gérer les permissions
En intégrant le SDK les deux permissions suivantes seront automatiquement importées à votre projet :
<uses-permission android:name="android.permission.BLUETOOTH"/>
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN"/>
Initialiser le SDK
L'initialisation complète du SDK se fait en deux temps :
• l’initialisation du SDK
• la transmission du contexte.
Cette opération peut être appelée :
• soit dans l’objet hérité de la classe Application
• soit dans une Activity.
Cependant, nous conseillons de la mettre dans la méthode onCreate de la classe qui hérite de Application.
public class MyApplication extends Application
{
@Override
public void onCreate()
{
super.onCreate();
try
{
MposSDK.init(this); // this -> MyApplication -> Context
}
catch (MposException e)
{
// Traiter l’exception
}
}
}
Champ
Valeur
Description
Context
this
Contexte de l’application
Requis
Remarque
Cette fonction peut retourner une MposException. La gestion d’erreur est traitée dans le chapitre Gérer
les erreurs du SDK.
Configurer un thème
Il est possible de configurer un thème de couleur pour les fenêtres affichées par le SDK (par défaut noir).
Pour cela ajoutez la ligne de code suivante :
MPosSDK.SetThemeColor(Color.RED);
Dans laquelle :
Champ
Format
Valeur
Color
int
En hexadécimal, exemple :
Color.RED (0xFFFF0000)
Requis
S’enregistrer
Afin que la librairie puisse communiquer avec le serveur, il faut transmettre le jeton de connexion.
Pour cela ajoutez la ligne de code suivante :
MPosSDK.registerToken("myToken");
Dans laquelle :
Champ
Format
Valeur
token
String
myToken
Requis
Le jeton est initialisé à l’aide de l’API présentée dans le chapitre S'authentifier sur le serveur .
Connaître l'état du lecteur de carte
Avant de lancer l’initialisation du lecteur de carte, il est conseillé de vérifier son état.
Pour cela le SDK met à disposition la fonction suivante :
MPosSDK.isCardReaderAvailable();
Cette fonction permet de savoir si le lecteur de carte est prêt à être utilisé.
Initialiser le lecteur de carte
Afin de pouvoir réaliser une transaction, il faut que le lecteur de carte soit initialisé.
Il faut passer au SDK l’acceptorId qui correspond à l’identifiant de la boutique, ex : 12345678
Remarque :
Cette action peut être longue la première fois.
Une fenêtre s’affichera et expliquera toutes les actions en cours.
MposResult result = MposSDK.start(activity, "acceptorId");
Champ
Format
Valeur
activity
Activity
myActivity
acceptorId
String
myAcceptorId
Requis
Pour être informé du résultat, il est nécessaire de s’abonner à un ResultCallback. La méthode pour cela
est la suivante :
MposResult mposResult = MposSDK.start(activity, “acceptorId”);
mposResult.setCallback(new MposResult.ResultCallback()
{
@Override public void onSuccess(Result result)
{ }
@Override public void onError(Result error)
{ }
@Override public void onError(Throwable e)
{ }
}
);
Une fois que vous êtes notifié sur la fonction onSuccess, le lecteur de carte est initialisé.
La liste des devises autorisées par votre contrat est disponible avec la méthode :
List<MCurrency> currencies = MposSDK.getCurrencies();
La classe MCurrency contient les attributs suivants :
Classe MCurrency
int code;
String alphaCode;
String label;
int exponent;
String symbol;
Remarque
les erreurs du SDK.
Connaitre l'état du SDK
Pour connaître l’état du SDK, vous pouvez utiliser la fonction suivante :
boolean isReady = MposSDK.isReady();
Enregistrer des informations clients
Il est possible d’associer un certain nombre d’informations client à la transaction.
Ces informations seront visibles sur le Back Office Marchand PayZen.
Pour cela :
//Client information, classe MosCustomer
MposCustomer mposCustomer = new MposCustomer();
//Available fields
String firstName;
String lastName;
String phone;
String email;
String address;
String country;
String reference;
String title;
MposCustomerType type;
//MposCustomerType.PRIVATE ou MposCustomerType.COMPANY
L’ensemble des éléments d’une transaction sont dans l’objet MTransaction.
Créer une transaction de Paiement/Annulation/Remboursement
Pour créer une transaction :
MTransaction mTransaction = new MTransaction();
mTransaction.setAmount(1000);
mTransaction.setCurrency(MPosSDK.getCurrencies().get(0));
mTransaction.setOperationType(MposTransactionType.<type>); //DEBIT,CREDIT,CANCEL
mTransaction.setCustomer(mCustomer);
MposResult result = MPosSDK.executeTransaction(activity, mTransaction, authorisationRequested,
myMode);
Voici les paramètres de la fonction executeTransaction.
Champ
Format
Valeur
activity
Activity
myActivity
mTransaction
MTransaction
myMTransaction
authorisationRequested
boolean
myAuthorisationRequested
mode
String
myMode
Valeurs possibles : TEST ou
PRODUCTION
Par défaut, la valeur
PRODUCTION est prise en
compte.
Requis
Remarque :
Le passage d'une transaction en mode PRODUCTION sur une boutique de test n'est pas possible.
L’ensemble des éléments d’une transaction sont dans l’objet MTransaction.
Certains attributs de l’objet transaction seront renseignés par le serveur et accessibles dans le callback.
Classe MTransaction
//To be entered by the developer
long amount; //Amount
MCurrency currency; //Currency
String orderId; //Payment reference
String orderInfo; //text
MTransactionType operationType; //Transaction type: Payment, refund, cancelation
MCustomer customer; //Customer informations
String captureDate;
// yyyy-MM-dd'T'HH:mm:ss
//Entered by the server
String transactionUiid; //The unique transaction reference generated by the payment gateway
byte[] signature; //The hand written customer signature
MposTransactionStatus transactionStatusLabel; //The transaction status label signature
(APPROVED,ABORTED,DECLINED)
String receipt; //The transaction receipt generated by the payment gateway
Date submissionDate; //The transaction date
String transactionId; //The transaction identifier, unique per day
Pour être informé du résultat, ResultCallback doit être utilisé :
MposResult mposResult = MposSDK.executeTransaction(getActivity(), mTransaction, false);
mposResult.setCallback(new MposResult.ResultCallback() {
@Override
public void onSuccess(Result result) { }
@Override
public void onError(Result error) { }
@Override
public void onError(Throwable e) { }
});
Remarque
les erreurs du SDK.
Récupérer l’historique des transactions du lecteur de carte
Le SDK permet de visualiser les transactions qui ne sont pas encore remisées en banque.
Pour récupérer la liste des transactions non remisées effectuées sur le lecteur de carte :
List<MTransaction> transactionList = MposSDK.getListPendingTransaction();
Cette méthode retourne la liste des transactions triées par date, les plus récentes en premières positions.
Attention : cette méthode est synchrone. Elle ne peut pas être appelée depuis l’UIThread.
Remarque
les erreurs du SDK.
Réafficher un reçu
Pour réafficher la fenêtre du reçu et ainsi le renvoyer par e-mail :
MposSDK.showReceipt(activity, mTransaction);
Champ
Format
Valeur
activity
Activity
myActivity
mTransaction
MTransaction
myMTransaction
Requis
Envoyer un reçu
Le reçu peut être envoyé manuellement.
Pour cela :
MposSDK.sendReceipt(activity, mTransaction.getTransactionUiid(), "0606060606",
"[email protected]");
Champ
Format
Valeur
Requis
activity
Activity
myActivity
transactionUiid
String
mTransaction.getTransactionUiid()
phone
String
0606060606
email
String
[email protected]
Remarque :
Vous devez valoriser obligatoirement l'e-mail ou le téléphone.
Attention : cette méthode est synchrone. Elle ne peut pas être appelée depuis l’UIThread.
Remarque
les erreurs du SDK.
Accéder aux informations sur le lecteur mPOS
Pour accéder aux informations concernant le lecteur, le sdk met à disposition la fonction suivante :
CardReader reader = MposSDK.getCardReaderData();
Cette fonction retourne un objet CardReader
String terminalId;
String aidVersion;
String emvKeyVersion;
String terminalVersion;
String serialNumber;
String manufacturerId;
String model;
Date lastUpdateDate;
Integer nlpa;
Mettre à jour le Numéro Logique du Point d’Acceptation (NLPA)
Pour mettre à jour le NLPA :
MPosSDK.updateNlpa(newNlpa);
Champ
Format
Valeur
newNlpa
int
Ex : 001
Requis
Remarque :
La valeur du Nlpa doit être comprise entre 001 et 999.
Attention : Vous devez redémarrer le SDK une fois le NLPA modifié.
Configurer l'orientation du device
Nous préconisons l’utilisation de la propriété configChanges dans le fichier AndroidManifest afin de ne
pas recréer l’activity lors d’un changement d’orientation.
android:configChanges="orientation|screenSize"
Arrêter le SDK
Une fonction existe pour arrêter proprement le SDK :
MposSDK.shutdown();
Cette fonction doit être appelée sur la méthode onDestroy de votre activity principale.
Remarque
les erreurs du SDK.
Gérer les erreurs du SDK
Il est fortement recommandé de gérer les erreurs et les informations remontées par le SDK par un affichage
explicite afin de faciliter l’expérience utilisateur et d’éviter un support sur des problèmes identifiables.
Si une erreur intervient lors de l’exécution d’une fonction du SDK, la méthode onError du callback est
appelée avec un objet Result contenant l’erreur.
Le SDK gère l’affichage des messages d’erreur. En conséquence, l’application appelante n’est pas obligée
d’afficher les messages d’erreur.
Les types d’exception retournés
Code d'erreur
Description
MPOS_CARD_READER_UNAVAILABLE
Erreur de communication avec le lecteur
MPOS_CARD_READER_ERROR
Lecteur en erreur
MPOS_BLUETOOTH_DISABLED
Bluetooth inactif
MPOS_NO_INTERNET_CONNECTION
Pas de connexion internet
MPOS_AUTHENTICATION_ERROR
Erreur d’authentification sur le serveur mPOS
MPOS_CONTRACT_ERROR
Erreur de contrat
MPOS_INVALID_PARAM
Paramètre fourni au SDK invalide
MPOS_INTERNAL_ERROR
Erreur interne
MPOS_INVALID_TOKEN
Le jeton est invalide
Exemple : session expirée.
MPOS_CODE_SUPERVISOR_ERROR
Mauvais code superviseur

Télécharger en format PDF

Transcription

Documents pareils

Cours de formation au printemps 2017 Responsable de la gestion

Quand je suis fâché

SDK et interfaces ouvertes – Intégration au bénéfice

EZMaker SDK Express (C725B)

SDK et interfaces ouvertes – Intégration au bénéfice

Intégrateur SDK audio (CDD /CDI) La Société : 3D Sound Labs est

Développement d`une Application Multimédia pour Android

veille préparatoire smartphone

Game Developer