SDK React Native

Notre SDK natif vous aide à communiquer avec l'API Client. Il offre :

• Des wrappers pratiques pour les réponses API.
• La gestion de tous les détails concernant le cryptage des informations de paiement.
• La mise en cache des logos et images des produits de paiement pour fournir des informations supplémentaires sur ces produits.
• Une mise en forme conviviale des données de paiement, telles que les numéros de carte et les dates d'expiration.
• La validation des entrées.
• Des vérifications pour déterminer à quel émetteur un numéro de carte est associé.

Notre application d'exemple simule l'interface utilisateur pour l'ensemble du processus de paiement basé sur l'interaction entre l'application et notre plateforme. Trouvez le code source du SDK et de l'application d'exemple sur GitHub, y compris les instructions d'installation.

Pourquoi utiliser le SDK React Native

Notre SDK React Native vous aide à intégrer des paiements en ligne dans des applications Android et Swift via une seule bibliothèque. Il gère de nombreux détails techniques pour vous, de sorte que vous n'avez pas à travailler directement avec l'API Client pour les tâches courantes. Les principaux avantages de l'utilisation du SDK sont :

• Moins de code à écrire et à maintenir – Le SDK inclut des fonctionnalités prête à l'emploi, ce qui réduit le temps de développement et la maintenance continue.
• Authentification simple et sécurisée – Le SDK s'occupe de l'authentification et de la logique liée à la sécurité, rendant la configuration plus rapide et plus sûre.
• Une intégration plus stable dans le temps – La plupart des modifications de la plateforme sont gérées au sein du SDK, minimisant l'impact sur le code de votre application.
• Une configuration plus rapide et un support plus facile – L'utilisation du SDK permet des intégrations plus standardisées, rendant l'intégration plus rapide et le support plus efficace.

Intégration du SDK

Pour créer des paiements, vous devez d'abord intégrer le SDK à votre projet. Vous pouvez trouver toutes les versions du SDK dans notre référentiel. Nous avons préparé les exigences et les instructions d'installation pour le SDK ci-dessous.

Exigences

Ce SDK est conçu pour les applications React Native et possède les dépendances partenaires suivantes :

• react
• react-native

Votre backend doit être capable de créer une session client en utilisant l'API serveur. La réponse de la session fournit les valeurs nécessaires pour initialiser le SDK.

Installation

Installez ce SDK en utilisant votre gestionnaire de paquets Node préféré : npm, yarn ou pnpm.

npm install onlinepayments-sdk-client-reactnative 

Vous pouvez également utiliser le SDK en tant que module CommonJS ou ES module.

// ES module  
import { init } from 'onlinepayments-sdk-client-reactnative';  

// CommonJS  
const { init } = require('onlinepayments-sdk-client-reactnative'); 

Android

Lors de l'installation du SDK sur Android, activez la prise en charge de multidex dans votre fichier build.gradle si la minSdkVersion est définie à 20 ou moins.

defaultConfig {
    ...
    multiDexEnabled true
    ...
}

dependencies {
    ...
    implementation 'androidx.multidex:multidex:2.0.1'
    ...
}

Après avoir intégré avec succès le SDK à votre projet, vous pouvez continuer à l'intégrer au système de paiement complet. Le processus de paiement complet consiste en ces étapes :

1. Initialisation du SDK
2. Récupération des méthodes de paiement possibles
3. Récupération et affichage des détails de la méthode de paiement
4. Validation des données fournies
5. Chiffrement et transfert des données de paiement
6. Finalisation de la transaction

1. Initialiser le SDK

Tout d'abord, vous devez créer une Session permettant la communication entre l'API du serveur et le client. Votre application doit disposer de son propre serveur, agissant comme un intermédiaire entre notre client et l'API du serveur.

Comme le client initie le paiement dans votre application, votre application cliente demande à votre application serveur de créer une Session. Lorsqu'une application serveur reçoit une demande, elle peut créer une Session via CreateSession à partir du SDK du serveur.

Après avoir configuré et connecté votre application à l'API du serveur, vous recevez une réponse contenant des informations sur la Session créée. Une réponse typique ressemble à ceci :

{  
    clientSessionId: '47e9dc332ca24273818be2a46072e006',  
    customerId: '9991-0d93d6a0e18443bd871c89ec6d38a873',  
    clientApiUrl: 'https://clientapi.com',  
    assetUrl: 'https://asset.com',  
    invalidTokens: []  
}

