- Directives d'intégration
- American Express Payment Gateway SDK pour Android
American Express Payment Gateway SDK pour Android
Installation
Ce SDK est proposé sous la forme d'un référentiel Maven. Il doit être décompressé à un emplacement de votre projet, et ajouté comme référentiel dans votre fichier build.gradle de projets.
- Depuis le portail Merchant Administration, téléchargez la dernière version du SDK dans un format de fichier ZIP.
- Décompressez ce fichier dans le répertoire racine de votre projet Android. (Par exemple, ~/my-android- project/gateway- repo)
- Ajoutez une référence à ce référentiel local dans le fichier
build.gradlede votre projet. - Dans le fichier
build.gradlede vos modules d'application, incluez le SDK de la passerelle en tant que dépendance.
Pour plus d'informations sur le téléchargement du SDK, voir Intégration Mobile SDK.
// build.gradle
allprojects {
repositories {
mavenCentral()
google()
// Gateway Android SDK repo
maven {
url "$rootDir/gateway-repo"
}
}
}
// app/build.gradle implementation 'com.mastercard.gateway:Mobile_SDK_Android:x.x.x'
Le dossier Mobile_SDK_Android contient un fichier maven-metadata.xml contenant des informations pour la création de la référence d'implémentation de la bibliothèque. Le format Gradle pour l'implémentation est implementation <groupId>:<artifactId>:<version>
Initialiser le SDK
Initialisez le SDK pour Android avant de l'utiliser. Il est recommandé d'effectuer cette opération dans votre classe d'application personnalisée, dans la méthode onCreate() .
// CustomApplication.kt
override fun onCreate()
{
super.onCreate()
// init Gateway SDK
GatewaySDK.initialize
(
this,
"YOUR_MERCHANT_ID",
"Your Merchant Name",
"https://your-merchant-url.com",
"Your gateway region",
callback
)
}
Présentation de la session
Le flux du SDK de la passerelle est basé sur le concept de session. Une session est un conteneur temporaire pour les champs de demande et les valeurs des opérations faisant référence à une session. Pour plus d'informations, voir la documentation Session de paiement
Avantages clés
- Réduit les coûts liés à la conformité PCI, car vous ne gérez ni ne stockez aucun détail du paiement.
- Facilite l'intégration, car vous n'avez pas besoin de gérer directement les valeurs des champs de demande stockés dans une session.
- Réduit la fraude interne, car votre personnel n'a qu'un accès limité aux informations du payeur.
- Vous permet de mettre à jour les champs de demande et les valeurs stockés dans une session. Cela est utile lorsqu'une carte de crédit expire ou que d'autres informations d'un payeur changent.
- Vous permet d'extraire les champs de demande et les valeurs contenus dans une session en spécifiant l'identifiant de session.
Créer une session
Créez une session avec la passerelle pour lancer le flux de paiement sur un appareil mobile.
- Deux appels API doivent être effectués pour préparer cette session aux transactions mobiles.
- Ces appels sont sécurisés par un mot de passe API et doivent donc être lancés depuis votre serveur privé.
| Paramètre de la demande | Exemple |
|---|---|
| authenticationLimit | 25 |
Mettre à jour la session
| Paramètre de la demande | Existence | Exemple |
|---|---|---|
| order.id | Obligatoire | your-order-id |
| order.amount | Obligatoire | 1.23 |
| order.currency | Obligatoire | AUD |
| authentication.acceptVersions | Obligatoire | Authentification 3DS2 |
| authentication.channel | Obligatoire | PAYER_APP |
| authentication.purpose | Obligatoire | PAYMENT_TRANSACTION |
Une fois une session créée sur votre serveur, vous devez
- retourner les informations de session à l'application mobile, et
- créer une instance de l'objet
Session.
// example
val session = Session(
id = "your-session-id",
amount = "1.23",
currency = "USD",
apiVersion = "61", // api version used to create the session
orderId = "your-order-id" // must match order id used on your server
)
Collecter les informations de la carte
L'utilisation de la méthode SDK pour updateSession est facultative, mais elle est recommandée pour contribuer à la portée PCI du serveur du commerçant. Toutefois, les informations relatives à la carte et au jeton peuvent être chargées via une conception différente de l'API et doivent être présentes dans la session avant que l'appel ne soit effectué dans le SDK pour authentifier le payeur.
Saisie manuelle de la carte
Transmettez les informations directement à la passerelle en utilisant un ID de session existant.
// The GatewayMap object provides support for building a nested map structure using key-based dot(.) notation.
// Each parameter is similarly defined in your online integration guide.
val request = GatewayMap()
.set("sourceOfFunds.provided.card.nameOnCard", nameOnCard)
.set("sourceOfFunds.provided.card.number", cardNumber)
.set("sourceOfFunds.provided.card.securityCode", cardCvv)
.set("sourceOfFunds.provided.card.expiry.month", cardExpiryMM)
.set("sourceOfFunds.provided.card.expiry.year", cardExpiryYY);
GatewayAPI.updateSession(session, request, callback);
Segmentation en jetons
Le SDK permet de mettre à jour une session avec les informations de la carte ; vous pouvez utiliser cette session pour effectuer plusieurs opérations avec la passerelle. La segmentation en jetons permet de conserver une carte dans un fichier, et peut être effectuée sur votre serveur avec une session valide.
Suivez ces étapes pour utiliser le Mobile SDK afin de faciliter la création d'un jeton de carte.
- Créez et mettez à jour une session à l'aide du SDK.
- Mettez à jour la session avec les détails de la carte client via la méthode SDK.
GatewayAPIupdateSessionde la passerelle. - Retournez l'identifiant de session à votre serveur et appelez la méthode Create or Update Token (Créer ou mettre à jour un jeton) sur la passerelle avec vos informations d'identification privées de l'API.
- Un ID de jeton est retourné et peut être conservé sur vos serveurs en tant que carte sur fichier.
Pour plus d'informations sur la segmentation en jetons, voir la documentation sur la transaction Create or Update Token (Créer ou mettre à jour un jeton).
Google Pay
Le SDK de la passerelle comprend un utilitaire d'aide, appelé GooglePayHandler, qui permet de collecter des informations sur les cartes à partir d'un portefeuille Google Pay.
Configuration
Pour activer la prise en charge de Google Pay dans votre application, voir la documentation Google Pay.
Ces instructions devraient vous guider sur la manière de :
- Configurer l'API Google Pay
- Demander des informations de paiement à partir du portefeuille Google
- Intégrer le bouton dans votre mise en page, et
- Gérer la réponse de l'API Google Pay.
L'intégration de Google Pay avec le SDK de la passerelle étant facultative, vous devez fournir la dépendance de services de lecture appropriée.
implementation 'com.google.android.gms:play-services-wallet:X.X.X'
La passerelle est intégrée à Google Pay en tant que type PAYMENT_GATEWAY.
Pour demander des informations de carte cryptées à partir de Google Pay
- Utilisez le nom valide
mpgsdans votre demande, et - Remplacez
YOUR_MERCHANT_IDpar l'ID du commerçant que vous utilisez sur la passerelle.
val tokenizationSpecification = JSONObject()
.put("type", "PAYMENT_GATEWAY")
.put("parameters", JSONObject()
.put("gateway", "mpgs")
.put("gatewayMerchantId", "YOUR_MERCHANT_ID"))
Demander des informations du portefeuille
Utilisez GooglePayHandler pour lancer le portefeuille Google Pay avec le client de paiements que vous avez créé et demander les données.
// YourActivity.kt
fun googlePayButtonClicked()
{ try {
val request = PaymentDataRequest.fromJson(paymentDataRequest.toString())
// use the Gateway convenience handler for launching the Google Pay flow
GooglePayHandler.requestData(this, paymentsClient, request)
} catch (e: JSONException) {
Toast.makeText(this, "Could not request payment data", Toast.LENGTH_SHORT).show()
}
}
Gérer la réponse du portefeuille
Le SDK de la passerelle propose un gestionnaire du cycle de vie de Google Pay pour plus de commodité. Vous pouvez implémenter le rappel Google Pay fourni et utiliser le gestionnaire de résultats dans votre activité.
Il n'est donc plus nécessaire de traiter manuellement les résultats de l'activité Google Pay et les étapes importantes de la transaction sont déléguées aux méthodes de rappel.
// YourActivity.kt
override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?)
{
// handle the Google Pay response
if (GooglePayHandler.handleActivityResult(requestCode, resultCode, data, callback)) {
return
}
super.onActivityResult(requestCode, resultCode, data)
}
val googlePayCallback = object : GooglePayCallback {
override fun onReceivedPaymentData(paymentData: JSONObject) {
try {
val description = paymentData.getJSONObject("paymentMethodData")
.getString("description")
Log.d(MyGooglePayCallback::class.java.simpleName,"ReceivedPaymentData: $description")
} catch (e: Exception) {
// handle exception
}
handleGooglePayData(paymentData)
}
override fun onGooglePayCancelled() {
// handle cancelled
}
override fun onGooglePayError(status: Status) {
// handle error
}
}
Mettre à jour une session avec le jeton de paiement
Mettez à jour une session avec la passerelle dès que vous recevez les données de paiement de Google Pay.
fun handleGooglePayData(paymentData: JSONObject) {
val token = paymentData.getJSONObject("paymentMethodData")
.getJSONObject("tokenizationData")
.getString("token")
val request = GatewayMap()
.set("sourceOfFunds.provided.card.devicePayment.paymentToken", token)
GatewayAPI.updateSession(session, request, callback)
}
Authentification du payeur
3D-Secure
L'authentification 3-D Secure or 3DS est conçue pour protéger les achats en ligne contre les fraudes sur les cartes de crédit en vous permettant d'authentifier le payeur avant de soumettre une demande Authorization (Autoriser) ou Pay (Payer).
L'authentification EMV 3DS, également connu sous le nom de 3DS2 sur la passerelle, est la nouvelle version conçue pour améliorer la sécurité des achats en ligne tout en fournissant des paiements fluides aux payeurs considérés comme à faible risque par le serveur de contrôle d'accès (ACS).
Le serveur ACS peut déterminer le risque en utilisant les informations fournies par le commerçant, les empreintes digitales de l'appareil et/ou les interactions précédentes avec le payeur. Le serveur ACS demande au payeur d'effectuer une action (par exemple, de saisir un code PIN) uniquement lorsqu'une vérification supplémentaire est requise pour authentifier le payeur, ce qui permet d'améliorer les taux de conversion.
Les systèmes d'authentification pris en charge sont notamment Mastercard Identity Check, Visa Secure et American Express SafeKey.
L'authentification dans les Mobile SDK est limitée à l'authentification 3DS2. Si l'authentification 3DS2 n'est pas disponible, l'authentification ne se poursuit pas. Toutefois, vous pouvez toujours procéder au paiement si la passerelle vous le recommande.
Pour plus d'informations sur l'authentification 3-D Secure, voir la documentation Authentification 3-D Secure.
Détails de l'authentification
Le Mobile SDK intégré collecte les métriques de l'appareil pour les envoyer à la passerelle avec les informations sur la transaction lorsque vous effectuez une authentification Mobile SDK, c'est-à-dire que vous vérifiez l'identité d'un titulaire de carte dans une application mobile.
Fournissez autant d'informations que possible sur le payeur et la transaction afin d'augmenter les chances de réussite de l'authentification.
Ces informations supplémentaires peuvent être ajoutées à votre session avec une demande Update session (Mettre à jour la session).
| Paramètre | Existence | Description |
|---|---|---|
| order.merchantCategoryCode | Facultatif | Identique au code de votre profil de commerçant. |
| Groupe de paramètres billing.address | Facultatif | Il est fortement recommandé de l'inclure dans votre demande chaque fois que cela est possible. |
| Groupe de paramètres shipping.address | Facultatif | Il est fortement recommandé de l'inclure dans votre demande chaque fois que cela est possible. |
| Groupe de paramètres customer | Facultatif | Il est fortement recommandé de l'inclure dans votre demande chaque fois que cela est possible. |
device tel qu'il apparaît dans la documentation n'est pertinent que pour les paiements avec redirection. Il ne doit pas être utilisé pour les authentifications de payeurs basés sur un appareil mobile.Ces mesures aident le système à déterminer comment ou si le titulaire de la carte doit être authentifié. Lors de l'authentification, l'utilisateur peut s'attendre à être confronté à l'un des deux flux d'authentification :
- Sans friction : le serveur ACS a recueilli suffisamment d'informations sur le titulaire de la carte pour l'authentifier. Aucune autre action n'est requise de la part de l'utilisateur.
- Authentification : le serveur ACS exige que le titulaire de la carte effectue une étape d'authentification supplémentaire qui consiste à saisir un mot de passe à usage unique, à se connecter à sa banque émettrice, etc. Le Mobile SDK intégré gère l'affichage d'une interface native pour cette authentification. L'interface utilisateur de ces écrans peut être personnalisée en transmettant des paramètres
UICustomizationau SDK de la passerelle lors de l'initialisation.
Pour plus d'informations, voir la documentation sur la transaction Authenticate Payer (Authentifier le payeur).
authentication.PSD2.exemption n'est actuellement pas pris en charge dans le SDK. Effectuer une authentification
L'authentification du payeur est considérée comme une transaction à part entière sur la passerelle, et nécessite donc un ID de transaction unique.
Si vous collectez le paiement d'une commande, vous pouvez
- corréler un paiement et une transaction d'authentification en utilisant le même ID de commande pour chaque transaction,
- chaque transaction est affichée comme une transaction distincte dans le portail Web de la passerelle, comme l'UUID.
AuthenticationHandler.authenticate(activityContext, session, "your-auth- transaction-id", callback)
your-auth-transaction-id est un identifiant unique de cette transaction qui la différencie de toutes les autres transactions pour la commande. Ceci est nécessaire car la passerelle utilisera le paramètre your-auth-transaction-id pour rechercher les résultats de l'authentification qu'elle a stockés lorsque vous avez demandé au SDK d'authentifier le payeur. La passerelle transmet ensuite les informations requises à l'acquéreur pour la demande de paiement.Interpréter la réponse
La méthode authenticate renverra un objet AuthenticationResponse qui contient :
- des informations importantes sur le résultat, et
- les actions réalisées au cours de l'opération.
Le champ le plus important à utiliser est response.recommendation. Il peut contenir la valeur PROCEED ou DO_NOT_PROCEED.
- PROCEED : indique « OK pour continuer avec un paiement ou une autorisation ».
- DO_NOT_PROCEED : indique que quelque chose a échoué lors de l'opération d'authentification. L'objet
AuthenticationErrorpeut être utilisé pour avoir plus d'informations.
À compter de la version 70 de l'API de la passerelle, vous pouvez recevoir les erreurs suivantes :
AuthenticationError.recommendation_ResubmitWithAlternativePaymentDetails: indique que vous devez demander d'autres détails de paiement au payeur. Par exemple, une nouvelle carte ou un autre mode de paiement ; vous devrez soumettre à nouveau la demande avec les nouveaux détails.AuthenticationError.recommendation_AbandonOrder: indique que le prestataire de services de paiement, le système ou l'émetteur vous demande d'abandonner la commande.AuthenticationError.recommendation_DoNotProceed: indique que la passerelle a échoué à traiter la demande, et qu'il n'y a aucun moyen pour que cette transaction réussisse.
Pour plus d'informations, reportez-vous aux guides d'intégration.
AuthenticationHandler.authenticate(activityContext, session, "your-auth-transaction-id") { response ->
when(response.recommendation) {
AuthenticationRecommendation.PROCEED -> {
// continue to payment/authorization
}
AuthenticationRecommendation.DO_NOT_PROCEED -> {
if (response.error !=null) {
if (response.error is AuthenticationError.RecommendationResubmitWithAlternativePaymentDetails) {
// "Authentication not successful, re-enter card details
}
} else {
// "Authentication not successful"
}
}
}
}
Si l'authentification échoue, vous pouvez examiner le response.error pour obtenir plus d'informations sur la cause.