SDK React Native
Ciblez l'URL de base de l'API la plus à jour
Nous vous encourageons à toujours cibler l'URL de base de l'API la plus à jour lors de l'envoi de requêtes à notre plateforme. Consultez notre guide dédié pour un aperçu complet.
Pour vous permettre une transition en douceur, les anciennes URL de base de l'API restent disponibles jusqu'à nouvel ordre.
Le SDK React Native vous aide à communiquer avec l'API Client en vous offrant :
- Des encapsulations pratiques pour les réponses de l'API.
- Une gestion de chiffrement des informations de paiement.
- Un cache des logos des méthodes de paiement.
- Une traduction des textes et des messages.
- Un formatage convivial des données de paiement telles que les numéros de carte et les dates d'expiration.
- Une validation des saisies utilsiateurs.
- Des vérifications pour déterminer à quel émetteur un numéro de carte est associé.
Trouvez le code source du SDK sur GitHub avec les instructions d'installation.
Pour comprendre comment utiliser ce SDK, consultez la documentation suivante :
- Intégration mobile/client – familiarisez-vous avec divers concepts.
- API Reference Client – le SDK englobe l'API Client et (entre autres) expose les réponses des appels de services web sous forme d'objets. Comprendre l'API Client vous aidera également à comprendre ces objets du SDK.
- Le SDK sur GitHub – le SDK contient une application exemple fonctionnelle qui peut vous aider à comprendre comment utiliser au mieux le SDK.
- Ce document actuel vous aidera à comprendre le flux global lors de la création de pages de paiement en utilisant le SDK.
Une fois que vous êtes prêt, lisez les chapitres suivants sur la manière de préparer et d'utiliser le SDK.
À des fins de développement et de test, vous pouvez utiliser notre API Explorer. Il vous permet d'interroger facilement notre API Serveur. Nous ne recommandons pas son utilisation en environnement de production.
Pour créer des paiements, vous devez d'abord intégrer le SDK à votre projet. Toutes les versions du SDK sont disponibles publiquement dans notre dépôt. Pour simplifier l'intégration, nous avons préparé un package ci-dessous pour un accès rapide.
Le SDK est disponible via npm.js.
npm
Vous pouvez ajouter le SDK comme dépendance à votre projet en exécutant la commande suivante : en ajoutant le code suivant à votre package.json où ‘x.y.z’ est le numéro de version :
npm install onlinepayments-sdk-client-reactnative
Après l'intégration réussie du SDK à votre projet, vous pouvez procéder à l'intégration avec l'ensemble du système de paiement. Le processus de paiement complet se compose des étapes suivantes :
- Initialisation des objets Session et PaymentContext
- Réception des méthodes de paiement possibles
- Réception et affichage des détails de la méthode de paiement
- Validation des données fournies
- Chiffrement et transfert des données de paiement
- Finalisation de la transaction
1. Initialiser les objets Session et PaymentContext
Tout d'abord, vous devez créer un objet Session pour permettre la communication entre votre application Cliente et notre API Serveur. Votre application Cliente doit avoir son propre serveur, agissant comme un intermédiaire entre votre application Cliente et notre API Serveur.
Étant donné que c'est votre application Cliente qui initie le paiement, votre application Cliente doit demander à l'API Serveur de créer un objet Session. L'API Serveur utilise alors la fonctionnalité Créer une Session du SDK.
Essayez notre API Explorer pour envoyer une requête CreateSession.
Après avoir configuré et connecté votre application Cliente à notre API Serveur, vous recevez un objet Session contenant les informations suivantes :
{
"assetUrl": "https://assets.test.cdn.v-psp.com/s2s/515c2c0bd13d5dd4bd42",
"clientApiUrl": "https://payment.preprod.direct.worldline-solutions.com/",
"clientSessionId": "68a4b0b183a34016b4b694b97938f75b",
"customerId": "cf7d7aafd42e4a1cb9e4b0624a5041b1",
"invalidTokens": []
}
Une fois que votre application Cliente reçoit un objet Session contenant les informations, créez un objet Session local pour stocker les données côté application Cliente.
Ensuite, créez un objet PaymentContext. Il contient les informations de paiement : la devise, le pays, le montant, etc. Vous utiliserez les objets PaymentContext et Session tout au long du processus de paiement.
Chaque objet Session a une durée de vie fixe de 3 heures. Si elle expire, vous devez créer un nouvel objet Session
Différentes méthodes de paiement sont disponibles pour différents objets PaymentContext. Si vous modifiez une variable, vous devrez recommencer le processus. Seule la Session peut rester la même si le paiement est effectué avec le même consommateur.
2. Recevoir les méthodes de paiement possibles
La prochaine étape consiste à obtenir et à afficher les méthodes de paiement possibles. Pour ce faire, créez un objet BasicPaymentProductsResponseListener et utilisez les objets Session et PaymentContext précédemment créés pour invoquer la méthode GetBasicPaymentItems qui enverra un appel GetPaymentProducts à notre API Serveur.
L'exemple de code ci-dessous montre comment initialiser un objet PaymentContext, comment initialiser un objet BasicPaymentProductsResponseListener et comment les utiliser pour obtenir la liste des BasicPaymentProducts avec l'objet Session :
const paymentContext: PaymentContext = {
amountOfMoney: {
amount: 100,
currencyCode: 'EUR'
},
countryCode: 'NL',
isRecurring: false
};
session.getBasicPaymentProducts(
paymentContext,
new BasicPaymentProductsListener(
(paymentProducts) => {
// Permettre au client de sélectionner sa méthode de paiement préférée parmi la liste des méthodes de paiement disponibles.
},
(errorResponse) => {
// Indiquer qu'une erreur s'est produite.
},
(exception) => {
// Indiquer qu'une erreur s'est produite.
}
)
);3. Recevoir et afficher les détails des méthodes de paiement
Les méthodes de paiement sont des instances de BasicPaymentProduct . Votre application Cliente peut utiliser ces éléments pour afficher un écran qui les liste tous.
Si le look-and-feel par défaut de la page vous convient, vous n'avez pas besoin d'apporter de modifications. Si vous n'avez qu'une seule méthode de paiement à afficher, vous pouvez ignorer cette page. Cependant, vous pourriez également vouloir afficher la sélection de AccountOnFile.
Pour certaines méthodes de paiement, les utilisateurs peuvent indiquer s'ils souhaitent que notre plateforme stocke leurs informations d'identification dans Card On File. Nous faisons référence aux données stockées en tant que compte enregistré ou token. Vous pouvez réutiliser ces comptes enregistrés / tokens pour des paiements ultérieurs si vos utilisateurs choisissent la même méthode de paiement.
La liste des méthodes de paiement disponibles envoyée par le SDK vers votre application Cliente contient également les comptes enregistrés pour chaque méthode de paiement. Votre application Cliente peut alors présenter cette liste à l'utilisateur.
En fonction de la méthode choisie par l'utilisateur, vous pouvez envisager les cas suivants :
Si l'utilisateur a choisi une méthode de paiement native, vous devez utiliser le SDK du fournisseur de paiement et traiter la réponse uniquement dans la dernière étape pour informer l'utilisateur du statut du paiement. En savoir plus sur les paiements natifs dans le chapitre dédié.
Pour les paiements avec un fournisseur de paiement tiers, vous recevez les données de redirection dans les données de paiement. Redirigez alors vos utilisateurs vers le portail de paiement tiers pour continuer le processus de paiement. Après le paiement réussi, votre application doit gérer la redirection vers votre application Cliente.
Le processus de paiement standard est un paiement par carte. Une fois que vos utilisateurs ont sélectionné une méthode de paiement ou un compte enregistré, votre application Cliente doit demander les informations nécessaires pour continuer le paiement.
L'objet BasicPaymentProduct, représentant une méthode de paiement, fournit la liste des champs que votre application Cliente doit afficher, y compris l'affichage des indices et des règles de validation. Si vos utilisateurs sélectionnent un compte enregistré, les informations déjà disponibles peuvent être préremplies dans les champs de saisie. Les données préremplies au nom du client sont conformes aux réglementations applicables. En fonction du cas d'usage, vos utilisateurs pourraient tout de même devoir fournir certaines données (c'est-à-dire le CVC).
4. Valider les données fournies
Maintenant, votre application Cliente doit valider les données que vos utilisateurs saisissent. Pour ce faire, utilisez le composant de validation des données. L'interface de saisie des données doit être entièrement transparente et compréhensible pour vos utilisateurs. Nous recommandons l'utilisation des ToolTips pour afficher les éventuelles erreurs de validation.
5. Chiffrer et transférer les données de paiement
Sur la base des données collectées, vous devez créer un objet PaymentRequest. Utilisez l'exemple de code suivant pour des demandes de paiement sans tokenisation et sans comptes enregistrés :
const paymentRequest = new PaymentRequest(paymentProduct);
L'objet PaymentRequest possède une propriété tokenize utilisée pour indiquer si l'API Server doit stocker les informations d'identification de l'utilisateur pour les paiements Card On File. Si vous souhaitez tokeniser la requête de paiement, vous pouvez soit fournir cette propriété dans le constructeur, soit définir la propriété à un moment ultérieur :
const paymentRequestTokenized = PaymentRequest(paymentProduct, undefined, true);
// Ou définir la propriété sur une requête de paiement existante
paymentRequest.tokenize = true;
Un compte enregistré peut être fourni de manière similaire :
const paymentRequestWithAccountOnFile = PaymentRequest(paymentProduct, accountOnFile);
// Ou définir la propriété sur une requête de paiement existante
paymentRequest.accountOnFile= accountOnFile;Une fois que vous avez configuré une requête de paiement, vous devze fournir les valeurs pour les champs de la méthode de paiement. Utilisez les identifiants des champs, tels que "cardNumber" et "cvv", pour renseigner les valeurs :
paymentRequest.setValue("cardNumber", "1234567890");
paymentRequest.setValue("cvv", "123");
Maintenant, vous pouvez valider la requête de paiement. Une liste d'erreurs éventuelles est disponible. Pour toute erreur, vous devez fournir un retour d'information à l'utilisateur. Pour plus d'informations, lisez le chapitre dédié.
const errors = await paymentRequest.validate();
if (errors.length) {
// La requête de paiement est valide et peut être chiffrée et envoyée à
// notre plateforme via l'application Cliente.
}
else {
// Informez l'utilisateur que certains champs contiennent des données invalides.
}Après la validation de l'objet PaymentRequest, chiffrez la requête et envoyez-la à l'API Server. Jetez un œil à l'exemple de code ci-dessous montrant comment utiliser l'objet Session pour chiffrer une requête :
const preparePaymentRequest = new PreparePaymentRequest(paymentRequest);
session.preparePaymentRequest(
preparePaymentRequest,
new PaymentRequestPreparedListener(
(preparedPaymentRequest) => {
// Soumettez les informations contenues dans la requête de
// paiement chiffrée représentée par preparedPaymentRequest
// à notre plateforme.
},
(errorResponse) => {
// Indiquer qu'une erreur s'est produite.
},
(exception) => {
// Indiquer qu'une erreur s'est produite.
}
)
);Voir une description plus détaillée du processus de chiffrement dans le chapitre dédié.
6. Finaliser la transaction
Après avoir reçu les données chiffrées, transmettez-les à l'API Server pour finaliser le paiement en envoyant une requête CreatePayment.
La réponse peut nécessiter des actions supplémentaires de la part de votre application Cliente spécifiées dans l'objet MerchantAction. Dans la plupart des cas, cela implique de rediriger l'utilisateur vers une application externe (c'est-à-dire pour une vérification 3-D Secure). Une fois que vos utilisateurs ont terminé cette vérification, notre plateforme traite la transaction. Lisez la documentation du SDK Serveur pour plus d'informations.
Enfin, vous devez afficher le résultat de la transaction à vos utilisateurs.
Un aperçu complet du flux de paiement est disponible dans le guide Intégration Mobile/Client.
Objets SDK
Le SDK comprend plusieurs objets. Cliquez sur l'objet qui vous intéresse dans la liste ci-dessous pour en savoir plus à son sujet :
- Session
- PaymentContext
- BasicPaymentProduct
- PaymentProduct
- AccountOnFile
- DisplayHints
- PaymentRequest
- PreparedPaymentRequest
- ErrorResponse
Session
Session est le principal objet du SDK. L'objet :
- Est le point d'entrée pour interagir avec nos SDK natifs
- Contient toutes les fonctions pouvant être appelées sur l'API Client
- Est responsable de la conversion des réponses de l'API en objets Dart simples à l'aide d'écouteurs
Pour établir la communication avec l'API Server, il est crucial d'initialiser l'objet Session correctement. Les propriétés obligatoires pour l'initialisation incluent :
- client session identifier
- customer identifier
- client-api-url
- asset-base-url
Vous obtiendrez ces paramètres en utilisant la CreateSession de l'API Server. Référez-vous aux SDK Serveur et à l'API Serveur pour en savoir plus.
Lors de l'initialisation, déterminez si l'application est en production et spécifiez l'identifiant de l'application. Un paramètre supplémentaire vous permet de contrôler si les requêtes et les réponses réseau sont enregistrées dans la console.
Cette fonction de logging est désactivée par défaut et doit toujours être désactivée en production.
L'identifiant de l'application est utilisé dans le Device Metadata du SDK lors de la communication avec l'API Server.
| Propriétés |
|---|
|
Device Metadata
Les Device Metadata incluent les données suivantes :
| Propriétés |
|---|
|
PaymentContext
Les objets PaymentContext contiennent les informations de paiement telles que :
- amountOfMoney
- currency
- countryCode
- isRecurring – une indication pour savoir si le paiement est un paiement unique ou Card On File.
Cet objet :
- Participe aux prochaines étapes de la transaction.
- Doit rester sous la même forme après l'initialisation – vous devez utiliser le même objet pendant tout le processus de transaction.
AmountOfMoney
L'objet AmountOfMoney fournit les informations sur le montant du paiement. Le montant doit être exprimé sous la forme d'une donnée de type "long" dans la devise spécifiée par currencyCode.
Notez que le montant inclut les fractions de devise. L'objet ci-dessous est égal à 1 EUR.
""amountOfMoney"": {
""amount"": 100,
""currencyCode"": ""EUR""
},
BasicPaymentProduct
L'objet BasicPaymentProduct représente une méthode de paiement. Il contient :
- Un identifiant.
- Un champ indiquant le nom de la méthode de paiement.
- Un champ indiquant si notre plateforme peut ou pas stocker les données de paiement en tant que compte enregistré pour les paiements ultérieurs.
- Un champ indiquant si la méthode de paiement permet Card On File.
- Un champ indiquant si la méthode de paiement utilise une redirection vers un tiers.
- Une liste de comptes précédemment enregistrés pour cette méthode de paiement.
- Les données d'affichage du BasicPaymentProduct :
- Un index indiquant à quelle position de la méthode de paiement dans la liste des méthodes de paiement disponibles
- Un nom
- Un logo
- Des informations sur les objets AccountOnFile associées.
- Deux champs contenant des informations spécifiques sur les produits 302 (Apple Pay) et 320 (Google Pay).
PaymentProduct
L'objet PaymentProduct étend l'objet BasicPaymentProduct avec une liste d'objet PaymentProductField. Lorsqu'un utilisateur sélectionne une méthode de paiement ou un compte enregistré, il doit fournir des informations supplémentaires telles qu'une adresse, un numéro de compte bancaire, un numéro de carte de crédit ou une date d'expiration pour traiter le paiement.
Chaque méthode de paiement peut avoir plusieurs champs que l'utilisateur doit compléter pour le traitement des paiements. Les objets PaymentProductField représentent ces informations supplémentaires de la méthode de paiement.
Pour récupérer des objets PaymentProduct, utilisez le code suivant :
const paymentProductRequest: PaymentProductRequest = {
productId,
paymentContext
};
session.getPaymentProduct(
paymentProductRequest,
new PaymentProductListener(
(paymentProduct) => {
// Permettez au client de sélectionner une méthode de paiement ou un compte
// facultatif parmi la liste des méthodes de paiement
// représentées par paymentProducts.
},
(errorResponse) => {
// Indiquer qu'une erreur s'est produite.
},
(exception) => {
// Indiquer qu'une erreur s'est produite.
}
)
);PaymentProductField
PaymentProductField représente une information d'une méthode de paiement. Chaque objet a :
- Un identifiant
- Un type
- Des informations sur la manière d'afficher l'information à l'utilisateur.
- Une définition des restrictions qui s'appliquent à la valeur de l'information.
- Une liste de 'ValidationErrorMessages'.
L'objet inclut une méthode de validation des données pour déterminer si une valeur donnée est valide. La méthode est basée sur DataRestrictions. Elle retourne ValidationErrorMessages et des méthodes pour masquer et désérialiser la valeur au moyen du StringFormatter intégré.
Le code ci-dessous montre comment récupérer le champ avec l'identifiant "cvv" d'une méthode de paiement.
const field = paymentProduct.getPaymentProductFieldById("cvv");
if (field !== undefined) {
const isRequired = field.dataRestrictions.isRequired;
const obfuscate = field.displayHints?.obfuscate;
const errorMessages = await field.validateValue("123");
const isValid = errorMessages.length === 0;
}Dans cet exemple, nous :
- Inspectons les restrictions de données du champ pour voir si ce champ est requis ou optionnel.
- Inspectons les restrictions d'affichage du champ pour voir si les valeurs fournies par un utilisateur doivent être masquées à l'écran.
- Validons la valeur "123".
- Inspectons le nombre d'erreurs de validation pour voir si la valeur fournie est valide.
AccountOnFile
L'objet AccountOnFile représente un compte enregistré pour une méthode de paiement. Il inclut :
- Un identifiant
- L'identifiant de la méthode de paiement correspondant
- Une liste de clé-valeur
- Des informations sur la façon d'afficher le compte enregistré
- Une méthode qui produit un nom décrivant le compte enregistré.
Récupérez les objets AccountOnFile d'un objet BasicPaymentProduct en utilisant le code suivant :
function getSelectedAccountOnFile(paymentProduct: BasicPaymentProduct, accountOnFileId: string) {
for (var aof of paymentProduct.accountsOnFile) {
if (aof.id === accountOnFileId) {
return aof;
}
}
return undefined;
}
DisplayHints
DisplayHints sont des objets contenant des informations, divisés en trois types :
- PaymentProductDisplayHints: Les informations les plus importantes concernant BasicPaymentProduct, c'est-à-dire un nom et un logo. Une propriété supplémentaire est displayOrder indiquant l'ordre d'affichage par rapport aux autres BasicPaymentProducts. Utilisez-les pour afficher la liste des objets BasicPaymentProduct.
- AccountOnFileDisplayHints: La liste contenant les paires clé-valeur des ProductFields et le masque à afficher (par exemple, des astérisques) sur la donnée de l'objet AccountOnFile.
- PaymentProductFieldDisplayHints: Définit le mode d'affichage des PaymentProductFields. En plus du nom et de l'espace réservé, il contient PreferredInputType, sur la base duquel vous pouvez choisir :
- Le type de clavier approprié que vous devriez utiliser.
- Si l'élément doit toujours être affiché comme AlwaysShow.
- Si la valeur Obfuscate doit être masquée, ainsi que la valeur de Mask – une référence à la ToolTip assignée et à FormElement.
Tooltip
L'objet Tooltip permet de faciliter la saisie des données. Il peut être disponible dans les objets DisplayHints d'un objet PaymentProductField. Il peut contenir un texte explicatif ou une image, par exemple, une photo d'une carte avec un CVV masqué.
FormElement
Une description simplifiée de l'élément visuel vous indiquant comment l'afficher correctement en tant que texte, liste, devise, date ou booléen.
PaymentRequest
Cet objet enveloppe la relation entre le PaymentProduct sélectionné, AccountOnFile et les valeurs saisies. Elle vous permet d'extraire facilement des valeurs masquées ou non masquées. Il contient une méthode de validation des données saisies.
Consultez le chapitre dédié au chiffrement pour plus d'informations.
PreparedPaymentRequest
Une instance de classe PreparePaymentRequest est le résultat du chiffrement d'une requête de paiement réalisé à l'aide d'une instance de classe Session. Elle a deux propriétés, encryptedFields et encodedClientMetaInfo – les données qui doivent être envoyées à notre plateforme.
Consultez le chapitre dédié au chiffrement pour plus d'informations.
ErrorResponse
Si un appel API échoue en raison d'une erreur, l'objet ErrorResponse contiendra les informations sur l'erreur. Il contient un message, un objet ApiError optionnel et un objet Throwable optionnel.
ApiError
ApiError contient un errorId et une liste optionnelle d'erreurs API qui peuvent être utilisées pour aider à déterminer l'erreur qui s'est produite.
L'identifiant de l'application est utilisé dans le Device Metadata du SDK lors de la communication avec l'API Server.
| Propriétés |
|---|
|
Device Metadata
Les Device Metadata incluent les données suivantes :
| Propriétés |
|---|
|
PaymentContext
Les objets PaymentContext contiennent les informations de paiement telles que :
- amountOfMoney
- currency
- countryCode
- isRecurring – une indication pour savoir si le paiement est un paiement unique ou Card On File.
Cet objet :
- Participe aux prochaines étapes de la transaction.
- Doit rester sous la même forme après l'initialisation – vous devez utiliser le même objet pendant tout le processus de transaction.
AmountOfMoney
L'objet AmountOfMoney fournit les informations sur le montant du paiement. Le montant doit être exprimé sous la forme d'une donnée de type "long" dans la devise spécifiée par currencyCode.
Notez que le montant inclut les fractions de devise. L'objet ci-dessous est égal à 1 EUR.
""amountOfMoney"": {
""amount"": 100,
""currencyCode"": ""EUR""
},
BasicPaymentProduct
L'objet BasicPaymentProduct représente une méthode de paiement. Il contient :
- Un identifiant.
- Un champ indiquant le nom de la méthode de paiement.
- Un champ indiquant si notre plateforme peut ou pas stocker les données de paiement en tant que compte enregistré pour les paiements ultérieurs.
- Un champ indiquant si la méthode de paiement permet Card On File.
- Un champ indiquant si la méthode de paiement utilise une redirection vers un tiers.
- Une liste de comptes précédemment enregistrés pour cette méthode de paiement.
- Les données d'affichage du BasicPaymentProduct :
- Un index indiquant à quelle position de la méthode de paiement dans la liste des méthodes de paiement disponibles
- Un nom
- Un logo
- Des informations sur les objets AccountOnFile associées.
- Deux champs contenant des informations spécifiques sur les produits 302 (Apple Pay) et 320 (Google Pay).
PaymentProduct
L'objet PaymentProduct étend l'objet BasicPaymentProduct avec une liste d'objet PaymentProductField. Lorsqu'un utilisateur sélectionne une méthode de paiement ou un compte enregistré, il doit fournir des informations supplémentaires telles qu'une adresse, un numéro de compte bancaire, un numéro de carte de crédit ou une date d'expiration pour traiter le paiement.
Chaque méthode de paiement peut avoir plusieurs champs que l'utilisateur doit compléter pour le traitement des paiements. Les objets PaymentProductField représentent ces informations supplémentaires de la méthode de paiement.
Pour récupérer des objets PaymentProduct, utilisez le code suivant :
const paymentProductRequest: PaymentProductRequest = {
productId,
paymentContext
};
session.getPaymentProduct(
paymentProductRequest,
new PaymentProductListener(
(paymentProduct) => {
// Permettez au client de sélectionner une méthode de paiement ou un compte
// facultatif parmi la liste des méthodes de paiement
// représentées par paymentProducts.
},
(errorResponse) => {
// Indiquer qu'une erreur s'est produite.
},
(exception) => {
// Indiquer qu'une erreur s'est produite.
}
)
);PaymentProductField
PaymentProductField représente une information d'une méthode de paiement. Chaque objet a :
- Un identifiant
- Un type
- Des informations sur la manière d'afficher l'information à l'utilisateur.
- Une définition des restrictions qui s'appliquent à la valeur de l'information.
- Une liste de 'ValidationErrorMessages'.
L'objet inclut une méthode de validation des données pour déterminer si une valeur donnée est valide. La méthode est basée sur DataRestrictions. Elle retourne ValidationErrorMessages et des méthodes pour masquer et désérialiser la valeur au moyen du StringFormatter intégré.
Le code ci-dessous montre comment récupérer le champ avec l'identifiant "cvv" d'une méthode de paiement.
const field = paymentProduct.getPaymentProductFieldById("cvv");
if (field !== undefined) {
const isRequired = field.dataRestrictions.isRequired;
const obfuscate = field.displayHints?.obfuscate;
const errorMessages = await field.validateValue("123");
const isValid = errorMessages.length === 0;
}Dans cet exemple, nous :
- Inspectons les restrictions de données du champ pour voir si ce champ est requis ou optionnel.
- Inspectons les restrictions d'affichage du champ pour voir si les valeurs fournies par un utilisateur doivent être masquées à l'écran.
- Validons la valeur "123".
- Inspectons le nombre d'erreurs de validation pour voir si la valeur fournie est valide.
AccountOnFile
L'objet AccountOnFile représente un compte enregistré pour une méthode de paiement. Il inclut :
- Un identifiant
- L'identifiant de la méthode de paiement correspondant
- Une liste de clé-valeur
- Des informations sur la façon d'afficher le compte enregistré
- Une méthode qui produit un nom décrivant le compte enregistré.
Récupérez les objets AccountOnFile d'un objet BasicPaymentProduct en utilisant le code suivant :
function getSelectedAccountOnFile(paymentProduct: BasicPaymentProduct, accountOnFileId: string) {
for (var aof of paymentProduct.accountsOnFile) {
if (aof.id === accountOnFileId) {
return aof;
}
}
return undefined;
}
DisplayHints
DisplayHints sont des objets contenant des informations, divisés en trois types :
- PaymentProductDisplayHints: Les informations les plus importantes concernant BasicPaymentProduct, c'est-à-dire un nom et un logo. Une propriété supplémentaire est displayOrder indiquant l'ordre d'affichage par rapport aux autres BasicPaymentProducts. Utilisez-les pour afficher la liste des objets BasicPaymentProduct.
- AccountOnFileDisplayHints: La liste contenant les paires clé-valeur des ProductFields et le masque à afficher (par exemple, des astérisques) sur la donnée de l'objet AccountOnFile.
- PaymentProductFieldDisplayHints: Définit le mode d'affichage des PaymentProductFields. En plus du nom et de l'espace réservé, il contient PreferredInputType, sur la base duquel vous pouvez choisir :
- Le type de clavier approprié que vous devriez utiliser.
- Si l'élément doit toujours être affiché comme AlwaysShow.
- Si la valeur Obfuscate doit être masquée, ainsi que la valeur de Mask – une référence à la ToolTip assignée et à FormElement.
Tooltip
L'objet Tooltip permet de faciliter la saisie des données. Il peut être disponible dans les objets DisplayHints d'un objet PaymentProductField. Il peut contenir un texte explicatif ou une image, par exemple, une photo d'une carte avec un CVV masqué.
FormElement
Une description simplifiée de l'élément visuel vous indiquant comment l'afficher correctement en tant que texte, liste, devise, date ou booléen.
PaymentRequest
Cet objet enveloppe la relation entre le PaymentProduct sélectionné, AccountOnFile et les valeurs saisies. Elle vous permet d'extraire facilement des valeurs masquées ou non masquées. Il contient une méthode de validation des données saisies.
Consultez le chapitre dédié au chiffrement pour plus d'informations.
PreparedPaymentRequest
Une instance de classe PreparePaymentRequest est le résultat du chiffrement d'une requête de paiement réalisé à l'aide d'une instance de classe Session. Elle a deux propriétés, encryptedFields et encodedClientMetaInfo – les données qui doivent être envoyées à notre plateforme.
Consultez le chapitre dédié au chiffrement pour plus d'informations.
ErrorResponse
Si un appel API échoue en raison d'une erreur, l'objet ErrorResponse contiendra les informations sur l'erreur. Il contient un message, un objet ApiError optionnel et un objet Throwable optionnel.
ApiError
ApiError contient un errorId et une liste optionnelle d'erreurs API qui peuvent être utilisées pour aider à déterminer l'erreur qui s'est produite.
Utiliser des fonctionnalités supplémentaires
Le SDK a beaucoup plus à offrir. Jetez un œil aux fonctionnalités suivantes, car elles vous aideront à construire la solution parfaite.
- Chiffrer les données sensibles
- Valider les données
- Appliquer la vérification IIN
- Mettre en œuvre les paiements natifs
- Utiliser la logging
Chiffrer les données sensibles
Un des plus grands atouts du SDK est son outil de chiffrement. Il offre une excellente sécurité lors du transfert de données sensibles (c'est-à-dire les numéros de carte, la date d'expiration, le code CVC). Un flux de chiffrement/transfert complet ressemble à ceci :
Vous n'avez pas besoin de faire toutes ces étapes par vous-même. Grâce au SDK, vos actions sont simplifiées :
- Lorsque votre client a complété toutes les informations de paiement requises et confirme le paiement, créez l'objet PaymentRequest, assignez-lui le PaymentProduct sélectionné et remplissez-le avec les valeurs saisies.
- Validez le PaymentRequest créé en utilisant la méthode validate.
- Si aucune erreur de validation n'est détectée, utilisez un objet Session et appelez preparePaymentRequest. Cela effectuera tout le processus de chiffrement pour vous et retournera les données chiffrées.
- Envoyez les données chiffrées à votre serveur.
- Votre serveur envoie les données chiffrées en utilisant la méthode CreatePaymentmethod dans le champ encryptedCustomerInput du corps de la requête.
- Vous envoyez le résultat de la transaction à l'application cliente.
L'algorithme utilisé est RSA-OAEP avec un encodage A256CBC-HS512. Bien qu'il soit possible de mettre en œuvre un chiffrement personnalisé, nous recommandons d'utiliser la fonctionnalité de chiffrement du SDK pour une sécurité optimale. Des données mal chiffrées peuvent entraîner des opérations incorrectes. De plus les données chiffrées ne sont pas vérifiées. Par conséquent, vous devez vous assurer que toutes les opérations précédentes ont été effectuées correctement.
Valider les données
Chaque objet PaymentProductField possède un objet DataRestrictions. L'objet DataRestrictions contient les restrictions à appliquer et permet de valider si les valeurs saisies répondent aux restrictions. En plus d'une liste de validateurs, il possède une propriété isRequired indiquant si le champ est obligatoire ou non.
Vous pouvez valider la saisie d'un champ via la méthode validate de l'objet PaymentRequest. En cas d'erreurs, l'objet Errors permet d'afficher une liste d'erreurs.
Les validateurs possibles sont les suivants :
- Expiration Date : Vérifie si la date d'expiration de la carte saisie n'est pas antérieure à la date actuelle et si elle n'est ultérieure à la date actuelle plus 25 ans.
- Email Address : Vérifie le format de l'adresse e-mail fournie par le client.
- Fixed List : Vérifie si la valeur saisie figure sur la liste des valeurs possibles.
- IBAN : Valide l'IBAN fourni par le client.
- Length : Vérifie si la valeur saisie est plus longue que la valeur minimale mais pas plus longue que la valeur maximale.
- Luhn : La formule de somme de contrôle utilisée pour valider une variété de numéros d'identification, tels que les numéros de carte de crédit.
- Range : Vérifie si la valeur est supérieure à la valeur minimale et si elle n'est pas supérieure à la valeur maximale.
- Regex : Valide que la valeur saisie correspond bien à l'expression régulière.
- TermsAndConditions : Le validateur booléen pour le champ d'acceptation des termes et conditions.
Chaque validateur renvoie une erreur appropriée, indiquant un champ qui ne respecte pas les conditions, et un message que vous pouvez facilement traduire.
Appliquer la vérification IIN
Les huit premiers chiffres d'un numéro de carte de paiement sont connus sous le nom de numéro d'identification de l'émetteur (IIN).
Vous pouvez utiliser une instance de Session pour vérifier quelles méthode de paiement sont associées à un IIN. La vérification est effectuée de manière asynchrone, donc le résultat de la vérification n'est pas disponible immédiatement. Le résultat est une instance de IinDetailsResponse. Cette classe a les propriétés suivantes :
- paymentProductId: La méthode de paiement principal associé à cet IIN.
- countryCode: Le code du pays de la méthode de paiement associé à cet IIN.
- status: L'indicateur du résultat de la vérification de l'IIN. Les valeurs possibles sont :
- SUPPORTED : L'IIN est associé à une méthode de paiement disponible sur notre plateforme.
- UNKNOWN : L'IIN n'est pas reconnu.
- NOT_ENOUGH_DIGITS : Moins de six chiffres ont été fournis.
- EXISTING_BUT_NOT_ALLOWED : L'IIN est reconnu, mais il ne peut pas être utilisé pour le paiement actuel.
- isAllowedInContext: Indique s'il est autorisé d'effectuer un paiement avec la méthode de paiement basé sur le PaymentContext.
- coBrands: Une liste d'instances de IinDetail, qui décrivent les marques associées pour le IIN actuel.
- cardType: La catégorie de la méthode de paiement. Les valeurs possibles sont :
- Crédit
- Débit
- Prépayé
Il est possible qu'une carte de crédit ait plusieurs marques associées et soit ainsi "co-brandé". Les détails du premier moyen de paiement que vos clients peuvent utiliser pour effectuer le paiement dans ce contexte sont toujours stockés dans les champs de premier niveau de IinDetailsResponse. Si le co-branding s'applique, la liste des instances de IinDetail contient toutes les marques associées à la carte, y compris le moyen de paiement qui est stocké dans les champs de premier niveau. Utilisez cette liste pour permettre aux clients de choisir leur marque préférée. S'il n'y a qu'un seul moyen de paiement associé à la carte de crédit, la liste des détails de l'IIN est vide.
async function doIINLookup() {
const unmaskedValue = await paymentRequest.getUnmaskedValue("cardNumber");
const iinDetailsRequest: IinDetailsRequest = {
partialCreditCardNumber: unmaskedValue,
paymentContext: paymentContext
};
session.getIinDetails(
iinDetailsRequest,
new IinDetailsListener(
(response) => {
if (response.status === IinDetailsStatus.Supported) {
if (response.coBrands.length !== 0) {
if(!self.isSelectedPaymentProduct(response.coBrands)){
switchToPaymentProduct(response);
}
// La législation de l'UE exige que, dans le cas d'une
// carte avec plusieurs marques, un client puisse
// choisir quelle marque il souhaite utiliser pour le paiement.
self.showCoBrandNotification();
} else if (response.paymentProductId !== paymentItemId) {
self.switchToPaymentProduct(response);
}
} else {
// Gérer les autres codes de statut.
}
},
(errorResponse) => {
// Indiquer qu'une erreur s'est produite.
},
(exception) => {
// Indiquer qu'une erreur s'est produite.
}
)
);
}
function isSelectedPaymentProduct(coBrands: IinDetail[]): boolean {
const selectedCoBrand = coBrands.find((coBrand) =>
coBrand.paymentProductId === paymentItemId);
return selectedCoBrand !== undefined;
}
function switchToPaymentProduct(response: IinDetailsResponse) {
if (response.isAllowedInContext && response.paymentProductId !== undefined) {
// Passer au moyen de paiement qui est effectivement dans le premier niveau
// de la réponse Iin Details.
paymentItemId = response.paymentProductId;
}
else {
// Informer le client qu'il entre un numéro de carte de crédit qui ne peut actuellement pas être utilisé pour le paiement.
// Montrer au client qu'il peut choisir une autre marque pour payer.
}
}
function showCoBrandNotification() {
// Informer le client qu'il peut choisir une autre marque pour payer.
}Si le statut est différent de la valeur SUPPORTED, les autres champs de IinDetailsResponse seront tous undefined (ou false dans le cas du champ isAllowedInContext).
Mettre en œuvre les paiements natifs
Le SDK prend en charge les paiements natifs pour les appareils mobiles incluant Google Pay pour Android et Apple Pay pour iOS.
Si une méthode de paiement est éligible au paiement natif, le SDK vérifie automatiquement la capacité de l'appareil à effectuer ce paiement natif. Si l'appareil ne remplit pas les conditions requises alors la méthode de paiement est masquée. Grâce à cette mécanique, vous n'avez pas à vous soucier de vérifier vous-même la faisabilité du paiement natif.
Pour les appareils avec iOS, vous pouvez vérifier si le système répond au critère de version minimale (8.0) et utilisez le PKPaymentAuthorizationViewController pour vérifier s'il est possible d'effectuer la transaction.
Consultez notre guide Apple Pay pour plus d'informations.
Utiliser la journalisation
Dans certains scénarios, activer la journalisation des requêtes et des réponses de la communication avec notre plateforme peut être bénéfique.
Activez la journalisation en positionnant la propriété loggingEnabled sur true dans le constructeur de la Session pendant le développement :
const session = new Session({
clientSessionId: '72f564e746bf4644b21776a13bbbbc82',
customerId: 'd621457028f1473b8f4a20d53bc76184',
clientApiUrl: 'https://clientapi.com',
assetUrl: 'https://assets.com',
loggingEnabled: true
});
La logging doit être désactivée dans les environnements de production.