Maintenant, transmettez clientSessionId, customerId, clientApiUrl et assetUrl à l'application Client. Une fois que l'application reçoit une réponse de l'application Serveur avec les informations de Session, créez un objet Session local sur votre application React Native et initialisez le SDK.

import { init } from 'onlinepayments-sdk-client-reactnative';

const sdk = init(
   {
       clientSessionId: '47e9dc332ca24273818be2a46072e006',
       customerId: '9991-0d93d6a0e18443bd871c89ec6d38a873',
       clientApiUrl: 'https://clientapi.com',
       assetUrl: 'https://asset.com',
   },
   {
       appIdentifier: 'MyShopApp/v1.0.0', // this identifies your application
   },
);

2. Récupérer les méthodes de paiement possibles

La prochaine étape consiste à obtenir et afficher les options de paiement possibles. Utilisez l'instance sdk créée précédemment pour récupérer les produits de paiement disponibles. Récupérez simplement et affichez les listes de BasicPaymentProduct et AccountOnFile afin de laisser votre client en sélectionner un.

import type { PaymentContext } from 'onlinepayments-sdk-client-reactnative';

const paymentContext: PaymentContext = {
   countryCode: 'BE',
   amountOfMoney: { amount: 1000, currencyCode: 'EUR' },
   isRecurring: false,
};

try {
   const { paymentProducts, accountsOnFile } = await sdk.getBasicPaymentProducts(paymentContext);
   // Display the payment products and/or accounts on file.
} catch (error) {
   // handle error state
}

N'oubliez pas que chaque appel de session peut générer des erreurs. Enveloppez votre code dans un bloc try/catch pour éviter cela.

3. Récupérer et afficher les détails des méthodes de paiement

Pour certains produits de paiement, les clients peuvent choisir que notre plateforme stocke leurs identifiants pour les paiements récurrents. Nous appelons les données stockées un account on file (Card On File) ou un token. Vous pouvez réutiliser ce compte enregistré/jeton pour des paiements ultérieurs si vos clients ont choisi la même méthode de paiement.

La liste des produits de paiement disponibles que le SDK reçoit de l'API Client contient également les comptes enregistrés pour chaque produit de paiement. Votre application peut présenter cette liste à l'utilisateur.

En fonction de la méthode choisie par le client, considérez différents flux de données :

Si le client choisit une forme de paiement native, vous devez utiliser le SDK du fournisseur de paiement. Vous devrez gérer la réponse uniquement lors de la dernière étape pour informer le client de l'état de son paiement. En savoir plus sur les paiements natifs dans ce chapitre dédié.

Pour les paiements avec un fournisseur de paiement tiers, vous recevez des données avec l'adresse de redirection dans les propriétés du paiement. Redirigez vos clients dans leur navigateur 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 l'application client. Si la méthode de paiement spécifique nécessite des données supplémentaires (par exemple, Google Pay), vous pouvez déjà disposer de ces données dans le PaymentProduct.

Le processus de paiement standard est un paiement par carte. Une fois que le client a sélectionné le produit de paiement souhaité ou un compte stocké, le SDK peut demander les informations que vos clients doivent fournir pour terminer le paiement.

try {  
   const paymentProduct = await sdk.getPaymentProduct(1, paymentContext);  

   paymentProduct.getFields();     	// array of all the fields the user needs to fill out.  
   paymentProduct.getRequiredFields(); // array of all the required fields the user needs to fill out.  
   paymentProduct.getField('cvv');     // returns a single PaymentProductField by id, or undefined if not found  

   // Display the form with fields to your user.  
   // Use the field helper functions to format and validate data.  
} catch (error) {  
   // handle error state  
}  

Si votre client sélectionne un account on file, vous pouvez renseigner les informations masquées fournies dans les champs de saisie correspondants. Les données préremplies au nom du client sont conformes aux réglementations applicables. Selon le cas d’usage spécifique, votre client peut toutefois devoir fournir certaines données de carte (par exemple, le CVC).

4. Valider les données fournies

Après que votre client a saisi ses informations de paiement, votre application doit valider les données reçues. Mais, avant la validation, vous devrez d'abord enregistrer les informations saisies par le client pour les champs requis dans une instance de PaymentRequest. Cette classe possède une propriété tokenize utilisée pour indiquer si l'application doit stocker les identifiants du client pour des paiements récurrents.

import { PaymentRequest } from 'onlinepayments-sdk-client-reactnative';  

// create payment request; if tokenize is not provided its default value is false.  
const paymentRequest = new PaymentRequest(paymentProduct);  

// to mark the payment request for tokenization:  
paymentRequest.setTokenize(true);  

