Étapes d'intégration
Pour utiliser le Mobile SDK iOS ou Android avec Mastercard Gateway, suivez ces instructions.
Étape 1 : Télécharger le SDK et la documentation
Les versions iOS et Android du Mobile SDK et la documentation associée peuvent être téléchargées à partir de Merchant Administration (MA) :
- Connectez-vous à MA, puis sélectionnez Admin > Téléchargement de logiciel.
- Cliquez sur le lien approprié et suivez les invites pour télécharger le fichier requis.
L'écran Admin - Téléchargements de logiciels et de documentation s'affiche. Il contient le Mobile SDK et les guides d'intégration Mobile SDK.
Version appareil et version simulateur pour iOS
Le Mobile SDK pour iOS est publié avec deux versions :
- Version appareil : le code binaire est activé pour la version appareil, ce qui permet à l'application d'avoir une empreinte moindre sur l'appareil de l'utilisateur. Cependant, la version ne prend pas en charge l'architecture x86_64. Les développeurs ont tendance à préférer la version appareil du SDK comme version de publication.
- Version simulateur : Pour utiliser un simulateur, vous avez besoin de l'architecture x86_64. Cela signifie que le code binaire est désactivé, ce qui entraîne une plus grande empreinte de l'application. Les développeurs ont tendance à préférer la version simulateur lors du développement, où l'empreinte n'est pas une réelle préoccupation.
Pour plus d'informations, voir la documentation d'Apple :
Étape 2 : Installer et initialiser le SDK
Cette rubrique comprend des instructions sur la manière d'installer et d'initialiser le SDK.
iOS
Pour installer le SDK dans votre projet Xcode :
- Faites glisser le dossier
Gateway-SDK.xcframeworkdans votre projet Xcode. - Ajoutez la bibliothèque aux cadres, bibliothèques et contenu intégré de votre cible.
- Lancez une opération import Gateway (Importer la passerelle) du cadre si nécessaire.
- Si nécessaire, définissez le Gateway-SDK.xcframework en tant que package Swift local avec l'option .binaryTarget.
- Assurez-vous d'inclure uSDK.xcframework dans votre projet. Le SDK dépend du paramètre uSDK.xcframework regroupé dans le fichier ZIP.
// AppDelegate.swift import Gateway
Vous devez initialiser le SDK avant de l'utiliser. Il est recommandé d'effectuer cette opération dans votre classe AppDelegate.
// AppDelegate.swift
GatewaySDK.shared.initialize(
merchantId: "MERCHANT_ID",
merchantName: "Merchant Name",
merchantUrl: "https://merchant-url.com",
region: "Your gateway region"
Android
Le SDK est présenté sous la forme d'un référentiel Maven.
Pour installer le SDK dans votre projet :
- Décompressez le 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 votre module d'application, incluez le Mobile SDK comme dépendance.
// 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>.
Vous devez initialiser le SDK avant de l'utiliser. Il est recommandé d'effectuer cette opération dans votre classe personnalisée Application de la fonction 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",
region: "Your gateway region",
callback
)
}
Recommandations de sécurité pour l'intégration de notre SDK
- Limitation des tentatives de mise à jour de session : implémentez un nombre limite de tentatives de mise à jour de la session pour empêcher les attaques par force brute et les accès non autorisés.
- Mesures de sécurité supplémentaires :
- Intégration CAPTCHA : utilisez CAPTCHA pour valider l'authenticité de l'utilisateur et empêcher les attaques automatisées.
- Authentification biométrique : utilisez la reconnaissance des empreintes digitales ou des visages pour une authentification solide de l'utilisateur et pour contrecarrer les tentatives d'accès non autorisé.
- Protection DDoS : mettez en œuvre des mécanismes de protection DDoS robustes pour vous protéger contre les attaques volumétriques et garantir une disponibilité continue du service.
- Détection de robots : intégrez des techniques avancées pour identifier et limiter les activités des robots malveillants qui exploitent les vulnérabilités des applications.
- Limitation du débit : appliquez des politiques strictes de limitation du débit pour réguler les demandes des clients ou des adresses IP, afin de garantir une allocation équitable des ressources et de limiter les abus.
- Épinglage SSL avec notre propre serveur : Incluez pour garantir une communication sécurisée, en empêchant les attaques de type "man-in-the-middle" et les accès non autorisés au serveur.
Étape 3 : Créer et mettre à jour une session
Le flux Mobile SDK est basé sur le concept d'une 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 Principes de base des sessions.
Créez et mettez à jour une session avec la passerelle pour initier le flux de paiement sur un appareil mobile :
- Pour préparer cette session pour les transactions mobiles, envoyez une demande d'API
CREATE SESSION(Créer une session). Pour les champs de demande, voir le tableau des champs de la demandeCREATE SESSION(Mettre à jour la session). - Pour mettre à jour la session, envoyez la demande
UPDATE SESSION(Mettre à jour la session) avec les champs obligatoires. Pour les champs de demande, voir le tableau des champs de la demandeUPDATE SESSION(Mettre à jour la session) obligatoires.
Tableau : Champs de la demande CREATE SESSION (Créer une session)
| Paramètre de la demande | Description | Exemple |
|---|---|---|
| authenticationLimit | Nombre d'opérations pouvant être soumises à la passerelle en utilisant l'ID de cette session comme mot de passe. L'ID de session est utilisé comme mot de passe dans les demandes authentifiées par session liées à l'authentification 3-D Secure (3DS). | 25 |
Tableau : Champs de demande UPDATE SESSION (Mettre à jour la session) obligatoires
| Paramètre de la demande | Description | Exemple |
|---|---|---|
| order.id | Identifiant unique de cette commande. | your-order-id |
| order.amount | Montant total de la commande. | 1.23 |
| order.currency | Devise de la commande. | AUD |
| authentication.acceptVersions | Version 3DS que vous acceptez pour ce paiement. Si vous ne spécifiez pas de version, 3DS2 est accepté. La passerelle utilise l'authentification 3DS2, si prise en charge par l'émetteur et la carte. Si l'authentification 3DS2 n'est pas disponible, l'authentification ne se poursuit pas. | Authentification 3DS2 |
| authentication.channel | Canal dans lequel la demande d'authentification est initiée. | PAYER_APP |
| authentication.purpose | Objectif de l'authentification. | PAYMENT_TRANSACTION |
Une fois une session créée sur votre serveur :
- Renvoyez les informations de session à l'application mobile pour les utiliser dans d'autres opérations.
- Créez une instance de l'objet
Session.
let sessionId = "session-id" let apiVersion = "61" // api version used to create the session let orderId = "order-id" // must match order id used on your server let amount = "1.23" let currency = "USD"
// example
val session = Session(
id = "session-id",
amount = "1.23",
currency = "USD",
apiVersion = "61", // api version used to create the session
orderId = "order-id" // must match order id used on your server
)
apiVersion doit avoir la même valeur pour tout le cycle de vie de la transaction, de la création de la session au paiement final.Étape 4 : Collecter les informations de paiement
Vous pouvez : collecter les informations de paiement auprès du payeur de plusieurs manières :
- Si votre niveau de conformité PCI le permet, vous pouvez recueillir manuellement les détails de la carte et les ajouter à la session. Pour plus d'informations, voir Détails de la carte transmis manuellement.
- Si votre niveau de conformité PCI ne vous permet pas de manipuler des données sensibles, vous pouvez utiliser le mode de paiement Apple Pay ou Google Pay pour obtenir un jeton de paiement qui représente une carte que le payeur a ajoutée à son portefeuille Apple ou Google Pay. Vous ajoutez ensuite le jeton à la session. Pour plus d'informations, voir Apple Pay et Google Pay.
La fonction updateSession() est utilisée dans le Mobile SDK pour ajouter les informations de paiement, les détails de la carte ou le jeton à la session. Les informations de paiement doivent être présentes dans la session avant de procéder à l'authentification facultative du payeur et à la transaction de paiement proprement dite.
updateSession() constitue le moyen le plus simple de charger les détails du paiement dans la session sans affecter votre portée PCI. Toutefois, si la portée PCI n'est pas un problème, vous pouvez télécharger les détails d'une autre manière, par exemple au moyen de la demande UPDATE SESSION (Mettre à jour la session) depuis votre serveur.Détails de la carte transmis manuellement
Recueillez les détails de la carte auprès du payeur sur l'écran de l'application et transmettez les informations directement à la passerelle à l'aide de l'ID de session qui a été renvoyé plus tôt dans la réponse CREATE SESSION (Créer une session).
// 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()
request.sourceOfFunds.provided.card.nameOnCard.value = nameOnCard
request.sourceOfFunds.provided.card.number.value = cardNumber
request.sourceOfFunds.provided.card.securityCode.value = cvv
request.sourceOfFunds.provided.card.expiry.month.value = cardExpiryMM
request.sourceOfFunds.provided.card.expiry.year.value = cardExpiryYY
GatewayAPI.shared.updateSession(sessionId, apiVersion: apiVersion, payload: request) { (response) in
// handle result
}
// 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);
Après avoir mis à jour la session avec les détails de la carte, vous pouvez utiliser un jeton pour stocker les détails de la carte pour vous permettre de stocker le jeton en vue d'une utilisation ultérieure lorsque le payeur revient ou lorsque vous devez effectuer des transactions initiées par le commerçant. Par exemple, en raison de paiements récurrents. Pour segmenter en jetons les détails de la carte, utilisez l'opération CREATE Or UPDATE TOKEN (Créer ou mettre à jour un jeton) sur votre serveur avec l'ID de session valide. Pour plus d'informations, voir Segmentation en jetons.
Étape 5 : Créer l'opération de paiement
Lorsque le payeur a été authentifié et que la session contient les détails de paiement tels que les détails de la carte ou un jeton, envoyez la demande de transaction de paiement PAY (Payer) ou AUTHORIZE (Autoriser) depuis votre serveur, en incluant l'ID de session dans la demande. Pour plus d'informations, voir Effectuer une demande d'API du serveur.