SDK Android

Le SDK Android vous aide à intégrer l'API Client dans votre application. Il offre :

• Des encapsulations pratiques pour les réponses
• Une gestion du chiffrement des données sensibles de la requête paiement
• Une mise en cache des logos et des images des méthodes de paiement
• Un formatage des données de paiement telles que les numéros de carte et les dates d'expiration
• Une validation des données saisies
• Une mécanique pour déterminer à quel émetteur un numéro de carte est associé

Notre application exemple simule l'interface utilisateur pour l'ensemble du flux de paiement. Vous trouverez le code source du SDK et de l'application exemple sur GitHub, y compris les instructions d'installation.

Une fois que vous êtes prêt, lisez les chapitres suivants sur la préparation et l'utilisation du SDK.

Pour créer des paiements, vous devez d'abord intégrer le SDK à votre projet. Toutes les versions du SDK sont disponibles publiquement dans notre dépôt. Pour simplifier leur utilisation, nous avons préparé un package ci-dessous pour une intégration rapide.

Gradle

Ajoutez une dépendance au SDK dans votre fichier build.gradle, où x.y.z est le numéro de version :

dependencies {
    // other dependencies
    implementation 'com.worldline-solutions:sdk-client-android:x.y.z'
}

Après l'intégration réussie du SDK à votre projet, vous pouvez passer au processus d'intégration avec l'ensemble du système de paiement. Le processus complet de paiement comprend les étapes suivantes :

1. Initialisation des objets Session et PaymentContext
2. Réception des méthodes de paiement possibles
3. Réception 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. Initialisez les objets Session et PaymentContext

Tout d'abord, vous devez créer un objet Session permettant la communication entre l'API Serveur et votre application cliente. Votre application cliente doit disposer de son propre serveur, qui agit comme un intermédiaire entre notre API Client et notre API Serveur.

Étant donné que vos clients initient le paiement dans votre application cliente, votre application cliente doit demander à l'API Serveur de créer une session. Cette requête de création de session se fait via la méthode Créer une Session du SDK.

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

{
    "assetUrl": "https://assets.test.cdn.v-psp.com/s2s/515c2c0bd13d5dd4bd42",
    "clientApiUrl": "https://payment.preprod.ca.cawl-solutions.fr/",
    "clientSessionId": "68a4b0b183a34016b4b694b97938f75b",
    "customerId": "cf7d7aafd42e4a1cb9e4b0624a5041b1",
    "invalidTokens": []
}

Transmettez maintenant assetUrl, clientApiUrl, clientSessionId et customerId à votre application cliente. Une fois que l'application cliente reçoit la réponse de l'API Serveur avec les informations sur la session, créez un objet Session local du côté de votre application cliente.

Ensuite, créez un objet PaymentContext. Celui-ci contient les informations sur le paiement, la devise, le pays, le montant, etc. Vous utiliserez les objets PaymentContext et Session tout au long du processus de paiement.

2. Recevoir les méthodes de paiement possibles

La prochaine étape consiste à obtenir et afficher les méthodes de paiement possibles. Pour ce faire, utilisez les objets Session et PaymentContext précédemment créés pour invoquer la méthode GetBasicPaymentItems qui fait un appel GetPaymentProducts à notre API Serveur.

Consultez l'exemple de code montrant comment initialiser une instance de la classe PaymentContext et l'utiliser pour obtenir la liste des BasicPaymentItems avec l'objet Session.

Long amountValue = 10.0;
CurrencyCode currencyCode = CurrencyCode.EUR;
AmountOfMoney amountOfMoney = new AmountOfMoney(amountValue, currencyCode);
CountryCode countryCode  = CountryCode.NL;
Boolean isRecurring  = false;

// Création du contexte de paiement
PaymentContext paymentContext = new PaymentContext(amountOfMoney, countryCode, isRecurring);

OnBasicPaymentItemsCallCompleteListener listener = new OnBasicPaymentItemsCallCompleteListener() {
    @Override
    public void onBasicPaymentItemsCallComplete(BasicPaymentItems basicPaymentItems) {
        if (basicPaymentItems == null) {
            // Indiquez qu'une erreur est survenue.
        } else {
            // Permettez à l'utilsateur de sélectionner une méthode de paiement et un compte enregistré depuis les données de l'objet paymentProducts.
        }
    }
};