// to read the current tokenization setting:  
const isTokenized = paymentRequest.getTokenize(); // false by default  

Alternativement, adaptez l'exemple de code en fournissant à la fois le compte enregistré et le produit de paiement correspondant.

import { PaymentRequest } from 'onlinepayments-sdk-client-reactnative';  

// providing paymentProduct and accountOnFile via constructor.  
const paymentRequest = new PaymentRequest(paymentProduct, accountOnFile);  

// or using setAccountOnFile method:  
paymentRequest.setAccountOnFile(accountOnFile);  

Une fois que vous configurez une demande de paiement, fournissez les valeurs pour les champs du produit de paiement. Utilisez les identificateurs des champs, tels que "cardNumber" et "cvv", pour définir les valeurs des champs de la demande de paiement :

paymentRequest.getField('cardNumber').setValue('1245 1254 4575 45');  
paymentRequest.getField('cvv').setValue('123');  

Vous devez maintenant valider les données reçues à l’aide de la liste de validateurs disponible. Pour ce faire, effectuez la validation sur le PaymentRequest en validant à la fois le field values et la payment request.

const field = paymentRequest.getField('cardNumber');  
field.setValue('1245 1254 4575 45');  
if (field.validate().isValid) {  
// the value is in the correct format.  
}  

// or use chained methods  
paymentRequest.getField('cvv').setValue('123').validate();  

const validationResult = paymentRequest.validate();  

if (!validationResult.isValid) {  
    console.log('the following fields are invalid', validationResult.errors);  
}  

Gardez à l'esprit que l'interface de saisie des données doit être entièrement transparente et compréhensible pour vos clients. Si des erreurs de validation se produisent, vous devez leur fournir un retour d'information à leur sujet. Vous recevez des informations d'erreur lors de la validation d'un champ de paiement ou de la validation de la demande de paiement, vous pouvez donc l'utiliser pour afficher des messages d'erreur appropriés. Chaque erreur de validation a une référence au champ défectueux correspondant.

5. Chiffrer et transférer les données de paiement

Après avoir collecté toutes les données et validé les champs, créez une instance de PaymentRequest.

import { PaymentRequest } from 'onlinepayments-sdk-client-reactnative';  

// paymentProduct is retrieved in the previous step.  
const paymentRequest = new PaymentRequest(paymentProduct);  

// set values directly in the corresponding PaymentRequestField instances.  
paymentRequest.getField('cardNumber').setValue('1245 1254 4575 45');  
paymentRequest.getField('cvv').setValue('123');  
paymentRequest.getField('expiryDate').setValue('12/2027');  

// OR with a helper method  
paymentRequest.setValue('cardNumber', '1245 1254 4575 45');  
paymentRequest.setValue('cvv', '123');  
paymentRequest.setValue('expiryDate', '12/2027');

Enfin, transmettre l'instance PaymentRequest chiffrée comme suit :

const validationResult = paymentRequest.validate();

if (!validationResult.isValid) {
   // use validationResult.errors to display errors to the user.
} else {
   try {
       const encryptedRequest = await sdk.encryptPaymentRequest(paymentRequest);
       /*
        * encryptedRequest.encryptedCustomerInput can safely be sent to your server.
        * encryptedRequest.encodedClientMetaInfo contains encoded metadata.
        */
   } catch (err) {
       // payment request can not be encrypted, handle error state
   }
}

6. Finaliser la transaction

Après avoir chiffré les données du client, envoyez l'objet chiffré à votre serveur et utilisez-le pour effectuer une requête CreatePayment avec le SDK serveur. Ensuite, fournissez la valeur correspondante de l'objet chiffré dans le champ encryptedCustomerInput pour finaliser le paiement.

Enfin, vous devez transmettre les informations à votre application cliente pour afficher le résultat de la transaction à vos clients.

Objets SDK

Le SDK React Native comprend plusieurs objets. Choisissez l'objet qui vous intéresse dans la liste ci-dessous pour en savoir plus :

• OnlinePaymentSdk
• PaymentContext
• BasicPaymentProduct
• AccountOnFile
• PaymentProduct
• PaymentProductField
• PaymentRequest
  • Tokeniser la PaymentRequest
  • Définir les valeurs des champs pour la PaymentRequest
  • Validez les valeurs du champ 
  • Valider la PaymentRequest
  • AccountOnFile avec des champs en READ_ONLY 
  • Chiffrer la PaymentRequest
• PaymentRequestField
• CreditCardTokenRequest
  • Demande de token de chiffrement
• Masking

