SDK Flutter

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

• Des outils Dart pratiques pour la gestion des réponses de l’API.
• La gestion de tous les aspects liés au chiffrement des données de paiement.
• Une mise en forme intuitive des données de paiement, notamment des numéros de carte et des dates d'expiration.
• La validation des données saisies.
• La vérification de l’émetteur associé au numéro de carte.

Notre application de démonstration simule l'interface utilisateur tout au long du parcours de paiement et l'interaction entre l'application et notre plateforme. Le code source du SDK et de l'application de démonstration est disponible sur GitHub, ainsi que les instructions d'installation.

Pourquoi utiliser le SDK Flutter

Notre SDK Flutter vous permet d’intégrer des paiements en ligne dans vos applications Android et iOS via une seule bibliothèque. Il prend en charge de nombreux aspects techniques, vous évitant ainsi d’interagir avec l'API Client pour les opérations courantes.

Les principaux avantages de l'utilisation du SDK sont les suivants :

• Moins de code à développer et à maintenir – Le SDK fournit des fonctionnalités prête à l'emploi, ce qui réduit le temps de développement et les efforts de maintenance.
• Une authentification simple et sécurisée – Le SDK gère l'authentification et les mécanismes de sécurité associés, 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, ce qui limite l'impact sur le code de votre application.
• Une configuration plus rapide et un support facilité – Le SDK favorise une intégration standardisée, ce qui accélère sa mise en œuvre et facilite le support technique.

Intégration du SDK

Pour créer des paiements, vous devez d'abord intégrer le SDK à votre projet. Toutes les versions du SDK sont disponibles dans notre référentiel. Vous trouverez ci-dessous les prérequis et les instructions d’installation du SDK.

Exigences

Exigences	Version minimale
Flutter SDK	3.32.0 ou version supérieure
Dart SDK	3.8.0 ou version supérieure (et <4.0.0)
Cible de déploiement iOS	iOS 15.6+
Version minimale de minSdk sur Android	API 23 (Android 6.0)

Installation

Ajoutez une dépendance au SDK dans le fichier pubspec.yaml de votre application, où x.y.z correspond au numéro de version :

dependencies:
    // other dependencies
    online_payments_sdk: ^x.y.z

Exécutez ensuite la commande suivante : flutter pub get.

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'
    ...
}

Applications de démonstration

Le SDK inclut une application de démonstration dans le dossier example. Elle montre comment initialiser une instance de OnlinePaymentSdk et effectuer un appel à un moyen de paiement.

Un exemple plus complet, qui présente l’ensemble du parcours de création d’un paiement, est également disponible ici.

Une fois le SDK intégré avec succès à votre projet, vous pouvez poursuivre son intégration au parcours de paiement complet, qui se déroule en six étapes :

1. Initialisation du SDK
2. Récupération des méthodes de paiement disponibles
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

Vous devez d’abord créer une instance de OnlinePaymentSdk, qui permet d’assurer la communication entre l’API Server et le client. Votre application doit disposer de son propre serveur, qui sert d’intermédiaire entre votre application cliente et notre API Server.

Le paiement étant initié par le client dans votre application, celle-ci envoie une requête à votre serveur pour créer une session. À la réception de cette requête, votre serveur peut créer une session à l’aide de la méthode CreateSession du SDK Server.

Une fois votre application configurée et connectée à l’API Server, vous recevez une réponse contenant les informations relatives à la session créée. Utilisez ces informations pour créer une instance de OnlinePaymentSdk. Voici un exemple d’initialisation :

import 'package:online_payments_sdk/online_payments_sdk.dart'; 

final sdk = OnlinePaymentSdk( 
  SessionData( 
    clientSessionId: '47e9dc332ca24273818be2a46072e006', 
    customerId: '9991-0d93d6a0e18443bd871c89ec6d38a873', 
    clientApiUrl: 'https://clientapi.com', 
    assetUrl: 'https://assets.com', 
  ), 
  configuration: SdkConfiguration( 
    appIdentifier: 'Flutter Example Application/v1.0.0', 
  ), 
); 

Transmettez ensuite les valeurs de clientSessionId, customerId, clientApiUrl et assetUrl à l’application Client.

Une fois que l'application reçoit la réponse de l'application Serveur avec les informations de données de session, créez une instance OnlinePaymentSdk côté application Client.