// Récuperez le contexte Android de votre application pour envoyer dans la requête de paiement les informations de l'appareil utilisé par l'utilisateur.
// Ces information seront utilisées pour déterminer l'éligibilité de certaines méthodes de paiement.
Context androidContext = getApplicationContext();

// Parcourez la liste des méthodes de paiement possibles.
session.getBasicPaymentItems(androidContext, paymentContext, listener, false);

3. Recevoir et afficher les détails des méthodes de paiement

Les méthodes de paiement sont représentées par des instances de l'objet BasicPaymentProduct. Votre application peut utiliser ces instances pour afficher un écran qui liste toutes les méthodes de paiement possibles. Utilisez notre application exemple comme base pour votre propre implémentation.

Pour certains moyens de paiement, les clients peuvent indiquer qu'ils souhaitent que notre plateforme stocke leurs identifiants pour les paiements Card On File. Nous faisons référence aux données stockées comme un compte enregistré ou un token. Vous pouvez réutiliser ce compte enregistré / tokenpour les paiements ultérieurs si vos clients choisissent la même méthode de paiement.

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

En fonction de la méthode choisie par le client, vous devez envisager des cas de flux de données différents :

Si l'utilisateur a choisi une forme native de paiement, vous devez utiliser le SDK du fournisseur de paiement et gérer la réponse uniquement à la dernière étape pour informer l'utilisateur de l'état du paiement. Lisez-en davantage sur les paiements natifs dans le chapitre dédié.

Pour les paiements avec un fournisseur de paiement tiers, vous recevez les données avec l'adresse de redirection dans les propriétés de paiement. Redirigez vos clients dans leur navigateur vers le portail de paiement tiers pour poursuivre le processus de paiement. Après le paiement réussi, votre application doit gérer la redirection vers l'application Client.

Le processus de paiement standard est un paiement par carte. Une fois que vos clients ont sélectionné un élément de paiement ou account on file (compte enregistré), le SDK Client peut demander les informations nécessaires que vos clients doivent fournir pour le paiement.

Un objet représentant la méthode de paiement BasicPaymentItem fournit une liste des champs que votre application doit afficher, y compris les indices et les règles de validation. Si vos clients sélectionnent un account on file (compte enregistré), les informations déjà disponibles peuvent être préremplies dans les champs de saisie au lieu de les demander à vos clients. Les données préremplies au nom du client sont conformes aux réglementations applicables. Selon le cas d'utilisation individuel, vos clients pourraient encore devoir fournir certaines données (c'est-à-dire le CVC).

4. Valider les données fournies

Maintenant, votre application doit valider les données que vos clients saisissent dans l'interface de votre application. Pour ce faire, utilisez le composant de validation des données. L'interface de saisie de données doit être entièrement transparente et compréhensible pour vos clients. Nous recommandons d'utiliser des info-bulles, qui possèdent des champs individuels ou affichent des erreurs de validation appropriées.

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 possède une propriété tokenize utilisée pour indiquer si l'application doit stocker les identifiants du client pour les paiements Card On File.
Utilisez l'exemple de code suivant pour des demandes de paiement sans comptes enregistrés :

PaymentRequest paymentRequest = new PaymentRequest();
paymentRequest.setPaymentProduct(selectedPaymentProduct);
paymentRequest.setTokenize(false);

Vous pouvez également adapter l'exemple de code en fournissant à la fois le compte enregistré et le moyen de paiement correspondant :

paymentRequest.setAccountOnFile(selectedAccountOnFile);

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

paymentRequest.setValue("cardNumber", "1234567890");
paymentRequest.setValue("cvv", "123");

Vous pouvez maintenant valider la requête de paiement. En résultat, une liste d'erreurs est disponible. Pour toute erreur de validation, vous devez fournir un retour au client. Pour plus d'informations, lisez le chapitre dédié.

List validationResult = paymentRequest.validate();
if (validationResult.size() > 0) {
    // Notify the customer that some fields contain invalid data.
} else {
    // The payment request is valid, and can be encrypted and sent to
    // the platform via your server.
}

Après la validation de la PaymentRequest, chiffrez la requête et envoyez-la à votre application Serveur. Consultez l'exemple de code montrant comment utiliser une instance de Session pour chiffrer une requête :

// Get the Android application context
Context androidContext = getApplicationContext();