OnlinePaymentSdk

Une instance d'OnlinePaymentSdk est requise pour toutes les interactions avec le SDK. Le fragment de code ci-dessous montre comment initialiser une OnlinePaymentSdk. Vous obtenez les détails de la session en effectuant un appel Create Client Session à l'aide de l'API Server. Vous pouvez également inclure une SdkConfiguration optionnelle qui comprend une propriété appIdentifier, servant d'identifiant pour votre application.

import { init } from 'onlinepayments-sdk-client-reactnative';  

const sdk = init(  
{  
        clientSessionId: '47e9dc332ca24273818be2a46072e006',  
        customerId: '9991-0d93d6a0e18443bd871c89ec6d38a873',  
        clientApiUrl: 'https://clientapi.com',  
        assetUrl: 'https://asset.com',  
},  
{  
        appIdentifier: 'MyShopApp/v1.0.0', // this identifies your application  
},  
);  

Toutes les méthodes proposées par l'OnlinePaymentSdk sont des wrappers autour de l'API Client. Elles créent la requête et convertissent la réponse en objets TypeScript qui peuvent contenir des fonctions de commodité.

PaymentContext

PaymentContext est un objet qui contient le contexte/paramètres du paiement à venir. Certaines méthodes de l'instance OnlinePaymentSdk nécessitent cet objet en tant qu'argument. Cet objet peut contenir les détails suivants :

export interface PaymentContext {  
    countryCode: string;      	// ISO 3166-1 alpha-2 country code  
    amountOfMoney: {  
        amount?: number;      	// Total amount in the smallest denominator of the currency  
        currencyCode: string;     // ISO 4217 currency code  
};  
    isRecurring?: boolean;    	// Set `true` when payment is recurring. Default false.  
}  

Vous pouvez également importer cette interface en tant que type lors de l'utilisation de TypeScript :

import type { PaymentContext } from 'onlinepayments-sdk-client-reactnative';

const paymentContext: PaymentContext = {
    // ...
};

BasicPaymentProduct

La SDK propose deux types d'objets pour représenter des informations sur les produits de paiement :

• BasicPaymentProduct
• PaymentProduct

Les instances de BasicPaymentProduct contiennent uniquement les informations nécessaires pour afficher une liste simple de produits de paiement parmi lesquels le client peut choisir.

L'objet PaymentProduct contient des informations supplémentaires sur chaque produit de paiement. Un exemple serait les champs de formulaire spécifiques que le client doit remplir. Vous utilisez généralement cet objet lors de la création d'un formulaire demandant les détails de paiement du client. Consultez la section PaymentProduct pour plus d'informations.

Voici un exemple de comment obtenir les noms d'affichage et les actifs pour le produit Visa.

const basicPaymentProduct = basicPaymentProducts.paymentProducts.find((p) => p.id === 1);  

basicPaymentProduct.id;                                   	// 1  
basicPaymentProduct.label;                                	// VISA  
basicPaymentProduct.logo;                                 	// https://www.domain.com/path/to/visa/logo.gif  
// this is valid only if there is a saved account on file  
basicPaymentProduct.accountsOnFile[0].label;              	// optional display label for the account on file  
basicPaymentProduct.accountsOnFile[0].getValue('cardNumber'); // masked card number, e.g. 4242 **** **** 4242  

AccountOnFile

Une instance d'AccountOnFile représente des informations sur un produit de carte stocké pour le client actuel. Vous devez fournir les identifiants AccountOnFile disponibles pour le paiement en cours dans le corps de la requête lors de l'appel CreateSession de l'API Serveur si vous souhaitez permettre à un client d'utiliser un mode de paiement préalablement tokenisé.

Si le client souhaite utiliser un AccountOnFile existant pour un paiement, vous devriez ajouter l'AccountOnFile sélectionné à la PaymentRequest. L'extrait de code ci-dessous montre comment récupérer les données d'affichage pour un compte enregistré. Vous pouvez afficher cette étiquette et le logo du produit de paiement correspondant au client.

// This contains all unique saved payment accounts from across all available payment products  
const aof = paymentProduct.accountsOnFile[0];  

// get display value of a field  
aof.getValue('cardNumber');      // returns masked card number  
aof.getValue('cardholderName');  // returns the cardholder name, if set  
aof.getValue('expiryDate');      // returns the expiry date, if set  

PaymentProduct

