Worldline | SDK JavaScript

Utilisez notre SDK JavaScript natif pour intégrer rapidement et en toute sécurité l'API Client, disposant d'une validation et d'un chiffrement intégrés.

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

Des wrappers utiles à la gestion des réponses API.
La gestion de tous les détails du chiffrement des informations de paiement.
La mise en cache des logo et images pour fournir des informations supplémentaires sur les moyens de paiement.
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 utilisateur.
Des vérifications pour déterminer à quel émetteur une numéro de carte est associée.

Nous vous encourageons à toujours cibler le point de terminaison API le plus à jour lorsque vous envoyez des requêtes à notre plateforme. Consultez notre guide dédié pour une vue d'ensemble complète.

Notre exemple d’application 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’exemple d’application sur GitHub. Vous y trouverez les instructions d'installation.

Pour comprendre comment utiliser ce SDK, consultez la documentation suivante :

Intégration mobile/client – Familiarisez-vous avec divers concepts.
Référence API Client – Le SDK encapsule l'API Client et, entre autres, expose les réponses des appels du service Web sous forme d'objets. Comprendre l'API Client vous aidera à comprendre également ces objets SDK.
Le SDK sur GitHub – Le SDK contient un exemple d’application fonctionnelle, qui peut vous aider à comprendre la meilleure façon de l'utiliser.
Ce document actuel vous aidera à comprendre le flux global lors de la création de pages de paiement avec le SDK.

Pourquoi utiliser le SDK JavaScript

Notre SDK JavaScript vous aide à intégrer les paiements plus rapidement et avec moins d'effort. Il gère de nombreux détails techniques pour vous, afin que vous n'ayez pas à travailler directement avec l'API Client pour les tâches courantes. Voici quelques-uns des principaux avantages de l'utilisation de notre SDK :

Moins de code à écrire et à maintenir – Le SDK comprend des fonctionnalités prêt-à-l’emploi, ce qui réduit le temps de développement et les efforts de maintenance.
Authentification simple et sécurisée – Le SDK s'occupe de la logique d'authentification et de sécurité, rendant la configuration plus rapide et plus sûre.
Intégration plus stable dans le temps – La plupart des modifications de la plateforme sont gérées dans le SDK, minimisant l'impact sur le code de votre application.
Configuration plus rapide et support plus facile – L'utilisation du SDK crée des intégrations plus standardisées, rendant l'intégration plus rapide et le support plus efficace.

Si votre projet a des contrôles stricts sur les dépendances, des besoins en fonctionnalités minimales ou une configuration très légère, l'utilisation du SDK pourrait ajouter du code et des fonctionnalités dont vous n'avez pas réellement besoin. Dans ces cas, travailler directement avec l'API pourrait être plus simple et plus efficace.

Intégration du SDK

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

Exigences

Les versions minimales des navigateurs supportés sont basées sur la dernière fonctionnalité implémentée des "private class fields" :

Chrome 74+
Edge 79+
Safari 14.1+
Firefox 90+
Chrome for Android 109+
Safari on iOS 14.8+
Opera Mobile 72+
Android Browser 109+
Firefox for Android 107+

Installation

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

npm install onlinepayments-sdk-client-js

Les paquets distribués

Vous pouvez utiliser le SDK soit comme un module UMD, soit comme un module ES.

Définition du module universel (UMD)

Le SDK est disponible sous l'espace de noms global onlinepaymentssdk et peut être utilisé de la manière suivante :

<!DOCTYPE html>
<html lang="en">
    <head>
        ...
    </head>
    <body>
        <script src="./node_modules/onlinepayments-sdk-client-js/dist/onlinepayments-sdk-client-js.umd.js"></script>
        <script>
            const sdk = window.onlinepaymentssdk.init({
                ...
            })
        </script>
    </body>
</html>

Utilisation du module ES (ESM)

La plupart des gestionnaires de modules (webpack, rollup, parcel, etc.) prennent en charge les modules ES. Vous pouvez importer le SDK comme suit :

import * as OnlinePaymentsSdk from 'onlinepayments-sdk-client-js';

Depuis la racine du projet, exécutez la commande npm ci pour installer les dépendances requises.