OnPaymentRequestPreparedListener listener = new OnPaymentRequestPreparedListener() {

    @Override
    public void onPaymentRequestPrepared(PreparedPaymentRequest preparedPaymentRequest) {
        if (preparedPaymentRequest == null ||
            preparedPaymentRequest.getEncryptedFields() == null) {
            // Indicate that an error has occurred.
        } else {
            // Submit the information contained in the encrypted
            // payment request represented by preparedPaymentRequest
            // to our platform via your server.
        }
    }
};

// Encrypts paymentRequest
session.preparePaymentRequest(paymentRequest, androidContext, listener);

6. Finaliser la transaction

Après avoir reçu les données chiffrées, transmettez-les à votre application serveur pour finaliser le paiement en envoyant une demande CreatePayment.

Enfin, vous devez transmettre l'information à l'application Client pour afficher le résultat de la transaction à vos clients.

Objets SDK

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

• C2sCommunicator
• Session
  • Métadonnées de l'appareil
• PaymentContext
  • AmountOfMoney
  • Clé du cache de l'élément de paiement
• BasicPaymentItem interface
  • moyen de paiement de base
  • moyen de paiement
  • Champ du moyen de paiement
• AccountOnFile
• DisplayHints
  • Info-bulles
  • Élément de formulaire
• Requête de paiement
• Rquête de paiement préparée
• Réponses

C2sCommunicator

C'est le principal service de communication. Vous ne l'utilisez pas directement, mais seulement à travers l'objet Session. Il crée une connexion sécurisée avec notre API Client.

Session

Session est le composant principal du SDK. L'objet :

• Encapsule C2sCommunicator en implémentant toute la logique de communication avec notre API Client.
• Crée les requêtes API appropriées.
• Est responsable de la conversion des réponses de l'API en objets natifs simples.
• Dispose d'un chiffrement intégré des objets natifs décrivant la requête de paiement d'une manière que notre API Serveur peut traiter.

Assurez-vous d'initialiser correctement Session pour commencer la communication avec notre API Client. Les propriétés obligatoires sont :

• client session identifier
• customer identifier
• url-api-client
• url-base-ressource

Vous obtiendrez ces paramètres en utilisant CreateSession depuis le point d'accès API Serveur. Référez-vous aux SDKs Serveur et à l'API Serveur pour en savoir plus.

La classe Session peut être initialisée via son constructeur :

String clientSessionId = "1234";
String customerId = "5678";
String clientApiUrl = "https://clientapi.com";
String assetBaseUrl = "https://asset.com";
boolean environmentIsProduction = false;
String applicationIdentifier = "Example Application/v1";

Session session = new Session(
                                                                    clientSessionId,
                                                                    customerId,
                                                                    clientApiUrl,
                                                                    assetBaseUrl,
                                                                    environmentIsProduction,
                                                                    applicationIdentifier);

Assurez-vous de déterminer si l'application fonctionne en production et spécifiez l'identifiant de l'application lors de l'initialisation. Un paramètre supplémentaire spécifie l'adresse IP. L'adresse IP et l'identifiant de l'application sont utilisés dans les Métadonnées de l'appareil lors de la communication avec l'API Client.

Propriétés

string clientSessionId : L'identifiant de la session créée. string customerId : La session est basée sur le client sous la forme de customerId. Toutes les APIs Clients utilisent ce customerId dans l'URI pour identifier le client. string clientApiUrl : L'URL de base spécifique au centre de données pour les requêtes Clients. Passez cette valeur au SDK Client pour vous assurer que le logiciel Client se connecte au bon centre de données. string assetBaseUrl : L'URL de base spécifique au centre de données pour les ressources. string applicationIdentifier : L'identifiant de l'application.

Métadonnées de l'appareil

Les Métadonnées de l'appareil incluent les données suivantes :

Propriétés

platformIdentifier : Contient la version et le type du système. appIdentifier : L'identifiant de l'application fourni par l'utilisateur, sinon défini sur "inconnu". sdkIdentifier : La version du SDK Client. sdkCreator : Le nom de l'éditeur du SDK Client. screensize : La taille de l'écran de l'appareil. deviceBrand : Le fabricant de l'appareil. deviceType : Le modèle de l'appareil. ipAddress : Le paramètre optionnel avec l'adresse IP publique de l'appareil.

PaymentContext