BasicPaymentProduct ne contient que les informations de base sur le produit de paiement que les clients doivent distinguer. Cependant, lorsqu'ils sélectionnent un produit de paiement ou un compte enregistré, ils doivent fournir des informations supplémentaires. Le système a besoin d'informations obligatoires comme le numéro de carte de crédit et la date d'expiration pour traiter le paiement. Les instances de BasicPaymentProduct ne contiennent aucune information sur ces champs.

Donc, lorsque vous avez besoin d'informations de paiement détaillées, appelez l'objet PaymentProduct. Cet objet contient plusieurs instances de PaymentProductField. Chaque PaymentProductField transporte une information nécessaire pour traiter le paiement (par exemple, le numéro de compte bancaire, le numéro de carte de crédit).

Récupérez l'instance du PaymentProduct comme indiqué dans l'extrait de code ci-dessous.

try {  
   const paymentProduct = await sdk.getPaymentProduct(1, paymentContext);  

   paymentProduct.getField('expiryDate'); // returns a single PaymentProductField by id, or undefined if not found  
   paymentProduct.getRequiredFields();    // array of all the required fields the user needs to fill out.  
   paymentProduct.getFields();        	// array of all fields available in the payment product.  
} catch (error) {  
   // handle error state  
} 

PaymentProductField

Les instances de PaymentProductField représentent des champs individuels de produit de paiement (par exemple, numéro de compte bancaire, numéro de carte de crédit). Chaque champ possède ce qui suit :

• Un identifiant
• Un type
• Une définition des restrictions applicables à la valeur du champ
• Une validation intégrée pour les valeurs saisies
• Informations sur la manière dont le champ doit être affiché au client

Dans l'exemple de code ci-dessous, le système récupère le champ avec l'identifiant "expiryDate" à partir d'un produit de paiement. Le système vérifie ensuite les restrictions de données pour déterminer s'il s'agit d'un champ obligatoire ou optionnel. Enfin, le système examine si les valeurs fournies par le client doivent être visibles ou cachées dans l'interface utilisateur.

const field = paymentProduct.getField('expiryDate');  

field.isRequired();      	// true if value is required.  
field.shouldObfuscate();     // true if needs to be obfuscated.  
field.applyMask('0628');     // returns 06/28  
field.removeMask('06/28');   // returns 0628  
field.validate('06/28');     // returns a list of validation errors (empty list if the value is valid)  

PaymentRequest

Une fois que le client a sélectionné un produit de paiement et que le système a récupéré une instance de PaymentProduct, une demande de paiement peut être construite. Vous devez utiliser la classe PaymentRequest comme conteneur pour toutes les valeurs fournies par le client.

import { PaymentRequest } from 'onlinepayments-sdk-client-reactnative';  

// paymentProduct is an instance of the PaymentProduct class (not BasicPaymentProduct).  
const paymentRequest = new PaymentRequest(paymentProduct);  

Lors de l'instanciation du produit de paiement, des méthodes telles que le masquage et le démasquage des valeurs, la validation et le chiffrement fonctionneront. Vous pouvez définir des valeurs via les instances de la classe PaymentRequestField.

Tokeniser la PaymentRequest

Une PaymentRequest possède une propriété tokenize. Vous pouvez l'utiliser pour indiquer si une demande de paiement doit être stockée comme un compte dans le fichier pour de futurs paiements. Vous pouvez contrôler la tokenisation via setTokenize(boolean) et la lire avec getTokenize(). Le fragment de code ci-dessous montre comment construire une demande de paiement lorsque vous souhaitez la stocker comme un compte dans le fichier.

import { PaymentRequest } from 'onlinepayments-sdk-client-reactnative';  

// create payment request; if tokenize is not provided its default value is false.  
const paymentRequest = new PaymentRequest(paymentProduct);  

// to mark the payment request for tokenization:  
paymentRequest.setTokenize(true);  

// to read the current tokenization setting:  
const isTokenized = paymentRequest.getTokenize(); // false by default  

Si le client sélectionne une carte enregistrée, vous devez fournir à la fois la carte enregistrée et le produit de paiement correspondant lors de la construction de la demande de paiement. Vous pouvez récupérer les instances de AccountOnFile à partir des instances de BasicPaymentProduct et PaymentProduct.

import { PaymentRequest } from 'onlinepayments-sdk-client-reactnative';  

// providing paymentProduct and accountOnFile via constructor.  
const paymentRequest = new PaymentRequest(paymentProduct, accountOnFile);  

// or using setAccountOnFile method:  
paymentRequest.setAccountOnFile(accountOnFile);  

Définir les valeurs des champs pour la PaymentRequest