Après avoir créé une instance de OnlinePaymentSdk, vous devez également configurer l’objet PaymentContext, comme illustré ci-dessous. Celui-ci contient notamment la devise, le pays et le montant du paiement.

AmountOfMoney amountOfMoney = AmountOfMoney(
    1298, // in cents
    "EUR" // three-letter currency code as defined in ISO 4217
);

PaymentContext paymentContext = PaymentContext(
    amountOfMoney,
    "NL", // two-letter country code as defined in ISO 3166-1 alpha-2
    false // true, if it is a recurring payment
);

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

L'étape suivante consiste à récupérer et à afficher les options de paiement disponibles. Récupérez et affichez les listes de BasicPaymentProduct et AccountOnFile afin de permettre à votre client de choisir le moyen de paiement souhaité.

try { 
  final basicPaymentProducts = await sdk.getBasicPaymentProducts(paymentContext); 
  // Display the contents of basicPaymentProducts.basicPaymentProducts & basicPaymentProducts.accountsOnFile to your customer 
} on SdkError catch (e) { 
  // Inform the customer that something went wrong while retrieving the available Payment Products 
} 

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

Dans certains cas, les clients peuvent choisir d’autoriser notre plateforme à enregistrer leurs données de paiement en vue de paiements récurrents.

Ces données enregistrées, appelées accounts on file (Card On File) ou Token, peuvent être réutilsées lors d’un paiement ultérieur avec le même moyen de paiement.

Le SDK récupère également les comptes enregistrés (accounts on file) et associés à chaque moyen de paiement. Votre application peut ainsi 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 un moyen de paiement natif, vous devez utiliser le SDK du prestataire de paiement concerné. La réponse devra être traitée uniquement lors de la dernière étape afin d'informer le client de l'état de son paiement. Pour en savoir plus sur les paiements natifs, consultez le chapitre dédié.

Pour les paiements faisant appel à un prestataire tiers, l'adresse de redirection est renseignée dans les propriétés du paiement. Redirigez le client vers le portail de paiement du prestataire tiers afin qu’il puisse poursuivre le paiement. Une fois le paiement effectué avec succès, votre application doit gérer la redirection vers l’application cliente.

Le parcours de paiement standard est celui d’un paiement par carte. Une fois que le client a sélectionné le moyen de paiement souhaité, récupérez l’objet PaymentProduct enrichi, il décrit les informations que le client doit fournir pour autoriser le paiement. Affichez ensuite les champs correspondants dans votre application.

try { 
  final paymentProduct = await sdk.getPaymentProduct( 
    1, // id of the payment product you want to retrieve 
    paymentContext, 
  ); 
  // Display the fields to your customer 
} on SdkError catch (e) { 
  // Inform the customer that something went wrong while retrieving the Payment Product 
} 

Si votre client sélectionne un compte précédemment enregistré (account on file), le système préremplit automatiquement les champs correspondants avec les données sauvegardées. Ce préremplissage est effectué dans le respect de la réglementation applicable. Selon le cas d’usage, le client peut toutefois devoir fournir certaines données de carte, comme le cryptogramme visuel (CVC).

4. Valider les données fournies

Une fois que le client a renseigné ses informations de paiement, votre application doit les valider. Pour cela, commencez par enregistrer les informations saisies dans une instance de PaymentRequest, en renseignant les champs requis. La propriété tokenize de PaymentRequest permet d’indiquer si les données de paiement du client doivent être tokenisées afin de pouvoir être réutilisées pour des paiements ultérieurs.

PaymentRequest paymentRequest = PaymentRequest(
    paymentProduct: paymentProduct, // Product for which the request will be made
    tokenize: false // Flag for tokenising the request
);

Si le client souhaite utiliser un compte déjà enregistré, adaptez le code en renseignant également l’objet accountOnFile correspondant à son moyen de paiement :

PaymentRequest paymentRequest = PaymentRequest(
  paymentProduct: paymentProduct,
  tokenize: true, // Optional argument to tokenise the request - default is false
  accountOnFile: accountOnFile // Optional argument to set the accountOnFile to be used for the paymentRequest
);

Après avoir configuré la requête de paiement, renseignez les valeurs des champs correspondant au moyen de paiement. Utilisez les identifiants des champs, tels que cardNumber, cvv et expiryDate, pour définir les valeurs dans la demande de paiement :