Les instances de la classe PaymentContext contiennent les informations de paiement les plus pertinentes telles que :

• amountOfMoney
• currency
• countryCode
• isRecurring – une indication de si le paiement est un paiement unique ou un Card On File.

Cet objet :

• Participe aux étapes suivantes de la transaction.
• Doit rester dans la même forme après initialisation – vous devez utiliser le même objet tout au long du processus de transaction.

AmountOfMoney

Ce modèle contient des informations sur le montant du paiement. Il se compose de amount exprimé en type long et de la devise donnée sous currencyCode.

Notez que le montant inclut les fractions de devise. L'objet ci-dessous équivaut à 1 EUR.

"amountOfMoney": {
            "amount": 100,
    "currencyCode": "EUR"
        },

Clé du cache de l'élément de paiement

Un modèle supplémentaire utilisé dans le mécanisme de cache. Au cours d'une session unique, il enregistre les informations sur une tentative de paiement avec un paiement donné. En cas de tentative répétée, le mécanisme n'effectue pas une autre requête, mais utilise le cache à la place.

Interface BasicPaymentItem

L'interface principale de BasicPaymentItem est principalement responsable de l'identification et de la présentation visuelle simple de l'élément de paiement. Elle comprend :

• Un identifiant Id.
• Une liste DisplayHints qui contient le texte visuel publicitaire (par exemple, un logo ou la photo de la carte avec le CVC marqué).
• Une caractéristique distinctive de la méthode de paiement (par exemple, un logo).
• Des informations sur les instances d'AccountOnFile associées.

Moyen de paiement de base

Le modèle principal d'un moyen de paiement. Il contient une liste de méthodes de paiement disponibles. Le client peut choisir une méthode parmi cette liste. Chaque instance contient :

• Un identifiant.
• Un champ indiquant la méthode de paiement de ce produit.
• Deux champs indiquant le montant minimal et maximal requis pour payer avec ce moyen de paiement.
• Un champ indiquant si notre plateforme peut stocker les données de paiement comme un compte en dossier pour les paiements ultérieurs.
• Un champ indiquant si la méthode permet Card On File.
• Un champ indiquant si la méthode de paiement utilise une redirection vers un tiers.
• Une liste de comptes déjà enregistrés pour ce moyen de paiement.
• Affiche des indices pour rendre le BasicPaymentProduct adéquatement, contenant :
  • Un index indiquant à quelle position le moyen de paiement appartient dans une liste de moyens de paiement
  • Un libellé
  • Un logo

Moyen de paiement

Il étend la classe BasicPaymentProduct et implémente l'interface PaymentItem qui complète le modèle avec la liste PaymentProductField. Cependant, une fois que le client sélectionne un élément de paiement ou un compte en dossier, il doit fournir des informations supplémentaires (c'est-à-dire une adresse, un numéro de compte bancaire, un numéro de carte de crédit ou une date d'expiration) pour traiter le paiement réel.

Chaque élément de paiement peut avoir plusieurs champs que le client doit compléter pour traiter les paiements. Les instances de PaymentProductField représentent des informations sur les champs des éléments de paiement. Utilisez-le pour récupérer des instances de PaymentProduct :

String paymentProductId = "xyz";

// Get the Android application context
Context androidContext = getApplicationContext();

// Create the PaymentContext
PaymentContext paymentContext = new PaymentContext(amountOfMoney, countryCode, isRecurring);

PaymentProductCallListener paymentProductCallListener  = new PaymentProductCallListener() {

	@Override public void onPaymentProductCallComplete(PaymentProduct paymentProduct) {
		// Create a payment request using the payment product represented by paymentProduct.
    }
	
	@Override public void onPaymentProductCallError(ErrorResponse error) {
		// Indicate that an error has occurred.
    }
};

// Get selected PaymentProduct
session.getPaymentProduct(androidContext, paymentProductId, paymentContext, paymentProductCallListener);


BasicPaymentItemsCallListener basicPaymentItemsCallListener = new BasicPaymentItemsCallListener() {

    @Override public void onBasicPaymentItemsCallComplete(BasicPaymentItems basicPaymentItems) {
    }
	
	@Override public void onBasicPaymentItemsCallError(ErrorResponse error) {
    }
};

// Get all available BasicPaymentItems for paymentContext
session.getBasicPaymentProducts(androidContext, paymentContext, basicPaymentItemsCallListener);