Une fois que vous avez créé une demande de paiement, vous pouvez fournir les valeurs pour les champs de la demande de paiement comme suit :

paymentRequest.getField('cardNumber').setValue('1245 1254 4575 45');  
paymentRequest.getField('cvv').setValue('123');  

Les identifiants des champs, tels que "cardNumber" et "cvv", sont utilisés pour définir les valeurs des champs à l'aide de la demande de paiement. En général, vous pouvez récupérer tous les champs disponibles à partir de l'instance PaymentProduct.

Validez les valeurs du champ

Une fois les valeurs définies, vous pouvez les valider. Le système validera la valeur en utilisant les restrictions de données prédéfinies fixées pour chaque champ. Cela garantit que seules les valeurs valides seront cryptées pour la demande de paiement.

const field = paymentRequest.getField('cardNumber');
field.setValue('1245 1254 4575 45');
if (field.validate().isValid) {
    // the value is in the correct format.
}

// or use chained methods
paymentRequest.getField('cvv').setValue('123').validate();

Valider la PaymentRequest

Une fois que le serveur reçoit toutes les valeurs, il peut valider la demande de paiement. Les appels PaymentRequest valident chacun de leurs PaymentRequestField, qui utilisent leurs DataRestrictions internes et leur logique de validation pour vérifier que les valeurs des champs répondent à toutes les exigences. Le serveur fournira également une liste des erreurs survenues lors de la validation.

S’il n’y a aucune erreur, vous pouvez chiffrer la demande de paiement et l’envoyer à notre plateforme via votre serveur. En cas d’erreurs de validation, vous devez fournir au client un retour d’information concernant ces erreurs. Chaque ValidationErrorMessage contient le message d'erreur et le type d'erreur pour chaque champ afin d'aider à afficher un retour d'information approprié.

const validationResult = paymentRequest.validate();  

if (!validationResult.isValid) {  
    console.log('the following fields are invalid', validationResult.errors);  
}  

Les validations sont définies dans le PaymentProductField. Le serveur les renvoie sous forme de ValidationErrorMessage.

paymentRequest.setValue('cardNumber', '456735000042797');  
paymentRequest.validate();  
/*  
 * {  
 *      errorMessage: "Card number is in invalid format.",  
 *      paymentProductFieldId: "cardNumber",  
 *      type: "luhn"  
 *  }  
 */

AccountOnFile avec des champs en READ_ONLY

Lorsqu'aucun AccountOnFile n'est sélectionné pour la PaymentRequest spécifique, tous les champs de la demande de paiement (comme cardNumber) sont modifiables et peuvent être configurés normalement. Lorsqu'un AccountOnFile est défini sur la PaymentRequest, le SDK impose le comportement suivant :

• Toutes les valeurs de champs précédemment configurées comme non modifiables sont effacées de la PaymentRequest.
• Vous ne pouvez plus définir manuellement des champs en lecture seule. L'appel de la méthode setter renverra une InvalidArgumentError.
• L'appel de paymentRequest.getField(readOnlyFieldId).getValue() renverra undefined.
• Vous pouvez utiliser l'instance AccountOnFile pour récupérer une valeur

Cela garantit que seules les valeurs modifiables sont soumises.

Chiffrer la PaymentRequest

La PaymentRequest n'est prête pour le chiffrement qu'après que les conditions suivantes aient été remplies :

• Le PaymentProduct est défini
• Les valeurs de PaymentProductField ont été fournies et validées
• Les propriétés AccountOnFile ou tokenize sélectionnées ont été configurées (optionnel)

Ensuite, chiffrez la PaymentRequest en appelant le sdk.encryptPaymentRequest(request). Lorsque le sdk.encryptPaymentRequest s'exécute, le système validera d'abord la PaymentRequest pour détecter d'éventuels problèmes avec les données. Cela garantit qu'aucun temps ne sera perdu à chiffrer des données invalides que notre plateforme ne pourra pas traiter dans l'API du serveur.

PaymentRequestField

Les champs de la demande de paiement sont représentés par des instances de PaymentRequestField. Chaque champ fournit des méthodes pour ce qui suit :

• Configurer et récupérer des valeurs
• Obtenir les étiquettes des champs
• Obtenir des valeurs masquées pour l'affichage
• Valider la saisie de l'utilisateur par rapport aux restrictions du champ

const field = paymentRequest.getField('cardNumber');