paymentRequest.setValue(
    "cardNumber", // field id
    "1245 1254 4575 45" // value
);
paymentRequest.setValue("cvv", "123");
paymentRequest.setValue("expiryDate", "12/25");

Vous devez ensuite valider les données reçues à l’aide de la liste de validateurs disponible. Pour cela, lancez la validation sur le PaymentRequest afin de contrôler à la fois les valeurs des champs et la requête de paiement dans son ensemble.

// Validate all fields in a Payment Request
List errorMessages = await paymentRequest.validate();
// check if the payment request is valid
if (errorMessages.isEmpty) {
// payment request is valid
} else {
// payment request has errors
}

Veillez à ce que le formulaire de saisie soit clair et compréhensible pour vos clients. Si des erreurs de validation sont détectées, affichez des messages explicites afin que vos clients puissent les identifier et les corriger.

Les erreurs sont renvoyées sous la forme d’une liste d’objets ValidationErrorMessage, que vous pouvez utiliser pour afficher les messages d’erreur appropriés.

for (ValidationErrorMessage errorMessage in errorMessages) {
    // do something with the errorMessage, like displaying it to the user
}

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

Une fois PaymentRequest validé, appelez sdk.encryptPaymentRequest(paymentRequest) pour générer un objet EncryptedRequest. Transmettez ensuite les données client chiffrées à votre serveur comme suit.

try { 
  final encryptedRequest = await sdk.encryptPaymentRequest(paymentRequest); 
  // Forward encryptedRequest.encryptedCustomerInput to your server 
} on SdkError catch (e) { 
  // Encrypting the request failed 
} 

6. Finaliser la transaction

Après avoir chiffré les données du client, transmettez l'objet chiffré à votre serveur et utilisez-le pour envoyer une requête CreatePayment avec le SDK Server. Transmettez ensuite les données chiffrées dans le champ encryptedCustomerInput pour finaliser le paiement.

Pour terminer, vous devez transmettre le statut du paiement à votre application cliente pour afficher le résultat de la transaction à vos clients.

Objets SDK

Le SDK Flutter comprend plusieurs objets. Sélectionnez celui qui vous intéresse dans la liste ci-dessous pour en savoir plus :

• OnlinePaymentSdk
• PaymentContext
• BasicPaymentProducts
• BasicPaymentProduct
• AccountOnFile
• PaymentProduct
• PaymentProductField
• PaymentRequest
  • Tokeniser une PaymentRequest
  • Définir les valeurs des champs pour la requête PaymentRequest
  • Valider la PaymentRequest
  • Chiffrer la PaymentRequest
• Masking

OnlinePaymentSdk

Une instance de OnlinePaymentSdk est requise pour toutes les interactions avec le SDK. L'extrait de code suivant montre comment l'initialiser. Les données de session sont obtenues en effectuant un appel un appel Create Client Session via l’API Server.

import 'package:online_payments_sdk/online_payments_sdk.dart'; 

final sdk = OnlinePaymentSdk( 
  SessionData( 
    clientSessionId: '47e9dc332ca24273818be2a46072e006', 
    customerId: '9991-0d93d6a0e18443bd871c89ec6d38a873', 
    clientApiUrl: 'https://clientapi.com', 
    assetUrl: 'https://assets.com', 
  ), 
  configuration: SdkConfiguration( 
    appIdentifier: 'Flutter Example Application/v1.0.0', // optional application identifier 
  ), 
); 

Toutes les méthodes proposées par OnlinePaymentSdk encapsulent des appels à l'API Client. Elles construisent la requête et convertissent la réponse en objets Dart qui peuvent contenir des fonctions utilitaires. Chaque méthode est asynchrone et renvoie un Future. En cas d'erreur, une sous-classe de SdkError est levée.

Méthodes disponibles:

getBasicPaymentProducts(PaymentContext context) 
  → Future<basicpaymentproducts> 

getPaymentProduct(int paymentProductId, PaymentContext context) 
  → Future<paymentproduct> 

getPaymentProductNetworks(int paymentProductId, PaymentContext context) 
  → Future<paymentproductnetworksresponse> 

getIinDetails(String partialCreditCardNumber, PaymentContext context) 
  → Future<iindetailsresponse> 