Champ du moyen de paiement

Il représente les champs des éléments de paiement. Chaque champ a :

• Un identifiant
• Un type
• Une définition des restrictions qui s'appliquent à la valeur du champ.
• Des informations sur la manière de présenter le champ au client dans l'interface utilisateur.

Le modèle dispose d'une méthode de validation de données intégrée qui permet de déterminer si une valeur donnée est valide pour le champ. La méthode est basée sur DataRestrictions. Elle retourne ValidationErrorMessages et des méthodes pour masquer et démasquer la valeur à l'aide du StringFormatter intégré.

L'extrait de code ci-dessous montre comment récupérer le champ avec l'identifiant "cvv" d'un moyen de paiement. Dans ce processus, nous :

• Examinons les restrictions de données du champ pour voir si ce champ est requis ou optionnel.
• Examinons les indices d'affichage du champ pour voir si les valeurs fournies par un client doivent être obfusquées dans une interface utilisateur.
• Validons la valeur "123".
• Examinons le nombre d'erreurs de validation pour voir si la valeur fournie est valide.

PaymentProductField field = paymentProduct.getPaymentProductFieldById("cvv");
Boolean isRequired = field.getDataRestrictions().isRequired();
Boolean obfuscate  = field.displayHints.isObfuscate();

List errorMessageIds = field.validateValue("123");
Boolean validValue = errorMessageIds.isEmpty();

Compte enregistré

AccountOnFile représente des informations sur un compte enregistré pour un certain moyen de paiement. Il contient :

• Un identifiant pour le compte enregistré.
• Un identifiant pour le moyen de paiement correspondant.
• Une collection de paires clé-valeur stockées en tant que partie du compte enregistré.
• Des indices d'affichage qui contiennent des informations sur la façon d'afficher le compte enregistré.
• Une méthode qui produit une étiquette décrivant le compte enregistré.

Récupérez des instances de AccountOnFile en tant qu'instances de BasicPaymentProduct comme suit :

private AccountOnFile GetSelectedAccountOnFile(IBasicPaymentItem paymentItem, string selectedAccountOnFileId)
{
	AccountOnFile accountOnFile = paymentItem.getAccountOnFileById(selectedAccountOnFileId);
	return accountOnFile;
}

Indications d'affichage

DisplayHints sont des objets contenant des indices. Il existe trois types de DisplayHints :

• DisplayHintsPaymentItem : Les informations les plus importantes sur PaymentItem, c'est-à-dire un nom et un logo. Une propriété supplémentaire est displayOrder qui indique l'ordre d'affichage approprié selon l'indice de classement en relation avec d'autres PaymentItems utilisés par BasicPaymentItems et BasicPaymentProducts. Utilisez-les pour afficher la liste de sélection de PaymentItem.
• DisplayHintsAccountOnFile : La liste contenant les paires clé-valeur ProductFields et le masque correspondant pour appliquer le masque (par exemple, des astérisques) à la valeur correspondante de AccountOnFile.
• DisplayHintsProductFields : Définit la manière d'afficher les ProductFields. En plus du nom et de l'espace réservé, il contient PreferredInputType, sur la base duquel vous pouvez choisir :
  • Le type de clavier approprié que vous devriez utiliser.
  • Si l'élément doit toujours être affiché en tant que AlwaysShow.
  • Si la valeur Obfuscate doit être obfusquée, ainsi que la valeur de Mask – une référence à la ToolTip et à FormElement qui y sont affectées.

Info-bulles

ToolTips facilitent la saisie des données. Vous pouvez ajouter un objet ToolTip dans les indications d'affichage pour les ProductFields. Il peut contenir un texte d'explication ou un graphique, c'est-à-dire une photo d'une carte avec un CVV obfusqué.

Élément de formulaire

Une description simplifiée de l'élément visuel qui vous indique comment l'utiliser correctement comme texte, liste, devise, date ou booléen.

Remande de paiement

Cette classe encapsule la relation entre le PaymentProduct sélectionné, AccountOnFile et les valeurs saisies. Elle permet d'extraire facilement des valeurs masquées ou non masquées. Elle contient une méthode de validation des données saisies. Consultez le chapitre dédié au chiffrement pour plus d'informations.

Requête de paiement préparée