field.setValue('4242 4242 4242 4242'); // sets the value (mask is automatically removed)
field.getValue();                      // returns the raw unmasked value
field.getMaskedValue();                // returns the value with mask applied
field.getId();                         // returns the field identifier
field.getLabel();                      // returns the display label
field.getPlaceholder();                // returns the placeholder text, if defined
field.getType();                       // returns the field type (e.g. 'string', 'numericstring', 'expirydate')
field.isRequired();                    // true if the field is required
field.shouldObfuscate();               // true if the value should be hidden (e.g. CVV)
field.clearValue();                    // clears the current value
field.validate();                      // returns ValidationResult with isValid and errors

CreditCardTokenRequest

Cette classe est utilisée pour créer une demande de CardTokenization. Elle contient les champs essentiels de la carte de crédit : numéro de carte, nom du titulaire, date d'expiration, cryptogramme visuel (CVV) et identifiant du produit de paiement.

import { CreditCardTokenRequest } from 'onlinepayments-sdk-client-reactnative';

const tokenRequest = new CreditCardTokenRequest();

tokenRequest.setCardholderName('test');
tokenRequest.setExpiryDate('122026');
tokenRequest.setCardNumber('12451254457545');
tokenRequest.setSecurityCode('123');
tokenRequest.setProductPaymentId(1);

Notez qu'aucune règle de validation n'est appliquée aux valeurs définies dans la demande de jeton, car elle est dissociée de l'instance du PaymentProduct. Vous devriez utiliser cette classe comme un assistant pour chiffrer les données nécessaires à la création d'un jeton à l'aide du SDK serveur. Cependant, si des données invalides sont fournies, la demande de CreateToken échouera.

Encrypt token request

try {
    const encryptedRequest = await sdk.encryptTokenRequest(tokenRequest);
    /*
     * encryptedRequest is the encrypted token request which can safely be sent to your server.
     * It consists of two parts: encryptedCustomerInput and encodedClientMetaInfo.
     */
} catch (err) {
    // token request can not be encrypted, handle error state
}

Masking

La SDK offre une fonctionnalité de masquage sur PaymentProductField. Elle vous permet de formater les valeurs des champs et d'appliquer ou de désappliquer des masques sur une chaîne de caractères.

const field = paymentProduct.getField('cardNumber');  

// applying mask on a field.  
field.applyMask('1234123412341234');  

// removing mask from a field.  
field.removeMask('1234 1234 1234 1234');  

// getting masked value from PaymentRequestField  
const maskedValue = paymentRequest.getField('cardNumber').getMaskedValue();  

Fonctionnalités supplémentaires

Le SDK a beaucoup plus à offrir. Jetez un œil aux fonctionnalités suivantes, car elles vous aideront à créer la solution parfaite.

• Chiffrer les données sensibles
• Valider les données
• Appliquer la vérification IIN

Chiffrer les données sensibles

L'un des plus grands atouts du SDK est son outil de cryptage. 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 complet de cryptage/transfert ressemble à ceci :

Vous pouvez chiffrer toutes les informations de paiement fournies avec sdk.encryptPaymentRequest. Lors de l'envoi de la requête, votre application transmet le résultat chiffré à votre serveur e-commerce, qui l'envoie ensuite à l'API du serveur.

import { PaymentRequest } from 'onlinepayments-sdk-client-reactnative';  

const paymentRequest = new PaymentRequest(paymentProduct);  
// get field value from your input component  
paymentRequest.getField('cardholderName').setValue('John Doe');  
// set other fields...  

const validationResult = paymentRequest.validate();  
if (!validationResult.isValid) {  
// display errors to the user.  
} else {  
try {  
    	const encryptedRequest = await sdk.encryptPaymentRequest(paymentRequest);  
    	// encryptedRequest.encryptedCustomerInput can be used to send the encrypted input data  
    	// to the Server SDK to create a payment  
} catch (error) {  
        console.error(error);  
}  
}  

Le SDK se charge de tout le travail lourd, y compris :

• Demander une clé publique via l'API client
• Effectuer le chiffrement
• Encoder le résultat en BASE-64 dans une seule chaîne

Vous avez seulement besoin de vous assurer que l'objet PaymentRequest contient toutes les informations saisies par l'utilisateur. Vous devez envoyer la charge utile chiffrée à votre serveur e-commerce, où elle pourra être transmise à l'API Serveur.

Valider les données

Chaque champ PaymentProductField dispose de DataRestrictions appropriées. L'objet DataRestrictions contient des informations sur tous les champs obligatoires et vérifie si les valeurs saisies respectent la condition de correction. Avec une liste de validateurs abstraits, il possède également une propriété isRequired. Cette propriété indique si les restrictions données sont obligatoires ou non.