getSurchargeCalculation(AmountOfMoney amountOfMoney, CardSource cardSource) 
  → Future<surchargecalculationresponse> 

getCurrencyConversionQuote(AmountOfMoney amountOfMoney, CardSource cardSource) 
  → Future<currencyconversionresponse> 

getPublicKey() 
  → Future<publickeyresponse> 

encryptPaymentRequest(PaymentRequest request) 
  → Future<encryptedrequest> 

encryptTokenRequest(CreditCardTokenRequest request) 
  → Future<encryptedrequest> 

dispose() 
  → void  // releases HTTP client resources; call when the SDK is no longer needed

PaymentContext

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

class PaymentContext {
  AmountOfMoney amountOfMoney; // contains the total amount and the ISO 4217 currency code
  String countryCode; // ISO 3166-1 alpha-2 country code
  bool isRecurring; // Set `true` when payment is recurring. Default false.
  bool forceBasicFlow; // Set 'true' to force the basic flow. Default false.

  PaymentContext(
    this.amountOfMoney, this.countryCode, this.isRecurring, // Required unnamed constructor arguments
    { this.forceBasicFlow = false } // Named optional constructor argument
  );
}

BasicPaymentProducts

Cet objet contient les produits de paiement disponibles pour le paiement en cours. Utilisez la fonction session.getBasicPaymentProducts pour demander les données.

Vous recevez un objet BasicPaymentProducts, il contient la liste de tous les BasicPaymentProducts disponibles et les AccountOnFiles associés.

L'extrait de code ci-dessous décrit comment obtenir l'instance de BasicPaymentProducts.

try { 
  final basicPaymentProducts = await sdk.getBasicPaymentProducts(paymentContext); 
  // Display basicPaymentProducts.basicPaymentProducts & basicPaymentProducts.accountsOnFile to your customer 
} on SdkError catch (e) { 
  // Inform the customer that something went wrong while retrieving the available Payment Products 
}

BasicPaymentProduct

La SDK propose deux types d'objets pour afficher les informations relatives aux moyens de paiement :

• BasicPaymentProduct
• PaymentProduct

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

L’objet PaymentProduct contient des informations complémentaires sur chaque produit de paiement, notamment la structure des champs que le client doit renseigner. Cet objet est généralement utilisé pour créer un formulaire de saisie des données de paiement. Pour en savoir plus, consultez la section PaymentProduct.

L’exemple ci-dessous indique comment récupérer le nom d’affichage et les ressources visuelles du moyen de paiement Visa (id : 1).

BasicPaymentProduct? basicPaymentProduct = basicPaymentProducts.getBasicPaymentProductById(1); 

int? id = basicPaymentProduct?.id; 
String? label = basicPaymentProduct?.label; 
String? logoUrl = basicPaymentProduct?.logo;

AccountOnFile

AccountOnFile représente les informations du moyen de paiement enregistré par le client. 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 Server pour permettre au client d'utiliser un mode de paiement préalablement tokenisé.

Si le client souhaite utiliser un AccountOnFile existant, l'AccountOnFile doit être ajouté à la requête PaymentRequest.

Le code ci-dessous vous indique comment récupérer et afficher au client le libellé du compte enregistré et le logo du moyen de paiement associé.

// All available accounts on file across all payment products 
List<AccountOnFile> allAccountsOnFile = basicPaymentProducts.accountsOnFile; 

// All available accounts on file for a specific payment product 
BasicPaymentProduct? basicPaymentProduct = basicPaymentProducts.getBasicPaymentProductById(1); 
List<AccountOnFile> productAccountsOnFile = basicPaymentProduct?.accountsOnFile ?? []; 

// Get the specific account on file for the payment product by its id 
AccountOnFile? accountOnFile = basicPaymentProduct?.getAccountOnFile('identifier'); 

// Shows the masked value stored for a field, e.g. the obfuscated card number. 
// If the stored value for "cardNumber" is **** **** **** 7412, that is returned directly. 
String? maskedValue = accountOnFile?.getValue('cardNumber'); 

// Display label for the account on file, typically a masked card number 
String? displayLabel = accountOnFile?.label;

PaymentProduct