L'instance de la classe PreparePaymentRequest est le résultat du chiffrement d'une requête à l'aide d'une instance de Session. Elle possède deux propriétés, encryptedFields et encodedClientMetaInfo – les chaînes qui doivent être envoyées à notre plateforme. Consultez le chapitre dédié au chiffrement pour plus d'informations.

Réponses

• ApiResponse : Chaque requête est encapsulée dans une réponse d'API contenant des données génériques. En cas d'erreur, dans le champ ErrorResponse supplémentaire, vous pouvez trouver ApiErrorCode et Message décrivant l'erreur.
• PublicKeyResponse : API Client que vous utilisez pour récupérer une clé publique spécifique à une transaction de notre serveur. Utilisez-la pour chiffrer les données sensibles, c'est-à-dire les détails de la carte. Cet objet renvoie automatiquement une clé publique déjà déchiffrée de notre API.

Fonctionnalités supplémentaires

Le SDK a beaucoup plus à offrir. Jetez un coup d'œ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
• Implémenter les paiements natifs
• Utiliser la logging
• Utiliser l'application de démonstration

Chiffrer les données sensibles

L'un des plus grands atouts du SDK est son outil de chiffrement. Il offre une grande 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 chiffrement/transfert se déroule comme suit :

Vous n'avez pas besoin de faire toutes ces étapes vous-même. Grâce au SDK, vos tâches sont les suivantes :

1. Lorsque vos clients complètent toutes les entrées de paiement requises et confirment le paiement, créez l'objet PaymentRequest, assignez-lui le PaymentProduct sélectionné et remplissez-le avec les valeurs saisies.
2. Validez le PaymentRequest créé en utilisant la méthode Validate.
3. S'il n'y a pas d'erreurs de validation, utilisez un objet Session et appelez la méthode PreparePaymentRequest. Elle effectuera l'ensemble du processus de chiffrement pour vous et retournera les données chiffrées.
4. Envoyez les données chiffrées à votre serveur.
5. Votre serveur envoie les données chiffrées en utilisant la méthode CreatePayment dans le champ du corps de la requête – encryptedCustomerInput.
6. Vous envoyez le résultat de la transaction à l'application cliente.

L'algorithme utilisé est RSA-OAEP avec un encodage A256CBC-HS512. Il est possible de mettre en œuvre votre propre chiffrement, mais vous passerez à côté de la fonctionnalité d’assistance qu’offre le chiffreur. Nous ne garantissons pas le bon fonctionnement résultant de données mal chiffrées. Notez que nous ne sommes pas en mesure de vérifier les données chiffrées pour détecter des erreurs. Par conséquent, vous devez vous assurer que toutes les opérations précédentes ont été effectuées correctement.

Validation des données

Chaque PaymentProductField possède des DataRestrictions appropriées. L'objet DataRestrictions contient des informations sur tous les champs obligatoires et vérifie si les valeurs saisies répondent à la condition de validité. En plus d'une liste d'abstractions de validateurs, il possède aussi une propriété isRequired qui indique si les restrictions données sont obligatoires ou non.

Vous pouvez valider une saisie particulière aussi facilement que par la validation d'un PaymentRequest. En cas d'erreurs, le champ Errors affichera une liste d'erreurs.

Il contient les validateurs suivants :

• Date d'expiration : 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 la limite de vingt-cinq ans à l'avance.
• Adresse e-mail : Vérifie le format de l'adresse e-mail fournie par le client.
• Liste fixe : Vérifie si la valeur saisie figure dans la liste des possibilités.
• IBAN : Valide l'IBAN fourni par le client.
• Longueur : Vérifie si la valeur saisie est plus longue que la valeur minimale et si elle n'est pas plus longue que la valeur maximale.
• Luhn : La formule de somme de contrôle utilisée pour valider divers numéros d'identification, tels que les numéros de carte de crédit.
• Plage : 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 que la valeur saisie correspond à l'expression régulière.
• Termes et conditions : 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 huit premiers chiffres d'un numéro de carte de paiement sont connus sous le nom de Numéro d'Identification de l'Émetteur (IIN).

Vous pouvez utiliser une instance de Session pour vérifier quels moyens de paiement sont associés à un IIN. La vérification est effectuée de manière asynchrone, par conséquent le résultat de la vérification n'est pas disponible immédiatement. Le résultat est une instance de IinDetailsResponse. Cette classe possède les propriétés suivantes :