Vous pouvez valider une entrée particulière aussi facilement que via la validation de PaymentRequest. En cas d'erreurs, le champ Errors affichera une liste d'erreurs.

Il contient les validateurs 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 ne dépasse pas une plage de vingt-cinq ans dans le futur.
• Email Address : Vérifie le format de l'adresse email fournie par le client.
• Fixed List : Vérifie si la valeur saisie figure dans la liste des possibilités.
• IBAN : Valide l'IBAN fourni par le client.
• Length : Vérifie si la valeur saisie est plus longue que la valeur minimale et si elle ne dépasse pas la valeur maximale.
• Luhn : La formule de somme de contrôle utilisée pour valider diverses numéros d'identification, comme 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 : Vérifie si la valeur saisie correspond à 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 répond pas aux conditions, et un message que vous pouvez facilement traduire.

Appliquer la vérification IIN

Les six premiers chiffres d'un numéro de carte de paiement sont connus sous le nom d'Issuer Identification Number (IIN). Vous pouvez vérifier le produit de paiement et le réseau associés à l'IIN saisi dès que le client entre les six premiers chiffres de son numéro de carte. Utilisez l'appel sdk.getIinDetails pour récupérer ces informations et vérifier si vous pouvez accepter ce type de carte.

Vous pouvez utiliser une instance de OnlinePaymentSdk pour vérifier quel produit de paiement est associé à un IIN. Vous faites cela avec la fonction session.getIinDetails. Le résultat de cette vérification est une instance de IinDetailsResponse. Cette classe possède les éléments suivants :

• Une propriété status indiquant le résultat de la vérification
• Propriété paymentProductId indiquant quel produit de paiement est associé à l'IIN.

Vous pouvez utiliser le paymentProductId retourné pour récupérer le PaymentProduct et afficher le logo approprié au client.

L'IinDetailsResponse possède une propriété status représentée par l'énumération IinStatus. Les valeurs de l'énumération IinStatus sont :

• SUPPORTED indique que l'IIN est associé à un produit de paiement pris en charge par notre plateforme.
• UNKNOWN indique que l'IIN n'est pas reconnu.
• NOT_ENOUGH_DIGITS indique que moins de six chiffres ont été fournis, et qu'il est impossible d'effectuer la vérification de l'IIN.
• EXISTING_BUT_NOT_ALLOWED indique que l'IIN fourni est reconnu, mais que le produit correspondant n'est pas autorisé pour le paiement ou le commerçant actuel.
• UNSUPPORTED indique que l'IIN n'est pas supporté.

import {  
    IinDetailStatus,  
type PaymentContextWithAmount,  
} from 'onlinepayments-sdk-client-reactnative';  

const partialCreditCardNumber = '456735';  
const paymentContext: PaymentContextWithAmount = {  
    countryCode: 'BE',  
    amountOfMoney: { amount: 1000, currencyCode: 'EUR' },  
    isRecurring: false,  
};  

try {  
const response = await sdk.getIinDetails(partialCreditCardNumber, paymentContext);  
// response is an instance of `IinDetailsResponse`  
const isSupported = response.status === IinDetailStatus.SUPPORTED;  

// the list of co-brands, if available:  
const coBrands = response.coBrands;  
} catch (error) {  
// handle error state  
}

Certaines cartes sont co-badgée et peuvent être traitées comme une carte locale (avec une marque locale) ou une carte internationale (avec une marque internationale). Si vous n'êtes pas configuré pour traiter ces cartes locales, l'appel API ne renverra pas ce type de carte dans sa réponse.

Testing

Cette bibliothèque contient des tests unitaires et d'intégration écrits avec Vitest. Vitest démarre par défaut en mode watch dans l'environnement de développement et en mode exécution dans l'environnement CI (lorsque process.env.CI est présent).

Tests unitaires

Les tests d'entrée et de sortie de petites fonctions isolées (unités) peuvent être trouvés dans ./__tests__/unit. Vous n'avez pas besoin d'exposer de variables d'environnement pour exécuter les tests unitaires. Vous pouvez les lancer en utilisant :

yarn test:unit

Vous pouvez trouver les tests d'intégration dans ./__tests__/integration. Ces tests effectuent de véritables appels API vers le sandbox de Worldline et nécessitent un fichier .env à la racine du projet avec des identifiants valides. Consultez .env.example pour les variables requises. Vous pouvez les exécuter en utilisant :

yarn test:integration

Utilisez ce qui suit pour lancer tous les tests (unitaires et d'intégration) en une seule fois :

yarn test