BasicPaymentProduct contient uniquement les informations essentielles permettant au client de distinguer les différents moyens de paiement. Toutefois, lorsqu’il sélectionne un moyen de paiement ou un compte enregistré (AccountOnFile), des informations supplémentaires sont nécessaires pour effectuer le paiement. Le système a notamment besoin de données obligatoires telles que le numéro de compte bancaire, le numéro de carte bancaire et la date d’expiration. L’objet BasicPaymentProduct ne contient pas les détails de ces champs.

Pour obtenir ces informations, utilisez l’objet PaymentProduct, qui contient une liste de champs (PaymentProductField) correspondant aux données requises pour effectuer le paiement.

L’exemple suivant montre comment récupérer un objet PaymentProduct à l’aide de l’instance OnlinePaymentSdk :

try { 
  final paymentProduct = await sdk.getPaymentProduct( 
    1, // id of the payment product you want to retrieve 
    paymentContext, 
  ); 
  // Display the fields to your customer 
} on SdkError catch (e) { 
  // Inform the customer that something went wrong while retrieving the Payment Product 
} 

PaymentProductField

Les instances de PaymentProductField représentent les différents champs du moyen de paiement (par exemple, le numéro de compte bancaire ou le numéro de carte de crédit). Chaque champ possède les propriétés suivantes :

• Un identifiant
• Un type
• Une définition des restrictions applicables à la valeur du champ
• Un mécanisme de validation intégré pour les valeurs saisies
• Des 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 "cvv" à partir d'un moyen de paiement. Il 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 masquées dans l'interface utilisateur.

PaymentProductField ccvField = paymentProduct.getPaymentProductFieldById("cvv");

bool isRequired = ccvField.dataRestrictions.isRequired; // state if value is required for this field
bool shouldObfuscate = ccvField.displayHints?.obfuscate; // state if field value should be obfuscated

PaymentRequest

Une fois que le client a sélectionné un moyen de paiement et que le système a récupéré une instance de PaymentProduct, une requête de paiement peut être créée. Vous devez utiliser la classe PaymentRequest pour regrouper toutes les valeurs fournies par le client.

PaymentRequest paymentRequest = PaymentRequest(
  paymentProduct: paymentProduct,
  tokenize: true, // Optional argument to tokenise the request - default is false
  accountOnFile: accountOnFile // Optional argument to set the accountOnFile to be used for the paymentRequest
);

Tokeniser la PaymentRequest

Une PaymentRequest dispose d'une propriété tokenize qui permet d'indiquer si les informations de paiement doivent être stockées pour de futurs paiements. L'extrait de code ci-dessous montre comment construire une requête de paiement lorsque vous souhaitez enregistrer ces informations.

PaymentRequest paymentRequest = PaymentRequest(
    paymentProduct: paymentProduct,
);
// you can set the request's tokenize property after having initialised the paymentRequest
paymentRequest.tokenize = true;

Si le client sélectionne un compte enregistré, vous devez fournir le compte enregistré et le moyen de paiement correspondant dans la requête de paiement. Vous pouvez récupérer les instances de AccountOnFile à partir des instances de BasicPaymentProduct et PaymentProduct.

// you can supply accountOnFile via the constructor
PaymentRequest paymentRequest = PaymentRequest(
  paymentProduct: paymentProduct,
  accountOnFile: accountOnFile
);

// or by accessing the request's accountOnFile property
paymentRequest.accountOnFile = 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 paymentRequest = PaymentRequest(
  paymentProduct: paymentProduct,
);
paymentRequest.setValue(
    "cardNumber", // field id
    "1245 1254 4575 45" // value
);
paymentRequest.setValue("cvv", "123");
paymentRequest.setValue("expiryDate", "12/25");

Les identifiants des champs, tels que "cardNumber" et "cvv", permettent de renseigner les valeurs correspondantes dans la requête de paiement. En règle générale, vous pouvez récupérer la liste des champs disponibles à partir de l’instance PaymentProduct.

Valider la PaymentRequest

Une fois que toutes les valeurs des champs ont été renseignées, vous pouvez valider la demande de paiement. Cette étape consiste à vérifier que les valeurs saisies respectent les règles de validation (DataRestrictions) définies pour chaque champ du PaymentRequest. Le résultat de la validation contient également la liste des éventuelles erreurs détectées.