• paymentProductId : Le moyen de paiement principal associé à cet IIN.
• countryCode : Le code du pays du moyen de paiement principal associé à cet IIN.
• status : Type de IinStatus qui indique le résultat de la vérification IIN. Les statuts possibles sont :
  • SUPPORTED : L'IIN est associé à un moyen de paiement disponible sur notre plateforme.
  • UNKNOWN : L'IIN n'est pas reconnu.
  • NOT_ENOUGH_DIGITS : Moins de six chiffres ont été fournis.
  • EXISTING_BUT_NOT_ALLOWED : L'IIN est reconnu, mais il ne peut pas être utilisé pour le paiement actuel.
• isAllowedInContext : Indique s'il est autorisé d'effectuer un paiement avec le moyen de paiement principal basé sur le PaymentContext
• coBrands : Une liste d'instances de IinDetail, qui représente les co-marques pour l'IIN actuel.

Il est possible qu'une seule carte de crédit ait plusieurs marques associées à elle et soit ainsi 'co-marquée'. Les détails du premier moyen de paiement que vos clients peuvent utiliser pour effectuer le paiement dans ce contexte sont toujours stockés dans les champs de niveau supérieur du IinDetailsResponse. Si un co-branding s'applique, la liste des instances de IinDetail contient toutes les marques associées à la carte, y compris le moyen de paiementt qui est stocké dans les champs de niveau supérieur. Utilisez cette liste pour permettre aux clients de choisir leur marque préférée. S'il n'y a qu'un seul moyen de paiement associé à la carte de crédit, la liste des détails de l'IIN est vide.

// The payment item identifier that the customer has selected to pay with.
// The identifier can be of a specific payment product or it can be an
// identifier of a payment product group.
String paymentItemIdentifier;