Ensuite, exécutez npm run build. En conséquence, le dossier /dist/ (un dossier de distribution) sera créé, contenant une version originale et une version minifiée de onlinepaymentsdk.js – un SDK entièrement empaqueté avec les composants de chiffrement.

Lors de l'inclusion du SDK, il ajoutera automatiquement l'objet onlinepaymentsdk à l'espace de nom global. Vous pouvez accéder à toutes les fonctionnalités du SDK JavaScript via cet objet.

Exemples d'applications

Nous avons fourni une application exemple que vous pouvez utiliser comme base pour votre propre implémentation. Si vous aimez son apparence et son ressenti, vous n'avez pas besoin de faire aucune modification. Vous pouvez télécharger notre application exemple depuis notre dépôt GitHub.

Après avoir intégré avec succès le SDK dans votre projet, vous pouvez procéder à son intégration avec le système de paiement. Celui-ci se déroule selon ces étapes :

Initialisation du SDK
Récupération des méthodes de paiement possibles
Récupération et affichage des détails de la méthode de paiement
Validation des données fournies
Chiffrement et transfert des données de paiement
Chiffrement et transfert des données de paiement

1. Initialiser le SDK

Premièrement, vous devez créer une instance de l'OnlinePaymentsSdk, permettant la communication entre l'API du serveur et le client. Votre application doit avoir son propre serveur, agissant comme intermédiaire entre notre client et l'API du serveur.

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

Essayez notre Explorateur API pour envoyer une demande CreateSession.

Après avoir configuré et connecté votre application à l'API 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',
    tokens: []
}

Chaque Session a une durée de vie fixe de 3 heures. Si elle expire, vous devez créer une nouvelle Session.

Maintenant, transmettez l'assetUrl, la clientApiUrl, la clientSessionId et le customerId à l'application Client. Une fois que l'application reçoit une réponse de l'application Serveur avec des informations sur la Session, créez une instance de l'objet SDK côté application Client.

import * as OnlinePaymentsSdk from 'onlinepayments-sdk-client-js';

// this is the same as receiver from the create session request
const sessionData =  {
    clientSessionId: '...',
    customerId: '...',
    clientApiUrl: '...',
    assetUrl: '...',
}