Si aucune erreur n'est détectée, vous pouvez chiffrer la requête de paiement et l’envoyer à notre plateforme via votre serveur. En cas d’erreur, vous devez en informer le client afin qu'il puisse apporter les corrections nécessaires.

// Validate all fields in a Payment Request
List<validationerrormessage> errorMessages = await paymentRequest.validate();
// check if the payment request is valid
if (errorMessages.isEmpty) {
// payment request is valid
} else {
// payment request has errors
}

Les validations correspondent aux validateurs associés au PaymentProductField.

En cas d'erreur, la liste validationResult.errorMessages indique les champs concernés et les règles non respectées.

for (ValidationErrorMessage errorMessage in validationResult.errorMessages) { 
    // do something with the errorMessage, like displaying it to the user 
    // errorMessage.paymentProductFieldId — which field failed 
    // errorMessage.rule                  — which rule was violated 
} 

Chiffrer la PaymentRequest

La PaymentRequest ne peut être chiffrée que lorsque les conditions suivantes sont respectées :

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

Pour chiffrer la demande de paiement, utilisez sdk.encryptPaymentRequest. Une fois le chiffrement effectué, vous obtenez un objet EncryptedRequest qui contient les données du client chiffrées et ses métadonnées encodées.

try { 
  final encryptedRequest = await sdk.encryptPaymentRequest(paymentRequest); 
  // Forward encryptedRequest.encryptedCustomerInput to your server 
  // encryptedRequest.encodedClientMetaInfo is also available if needed 
} on SdkError catch (e) { 
  // Something went wrong while encrypting your payment request 
} 

Masking

Le SDK permet de gérer le masquage des champs PaymentProductField et PaymentRequestField. Elle permet de gérer l'affichage des valeurs des champs et d'appliquer ou de supprimer un masque sur une chaîne de caractères.

// apply mask to a raw value 
String? maskedValue = paymentProduct.getField('cardNumber')?.applyMask('4242424242424242'); // "4242 4242 4242 4242" 

// remove mask from a formatted value 
String unmaskedValue = paymentProduct.getField('cardNumber')?.removeMask('4242 4242 4242 4242') ?? ''; // "4242424242424242" 

// Get the masked value from a PaymentRequestField for display in your UI 
String? displayValue = paymentRequest.getField('cardNumber').getMaskedValue(); 

Fonctionnalités supplémentaires

Le SDK propose de nombreuses fonctionnalités pour vous permettre une intégration des paiements simplifiée et améliorer l’expérience de vos clients :

• Chiffrer les données sensibles
• Valider les données
• Appliquer la vérification IIN
• Intégrer les paiements natifs

Chiffrer les données sensibles

L'un des plus grands atouts du SDK est son outil de cryptage qui permet de sécuriser le transfert de données sensibles (c'est-à-dire les numéros de carte, la date d'expiration, le code CVC).

Le processus complet de cryptage/transfert se déroule comme suit :

Le SDK est conçu pour simplifier ce processus. Voici les étapes à suivre :

1. Utilisez sdk.encryptPaymentRequest pour chiffrer les données de paiement contenues dans le PaymentRequest.
2. Cette méthode renvoie un objet Future qui, une fois résolu, fournit un EncryptedRequest contenant les données du client chiffrées.
3. Récupérez les données chiffrées du client à partir de l'EncryptedRequest.
4. Transmettez ces données à votre serveur.
5. Depuis votre serveur, envoyez les données à notre plateforme via la requête CreatePayment, dans le champ encryptedCustomerInput.
6. Transmettez le résultat de la transaction à l'application cliente.

try { 
  final encryptedRequest = await sdk.encryptPaymentRequest(paymentRequest); 
  // Forward encryptedRequest.encryptedCustomerInput to your server 
} on SdkError catch (e) { 
  // Something went wrong while encrypting your payment request 
} 

Le SDK prend en charge toutes les étapes techniques du chiffrement :

• Récupération d’une clé publique via l'API client.
• Chiffrement des données.
• Encodage du résultat en BASE-64 dans une seule chaîne de caractères.

Vous devez seulement vous assurer que l'objet PaymentRequest contient toutes les informations saisies par l'utilisateur.

Valider les données

Chaque PaymentProductField est associé à des règles de validation, définies dans l’objet DataRestrictions. Ces règles précisent les contraintes applicables à chaque champ, notamment si celui-ci est obligatoire (propriété isRequired) et quelles valeurs sont acceptées.