public void doIinLookup() {

    String unmasked = paymentRequest.getUnmaskedValue("cardNumber", "1234 5678");

    // Get the Android application context
    Context androidContext = getApplicationContext();

    OnIinLookupCompleteListener listener = new OnIinLookupCompleteListener() {

        @Override
        public void onIinLookupComplete(IinDetailsResponse response) {
            if (response.getStatus() == IinStatus.SUPPORTED) {
                if (response.getCoBrands() != null) {
                    if (!isSelectedPaymentProductInCobrands(response.getCoBrands()) {
                        switchPaymentProduct(response);
                    }
                    // EU legislation requires that, in the case of
                    // a card with multiple brands, a customer can
                    // choose what brand he wants to do the payment with.
                    showCoBrandNotification();
                } else if (!response.getPaymentProductId().equals(paymentItemIdentifier)) {
                    switchPaymentProduct(response);
                }
            } else {
                // Handle other Status codes.
            }
        }
    };

    session.getIinDetails(context, unmasked, listener);
}

public boolean isSelectedPaymentProductInCobrands(List coBrands) {
    for (IinDetail iinDetail: coBrands) {
        if (iinDetail.getPaymentProductId().equals(paymentItemIdentifier)) {
                return true;
        }
    }
    return false;
}

public void switchPaymentProduct(IinDetailsResponse response) {
    if (response.isAllowedInContext()) {
        // Switch to the payment product that actually is in the top level
        // Iin Details Response. This can be done by doing a lookup with
        // the payment product id that is in the response.
        paymentItemIdentifier = response.getPaymentProductId();
    } else {
        // Provide the customer with an error message that shows that the
        // credit card number he is entering can currently not be payed with.
    }
}

public void showCoBrandNotification() {
    // Show the customer that he may choose another brand to pay with.

Implémenter les paiements natifs

Par paiements natifs pour les appareils mobiles, nous entendons Google Pay pour Android et Apple Pay pour les appareils iOS. Notre système prend en charge les paiements natifs, mais cela ne signifie pas qu'ils seront disponibles sur tous les appareils.

Si l'utilisateur reçoit un moyen de paiement responsable du paiement natif, le SDK vérifie automatiquement si l'appareil est capable de gérer le paiement. Si l'appareil ne répond pas aux conditions, ce paiement est masqué. Grâce à cette procédure, vous, en tant qu'utilisateur de notre produit, n'avez pas à vous soucier de vérifier la validité de l'opération.

En utilisant PaymentClient avec l'API Google sur les appareils Android, vous effectuez IsReadyToPayRequest et retournez une valeur en fonction du résultat.

Utiliser la logging

Dans certains cas, vous souhaiterez peut-être activer la logging des requêtes et des réponses qui constituent la communication avec notre plateforme.

Android utilise actuellement Log et la logging est toujours activée puisque le drapeau est défini dans Constants. L'utilisateur ne peut pas désactiver la logging dans

/** Disable/Enable logging of all requests and responses made to the Online Payments Client API **/
public final static Boolean ENABLE_REQUEST_LOGGING = true;

Utiliser l'application de démonstration

Les applications exemples illustrent les possibilités du SDK et les services offerts par notre plateforme. Vous pouvez trouver le code source pour les exemples en Kotlin et en Java sur GitHub. L'application exemple en Kotlin fournit une implémentation du SDK à la fois en Jetpack Compose et en XML traditionnel. Vous pouvez utiliser ce code comme base pour votre application. Les applications exemples se composent de quatre écrans :

• Le premier écran requête les informations nécessaires pour communiquer avec l'API Client et récupérer une liste de moyens de paiement. Cet écran ne devrait pas faire partie d'une application réelle dans le magasin d'applications. Nous le fournissons pour illustrer les informations nécessaires à l'initialisation d'une instance de Session
• Le deuxième écran est un écran de sélection de moyen de paiement généré dynamiquement. Basé sur les informations fournies dans le premier écran, l'application affiche une liste de moyens de paiement disponibles et de accounts on file (comptes enregistrés). Cet écran ou un écran similaire ferait typiquement partie d'une application réelle. Voir plus de détails ci-dessous.
• Après avoir sélectionné un moyen de paiement, l'application affiche le troisième écran pour obtenir les données du client. Le client ne peut confirmer le paiement qu'une fois que le SDK a validé les informations saisies. Cet écran ou un écran similaire ferait également partie d'une application réelle. Voir plus de détails ci-dessous.
• Le quatrième écran indique que le SDK a traité avec succès le paiement initié. Cet écran ne devrait pas faire partie d'une application réelle.

Écran de sélection de moyen de paiement

L'écran de sélection de moyen de paiement fournit un exemple pour l'un des deux écrans qui apparaîtront dans la plupart des applications utilisant le SDK. Il montre une liste d'éléments de paiement disponibles et de accounts on file (comptes enregistrés). Pour chaque élément de paiement / account on file (compte enregistré), il affiche un nom localisé/une courte description des informations stockées. Si un logo est disponible pour un élément de paiement, l'écran l'affichera.

L'écran contient une partie d'une liste d'éléments de paiement disponibles, générée à partir des informations contenues dans une instance de PaymentItems.

Écran de formulaire de saisie de moyen de paiement

Cet écran est un autre exemple d'écran qui apparaîtra dans la plupart des applications utilisant le SDK. L'application l'affiche après la sélection d'un élément de paiement ou d'un account on file (compte enregistré). Si le client a sélectionné un account on file (compte enregistré), certaines des valeurs requises seront préremplies et ne pourront pas être modifiées. Le formulaire de saisie est généré à partir d'une instance de PaymentProduct ou PaymentProductGroup.

Validation du formulaire

L'application exemple utilise le SDK pour valider les données saisies par le client lorsqu'il appuie sur le bouton Payer. Si les données fournies sont invalides, des messages d'erreur s'affichent sous les valeurs invalides.

Vérification de l'IIN

L'application exemple implémente également l'utilisation de la vérification IIN. Pour chaque méthode de paiement basée sur une carte, une vérification IIN est effectuée une fois que le client a saisi six chiffres ou plus dans le champ pour le numéro de carte. Si l'IIN correspond à la méthode de paiement sélectionné, le logo de la marque apparaît sur le côté droit du champ pour le numéro de carte. Si l'IIN correspond à une autre méthode de paiement que celle sélectionnée, les champs de saisie sont automatiquement remplacés par les champs de saisie de la méthode de paiement adéquate. Vous pouvez utiliser la vérification IIN pour passer d'un PaymentProductGroup à un PaymentProduct spécifique.

La capture d'écran montre comment afficher les marques qui peuvent être associées à une certaine carte. Le logo et le nom des marques sont récupérés en effectuant des appels spécifiques.