const sdk = OnlinePaymentsSdk.init(
    sessionData,
    {
        appIdentifier: 'MyShopIntegration', // 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. La prochaine étape consiste à obtenir et afficher les options de paiement possibles. Étant donné que les éléments de paiement sont des instances de BasicPaymentProduct, votre application peut utiliser ces éléments pour créer un écran qui les répertorie tous. Utilisez l'instance du sdk créée précédemment pour invoquer la méthode getBasicPaymentProducts.

Utilisez notre application exemple pratique comme base pour votre propre implémentation.

Voici un extrait de code montrant comment obtenir la liste des BasicPaymentProducts.

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

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

Vous pouvez sauter cette étape si vous souhaitez utiliser un moyen de paiement spécifique.

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

Pour certains moyens de paiement, les clients peuvent autoriser notre plateforme à stocker leurs identifiants afin de faciliter 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 cet account on file/token pour les paiements ultérieurs si vos clients choisissent le même moyen de paiement. La méthode sdk.getBasicPaymentProducts renverra une liste d’accounts on file associés à la session en cours si ladite session a été créée avec des tokens.

Selon la méthode choisie par le client, prenez en compte les différents cas de flux de données :

Pour les paiements effectués avec un fournisseur de paiement tiers, vous recevez des données contenant l'adresse de redirection dans les propriétés du paiement. Redirigez vos clients dans leur navigateur vers la plateforme de paiement tierce pour poursuivre le processus de paiement. Après que le paiement ait réussi, votre application doit gérer la redirection vers l'application cliente. Si une méthode de paiement spécifique nécessite des données supplémentaires (comme Google Pay), ces données peuvent déjà être fournies avec le PaymentProduct reçu.

Le processus de paiement standard est un paiement par carte. Une fois que vos clients ont sélectionné un article de paiement ou un account on file, le SDK client peut demander les informations nécessaires à vos clients pour le paiement.

sdk.getPaymentProduct(1, paymentContext)
    .then((paymentProduct) => {
        const {
            getFields, // array of all the fields the user needs to fill out.
            getRequiredFields, // array of all the required fields the user needs to fill out.
            getField, // returns a single PaymentProductField by id
        } = paymentProduct;

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

Utilisez notre application d'exemple comme source d'inspiration pour créer votre écran.

4. Valider les données fournies

Maintenant, votre application doit valider les données que vos clients saisissent dans l'interface de votre application. Vous devrez effectuer une validation sur le PaymentRequestField et vérifier à la fois les field values et la payment request.

L'interface de saisie doit être totalement transparente et compréhensible pour vos clients. Donc, s'il y a des erreurs de validation, vous devez leur fournir un retour d'information à ce sujet. Les informations d'erreur sont fournies lors de la validation d'un champ de paiement ou de la validation de la demande de paiement, afin que vous puissiez les utiliser pour afficher des messages d'erreur appropriés.

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

Sur la base des données collectées, vous devez créer une instance de PaymentRequest. Cette classe dispose d'une propriété tokenize utilisée pour indiquer si l'application doit stocker les identifiants du client pour des paiements récurrents.

Utilisez le code suivant pour les demandes de paiement sans comptes enregistrés :

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

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

Alternativement, adaptez l'exemple de code en fournissant à la fois l'account on file Alternativement, adaptez l'exemple de code en fournissant à la fois l’account on file

paymentRequest.setAccountOnFile(accountOnFile);

Une fois que vous avez configuré une demande de paiement, fournissez les valeurs pour les champs du moyen de paiement. Utilisez les identifiants des champs, tels que "cardNumber", "cvv", et "expiryDate", pour définir les valeurs des champs pour la demande de paiement.

paymentRequest.setValue('cardNumber', '1245 1254 4575 45');
paymentRequest.setValue('cvv', '123');
paymentRequest.setValue('expiryDate', '12/2027');

Notez que le format de la date d'expiration pour les produits de paiement par carte de crédit dépend des paramètres de votre compte marchand, il peut donc s'agir de MM/yyyy ou MM/yy. Le format exact est renvoyé par l'API, et la validation du champ ainsi que la validation de la demande de paiement assureront que le format est correct. Consultez la section de validation ci-dessous pour PaymentProductField pour plus d'informations.

Vous pouvez maintenant valider la demande de paiement en utilisant la liste disponible d'erreurs. Pour toute erreur de validation, vous devez fournir un retour d'information au client. Pour plus d'informations, lisez ce chapitre dédié.

const validationResult = paymentRequest.validate();
if (validationResult.isValid) { 
     // The payment request is valid; you can encrypt and send it to our platform via your server.
} else { 
    // Notify the user that some fields contain invalid data.
   var errors = validationResult.errors; 
}

Après la validation du PaymentRequest, cryptez la requête et envoyez-la à votre application serveur. Consultez l'exemple de code montrant comment crypter la requête :

sdk.encryptPaymentRequest(paymentRequest)
    .then((encryptedRequest) => {
        /*
         * encryptedRequest is the encrypted payment request, which can safely be sent to your
         * server. It consists of two parts: encryptedCustomerInput and encodedClientMetaInfo.
         */
    })
    .catch((err) => {
        // payment request can not be encrypted, handle error state
    });

Voir une description plus détaillée du processus de chiffrement dans ce chapitre dédié.

6. Finaliser la transaction

Après avoir crypté les données du client, le travail du SDK Client est terminé. Maintenant, envoyez l'objet crypté à votre serveur et utilisez-le pour effectuer une requête CreatePayment avec le SDK Serveur. Ensuite, fournissez-lui les données cryptées pour finaliser le paiement.

La réponse à la demande CreatePayment peut nécessiter des actions supplémentaires de la part du Client, spécifiées dans l'objet MerchantAction. Dans la plupart des cas, cela consiste à rediriger le client vers un tiers externe (par exemple pour une vérification 3-D Secure). Une fois que vos clients auront effectué cette vérification, notre plateforme traitera la transaction réelle. Consultez la documentation du SDK Serveur pour plus d'informations.

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

Trouvez un aperçu complet du processus de paiement dans le guide d'Intégration mobile/client.

Objets SDK

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

OnlinePaymentSdk
PaymentContext
BasicPaymentProduct
AccountOnFile
PaymentProduct
PaymentProductField
PaymentRequest
- Tokeniser 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 suivant montre comment initialiser le OnlinePaymentsSdk. Vous obtiendrez les données de session en effectuant un appel Create Session via l'API serveur. Vous pouvez également inclure une SdkConfiguration optionnelle qui comprend appIdentifier, un identifiant pour votre application.

import * as OnlinePaymentsSdk from 'onlinepayments-sdk-client-js';

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

PaymentContext

Le PaymentContext est un objet qui contient le contexte/configuration du paiement à venir. Certaines méthodes de l'instance OnlinePaymentsSdk en ont besoin comme 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-js';

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

BasicPaymentProduct

Le SDK contient des informations sur les moyens de paiement de deux manières : BasicPaymentProduct et PaymentProduct. Les instances de BasicPaymentProduct contiennent uniquement les informations nécessaires pour afficher une liste simple de produits de paiement. Lorsqu'ils sont affichés, l'utilisateur peut sélectionner un produit de paiement individuel pour voir des informations supplémentaires à son sujet.

Voici un exemple de comment afficher les noms et les ressources du produit Visa.

const basicPaymentProduct = basicPaymentProducts.paymentProducts.find((p) => p.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; // e.g. 4242 **** **** 4242

AccountOnFile

Une instance de AccountOnFile (AOF) représente des informations sur un produit de paiement par carte stocké pour l'utilisateur actuel. Les données AOF pour la session en cours sont disponibles si l'appel CreateSession côté serveur a fourni les tokens enregistrés. Vous pouvez trouver plus d'informations à ce sujet danse la référence API.

Le fragment de code ci-dessous montre comment récupérer les données d'affichage pour un compte enregistré. Vous pouvez afficher une label au client, accompagnée du logo du produit de paiement correspondant.

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

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

PaymentProduct

Lorsqu'un client sélectionne un article de paiement ou un account on file, il doit saisir des informations supplémentaires, telles que :

Numéro de compte bancaire
Numéro de carte de crédit
Date d'expiration

Sans ces données, le paiement ne peut pas être traité.

Chaque article de paiement peut comporter plusieurs champs qui doivent être remplis pour traiter un paiement. L'instance de la classe PaymentProduct contient une liste de champs que l'utilisateur doit remplir pour compléter le paiement. Il existe plusieurs méthodes d'assistance pour récupérer le PaymentProductField.

sdk.getPaymentProduct(1, paymentContext)
    .then((paymentProduct) => {
        const {
            getField, // array of all the fields available in the payment product.
            getRequiredFields, // array of all the required fields the user needs to fill out.
            getFields, // returns a single PaymentProductField by id
        } = paymentProduct;
    })
    .catch((error) => {
        // handle error state
    });

PaymentProductField

Chaque champ du produit de paiement est représenté par une instance de PaymentProductField. Chaque champ possède :

Un identifiant
Un type
Une définition des restrictions applicables à la valeur du champ
Un ensemble de méthodes d'aide pour formater et valider une valeur d'entrée

Dans le fragment de code ci-dessous, le champ avec l'identifiant expiryDate est extrait d'un produit de paiement. Des méthodes sont disponibles pour déterminer si le champ est obligatoire ou facultatif, et si ses valeurs doivent être obfusqué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 ValidationResult with information whether the validation passed and a list of errors, if any

PaymentRequest

Une fois que l'utilisateur a sélectionné un moyen de paiement et qu'une instance de PaymentProduct a été récupérée, une demande de paiement peut être construite. Vous devez utiliser cette classe comme conteneur pour toutes les valeurs fournies par le client.

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

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

Des méthodes telles que le masquage et le démasquage des valeurs, la validation et le cryptage ne fonctionneront que lorsque le produit de paiement sera instancié.

La définition des valeurs se fait via les instances de la classe PaymentRequestField.

Tokeniser la PaymentRequest

Une PaymentRequest possède une propriété tokenize, qui indique si les informations de paiement du client doivent être enregistrées en tant qu'account on file. Le fragment de code ci-dessous montre comment construire une demande de paiement lorsqu'elle ne doit pas être enregistrée en tant qu'account on file.

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

// create payment request, if tokenization is not provided, its default value is false.
const paymentRequest = new PaymentRequest(paymentProduct, null, true);
// OR
paymentRequest.setTokenize(true);

Si le client a sélectionné un account on file, cette instance doit être définie sur la demande de paiement soit lors de l'instanciation d'un objet, soit avec un setter dédié. Vous pouvez récupérer les instances de AccountOnFile à partir des instances de BasicPaymentProduct et PaymentProduct.

import { PaymentRequest } from 'onlinepayments-sdk-client-js';
// providing paymentProduct and accountOnFile via constructor.
const paymentRequest = new PaymentRequest(paymentProduct, accountOnFile);

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

Notez qu'utiliser un account on file en parallèle du paramètre tokenize n'a pas de sens.

PaymentRequestField

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

Définir et récupérer des valeurs
Obtenir le label du champ
Obtenir des valeurs masquées pour l'affichage
Valider les entrées de l'utilisateur en fonction des restrictions du champ

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');

Validez les valeurs du champ

Une fois qu'une valeur est définie, elle peut être validée. Le système validera la valeur en utilisant les restrictions de données prédéfinies appliquées à chaque champ. Cela garantit que seules les valeurs valides peuvent être 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().isValid;

Valider la PaymentRequest

Une fois que toutes les valeurs ont été fournies, la demande de paiement peut être validée. La méthode PaymentRequest effectue une validation sur chacun de ses PaymentRequestField .

Ces derniers utilisent leur propre logique de validation pour vérifier que les valeurs de champ répondent à toutes les exigences d’un type de carte spécifique et des paramètres du commerçant.

Après la validation, une liste d’erreurs est renvoyée, indiquant quelles exigences ne sont pas remplies pour chaque champ. S’il n’y a pas d’erreurs, vous pouvez chiffrer la demande de paiement et l’envoyer à notre plateforme via votre serveur e-commerce.

En cas d’erreurs de validation, vous devriez fournir au client un retour d’informations concernant ces erreurs, comme indiqué ci-dessus. Chaque ValidationErrorMessage contient le message d’erreur et le type d’erreur pour chaque champ, afin de faciliter l’affichage d’un retour approprié.

const validationResult = paymentRequest.validate();

if (validationErrorMessages.length) {
    console.log('the following fields are invalid', validationErrorMessages);
}

Les validations sont définies dans le PaymentProductField (contenu dans chaque PaymentRequestField) et renvoient ValidationErrorMessage, tel que :

paymentRequest.setValue('cardNumber', '456735000042797');
const result = paymentRequest.validate();
/*
 * result.errors[0] will have this:
 * {
 *      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 (tels que cardNumber) sont modifiables et peuvent être réglés normalement. Lors de la mise en place d'un AccountOnFile sur la PaymentRequest, le SDK applique le comportement suivant :

Toutes les valeurs de champs auparavant modifiables qui ont été définies sont supprimées de la PaymentRequest.
Il n'est plus possible de définir manuellement des champs en lecture seule. Appeler le setter renverra une InvalidArgumentError.
Appeler paymentRequest.getField(readOnlyFieldId).getValue() renverra undefined.
Vous pouvez utiliser l'instance AccountOnFile pour récupérer une valeur.

Cela garantit que seules les valeurs pouvant être modifiées sont soumises.

Chiffrer la PaymentRequest

Lorsque la PaymentRequest est initialisée, vous pouvez appeler sdk.encryptPaymentRequest(request) pour chiffrer ce qui suit :

Les valeurs des champs du produit de paiement
L'account on file sélectionné (optionnel)
Les informations de tokenisation (optionnel)

Bien que vous puissiez utiliser vos propres algorithmes de cryptage pour chiffrer une demande de paiement, nous vous conseillons d'utiliser la fonctionnalité de cryptage fournie par le SDK.

Lorsque la méthode sdk.encryptPaymentRequest s'exécute, le système valide d'abord le PaymentRequest pour détecter d'éventuels problèmes avec les données. Cela garantit que nous ne chiffrons pas de données invalides, que notre plateforme ne peut pas traiter via l'API Serveur.

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 de la carte, date d'expiration, cryptogramme visuel (CVV) et identifiant du produit de paiement.

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 token, puisqu'elle est détaché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 token en utilisant le SDK côté serveur. Cependant, si des données invalides sont fournies, la demande de CreateToken échouera.

Vous devez fournir des valeurs brutes, et non masquées (par exemple "1226" au lieu de "12/26"). Vous pouvez toujours utiliser une instance d'un PaymentProduct pour formatter et valider les valeurs.

Demande de token de chiffrement

sdk.encryptTokenRequest(tokenRequest)
    .then((encryptedRequest) => {
        /*
         * 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

Pour aider à formater les valeurs de champ en fonction des masques, le SDK propose un ensemble de fonctions de masquage de base dans PaymentProductField.

const field = paymentProduct.getField('cardNumber');
// applying a mask on a field.
field.applyMask('1234123412341234'); // returns “1234 1234 1234 1234”

// removing mask from a field.
field.removeMask('1234 1234 1234 1234'); // returns “1234123412341234”

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

Fonctionnalités supplémentaires

Le SDK offre beaucoup plus de fonctionnalités. 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 du 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 numéros de carte, date d'expiration, code CVC). Tout le processus 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 crypté à votre serveur e-commerce, qui l'envoie à l'API serveur.

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

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

const validationErrorMessages = paymentRequest.validate().errors;

if (validationMessages.length) {
    // display errors to the user.
} else {
    sdk.encryptPaymentRequest(paymentRequest)
        .then((encryptedRequest: EncryptedRequest) => {
            // encryptedRequest.encryptedCustomerInput can be used to send the encrypted input data
            // to the Server SDK to create a payment
        })
        .catch(console.error);
}

Le SDK effectue tout le travail lourd, y compris :

Demander une clé publique à l'API Client
Effectuer le chiffrement
Encoder le résultat en BASE-64 en une seule chaîne de caractères

Vous devez simplement vous assurer que l'objet PaymentRequest contient toutes les informations saisies par l'utilisateur. La charge utile chiffrée doit être envoyée à votre serveur e-commerce, où elle peut être transmise à l'API Server.

Bien que les données de paiement soient cryptées sur les appareils de vos clients, elles restent hors de portée pour votre niveau de certification PCI-DSS car vous ne pouvez pas être responsable de la sécurité d'un appareil que vous ne contrôlez pas.

Pour minimiser le risque pour les données de carte et le niveau, nous vous recommandons fortement de respecter les points suivants :

Utilisez le mécanisme de cryptage de notre SDK client (clés publiques et privées), qui est conforme aux exigences du PCI DSS. Crypter les données de carte sur les appareils de vos clients en utilisant la clé publique de notre plateforme assure que votre serveur de commerce électronique ne traitera pas de données de carte non cryptées. En conséquence, votre type PCI requis pour cette méthode d'intégration est le SAQ A.
Développez votre application mobile conformément aux exigences du PCI Security Standards Council comme décrit dans cette FAQ.

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 retourne 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 du IIN

Les six premiers chiffres d'un numéro de carte de paiement sont connus sous le nom de Issuer Identification Number (IIN). Vous pouvez utiliser l'appel sdk.getIinDetails() pour récupérer le produit de paiement et le réseau associés à l'IIN fourni, en tant qu'instance de IinDetailsResponse.

Cette classe possède une propriété status qui indique le résultat de la vérification et une propriété paymentProductId qui indique le moyen de paiement associé à l'IIN, si reconnu.

La propriété status peut prendre plusieurs valeurs :

"SUPPORTED" indique que l'IIN est associé à un produit de paiement supporté 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 en cours.

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

sdk.getIinDetails(partialCreditCardNumber, paymentContext)
    .then((response) => {
        // response is an instance of `IinDetailsResponse`
        const isSupported = response.status === IinDetailsStatus.SUPPORTED;

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

Certaines cartes sont co-marquées et peuvent être traitées comme une carte locale (avec une marque locale) ou une carte internationale (avec une marque internationale). Si votre compte n’est pas configuré pour traiter ces cartes locales, cet appel API ne renverra pas ce type de carte dans sa réponse.

Dès que le système capture les six premiers chiffres du numéro de carte, vous pouvez utiliser la méthode sdk.getIinDetails() pour vérifier le type de carte et voir si vous pouvez accepter cette carte. Vous pouvez utiliser le paymentProductId renvoyé pour récupérer le moyen de paiement et fournir un retour visuel à l'utilisateur en affichant le logo du moyen de paiement approprié.

SDK JavaScript