Vous pouvez valider un champ individuellement ou valider l’ensemble du PaymentRequest.

En cas d'erreurs, le champ errorMessages du ValidationResult affichera une liste d'erreurs.

Le SDK propose 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 valeurs autorisées.
• IBAN : Vérifie la validité de l'IBAN fourni par le client.
• Length : Vérifie si la longueur de la valeur saisie respecte les limites minimales et maximales définies.
• Luhn : Vérifie le numéro à l’aide de l’algorithme de Luhn, notamment utilisé pour contrôler les numéros de carte.
• Range : Vérifie que la valeur se situe dans l’intervalle autorisé.
• Regex : Vérifie si la valeur saisie correspond à l'expression régulière.
• TermsAndConditions : Vérifie si le client a accepté les conditions générales.

Chaque validateur renvoie une erreur lorsque la valeur ne respecte pas les règles définies. Le message associé peut être traduit pour être affiché au client.

Appliquer la vérification IIN

Les six premiers chiffres d’un numéro de carte correspondent à l’Issuer Identification Number (IIN). Ils permettent d’identifier le moyen de paiement et le réseau associés à la carte.

Dès que le client saisit ces six chiffres, vous pouvez utiliser sdk.getIinDetails pour récupérer les informations correspondantes et vérifier si la carte peut être acceptée.

Vous pouvez utiliser une instance de OnlinePaymentSdk pour vérifier quel produit de paiement est associé à un IIN via la fonction sdk.getIinDetails. Le résultat de cette vérification est une instance de IinDetailsResponse qui contient les éléments suivants :

• status : indique le résultat de la vérification.
• paymentProductId : identifie le produit de paiement associé à l’IIN.

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

L'IinDetailsResponse possède une propriété status. Elle utilise l'énumération IinStatus qui peut prendre les valeurs suivantes :

• SUPPORTED : l'IIN est associé à un moyen de paiement pris en charge par notre plateforme.
• UNSUPPORTED : l'IIN n'est pas reconnu par notre plateforme.
• UNKNOWN : le résultat de la vérification n’a pas pu être déterminé.
• NOT_ENOUGH_DIGITS : moins de six chiffres ont été saisis. La vérification ne peut donc pas être effectuée.
• EXISTING_BUT_NOT_ALLOWED : l'IIN fourni est reconnu, mais le moyen de paiement correspondant n'est pas autorisé pour le paiement ou le commerçant concerné.

try { 
  final iinDetails = await sdk.getIinDetails('123456', paymentContext); 

  if (iinDetails.status == IinStatus.supported) { 
    // iinDetails.paymentProductId — use to load the matching PaymentProduct 
  } 
} on SdkError catch (e) { 
  // Handle error while retrieving IIN details 
} 

Certaines cartes sont co-badgées et peuvent être traitées comme une carte locale ou une carte internationale. Si votre configuration ne permet pas de traiter la marque locale, celle-ci ne sera pas renvoyée par l’API.

Lorsque plusieurs marques de carte sont disponibles, vous pouvez proposer au client de choisir celle avec laquelle il souhaite payer :

if (iinDetails.coBrands.isNotEmpty) { 
  // Let the customer pick a brand from iinDetails.coBrands 
} 

Intégrer les paiements natifs

Notre système prend en charge les paiements natifs (ou paiements intégrés) pour les appareils mobiles, y compris Google Pay pour Android et Apple Pay pour iOS.

Pour les paiements natifs, le SDK vérifie automatiquement la compatibilité de l'appareil et filtre les moyens de paiement non pris en charge.

Pour les appareils Android, le système doit utiliser Android 6.0 (Marshmallow) ou une version ultérieure. Le SDK utilise PaymentClient pour effectuer une vérification IsReadyToPayRequest et déterminer si l’appareil peut effectuer un paiement avec Google Pay.

Cette vérification est automatique, le SDK filtre les produits de paiement qui ne sont pas pris en charge.

Pour les appareils iOS, le système doit répondre au critère de version minimale (15.6). Le SDK utilise PKPaymentAuthorizationViewController pour vérifier si la transaction est réalisable. Si l'appareil ne répond pas aux conditions, ce moyen de paiement n'est pas proposé au client.