SDK Android

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

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

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

Pourquoi utiliser le SDK Android

Notre SDK Android vous aide à intégrer les paiements dans les applications Android plus rapidement et avec moins d'efforts. Il gère de nombreux détails techniques pour vous, ce qui vous évite de travailler directement avec l'API Client pour les tâches courantes. Les principaux avantages de l'utilisation du SDK sont :

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

Intégration du SDK

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

Exigences

Les versions minimales supportées des bibliothèques sont les suivantes :

• Java 17+
• Android 6+ (niveau API 23)

Installation

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

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

Applications d'exemple

Nous avons fourni une application exemple en Kotlin et Java que vous pouvez utiliser comme base pour votre propre implémentation. Si vous aimez son apparence et sa convivialité, vous n'avez pas besoin de faire de modifications. Vous pouvez télécharger les applications exemple ci-dessous :

• Application exemple en Kotlin – Disponible en Jetpack Compose et en implémentations basées sur XML.
• Application exemple en Java – Disponible en implémentation basée sur XML.

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

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

1. Initialiser le SDK

Tout d'abord, vous devez créer un objet OnlinePaymentSdk 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 votre application, votre application cliente demande à votre application serveur de créer une Session. Lorsqu'une application serveur reçoit une demande, elle peut créer une Session via CreateSession à partir du SDK du serveur.

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

{
"assetUrl": "https://assets.test.cdn.v-psp.com/s2s/515c2c0bd13d5dd4bd42",
"clientApiUrl": "https://payment.preprod.direct.worldline-solutions.com/",
"clientSessionId": "68a4b0b183a34016b4b694b97938f75b",
"customerId": "cf7d7aafd42e4a1cb9e4b0624a5041b1"
}

Maintenant, transmettez clientSessionId, customerId, clientApiUrl et assetUrl à l'application Client. Une fois que l'application reçoit une réponse de l'application Serveur avec les informations de données de session, créez un objet local OnlinePaymentSdk côté application Client.

    // Create session data
SessionData sessionData = new SessionData(
    "47e9dc332ca24273818be2a46072e006", // client session id
"9991-0d93d6a0e18443bd871c89ec6d38a873", // customer id
    "https://clientapi.com", // client API URL
    "https://assets.com" // asset URL
);

// Create SDK configuration
SdkConfiguration sdkConfiguration = new SdkConfiguration( //optional
    false, // states if the environment is production, this property is used to determine the Google Pay environment
    "Android Example Application/v2.0.4", // your application identifier
    "AndroidSDK/v4.0.0", // SDK identifier, optional
    true // if true, requests and responses will be logged to the console; not supplying this parameter means it is false; should be false in production
);

// Initialise SDK
OnlinePaymentSdk sdk = new OnlinePaymentSdk(
    sessionData,
    getApplicationContext(), // this will get your Java application context
    sdkConfiguration
);

// Create session data
 val sessionData = SessionData(
    clientSessionId = "47e9dc332ca24273818be2a46072e006", // client session id
    customerId = "9991-0d93d6a0e18443bd871c89ec6d38a873", // customer id
    clientApiUrl = "https://clientapi.com", // client API URL
    assetUrl = "https://assets.com" // asset URL
 )

 // Create SDK configuration
 val sdkConfiguration = SdkConfiguration(
    environmentIsProduction = false, // states if the environment is production, this property is used to determine the Google Pay environment
    appIdentifier = "Android Example Application/v2.0.4", // your application identifier
    sdkIdentifier = "AndroidSDK/v4.0.0", // SDK identifier
    loggingEnabled = true // if true, requests and responses will be logged to the console; not supplying this parameter means it is false; should be false in production
 )

 // Initialise SDK
 val sdk = OnlinePaymentSdk(
    sessionData = sessionData,
    context = getApplication<application>().applicationContext, // application context
    configuration = sdkConfiguration //optional
 )

Après avoir créé OnlinePaymentSdk, vous devrez également configurer votre objet PaymentContext, comme indiqué ci-dessous. Il contient des informations telles que la devise, le pays, le montant, etc.

AmountOfMoney amountOfMoney = new AmountOfMoney(
    1298L, // in cents as a Long
    "EUR" //three-letter currency code as defined in ISO 4217
);
 
PaymentContext paymentContext = new PaymentContext(
    amountOfMoney,
    "NL", // two-letter country code as defined in ISO 3166-1 alpha-2
    false // true, if it is a recurring payment
);

val amountOfMoney = AmountOfMoney(
    1298L, // in cents as a Long
    "EUR" //three-letter currency code as defined in ISO 4217
)
 
val 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

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 liste. Il suffit de récupérer et d'afficher les listes de BasicPaymentProduct et AccountOnFile pour permettre à votre client d'en sélectionner un.

// sync call - blocks the main thread
 try {
 BasicPaymentProducts basicPaymentProducts = sdk.getBasicPaymentProductsSync(paymentContext);
    // Display the contents of basicPaymentProducts to your customer.
 } catch (ResponseException e) {
    // Handle HTTP/API errors (usually 4xx)
 } catch (CommunicationException e) {
   // Handle communication errors (network connection failed, timeout, malformed URL, etc.)
 } catch (Exception e) {
   // Handle any other unhandled exception
 }

// *** Listener-based async call ****
session.getBasicPaymentProducts(
    paymentContext, // PaymentContext
    new BasicPaymentProductsResponseListener() {
        @Override
        public void onSuccess(@NonNull BasicPaymentProducts basicPaymentProducts) {
           // Display the contents of basicPaymentProducts to your customer
        }

        @Override
        public void onApiError(ErrorResponse errorResponse) {
            // Handle API failure of retrieving the available Payment Products
        }

        @Override
        public void onException(Throwable throwable) {
            // Handle failure of retrieving the available Payment Products
        }
    }
);

try {
     BasicPaymentProducts basicPaymentProducts = sdk.getBasicPaymentProducts(paymentContext);
     // Display the contents of basicPaymentProducts to your customer.
 } catch (ResponseException e) {
     // Handle the exception thrown by the API. Usually, these are 4xx exceptions.
 } catch (CommunicationException e) {
    // Handle communication errors (network connection failed, timeout, malformed URL, etc.)
 } catch (Exception e) {
    // Handle any other unhandled exception
 }

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

Pour les appels asynchrones en Java, vous pouvez utiliser l'approche basée sur les écouteurs (comme illustré dans l'exemple ci-dessus). Vous pouvez également utiliser la même approche pour d'autres appels.

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

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

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

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

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

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

Le processus de paiement standard est un paiement par carte. Une fois que le client a sélectionné le produit de paiement souhaité, récupérez le PaymentProduct enrichi détaillant quelles informations le client doit fournir pour autoriser le paiement. Ensuite, affichez les champs d'informations requis à votre client.

// sync call
try {
    PaymentProduct paymentProduct = sdk.getPaymentProductSync(paymentProductId, paymentContext);
    // Display the fields to your customer.
} catch (e: ResponseException) {
    // Handle the exception thrown by the API. Usually, these are 4xx exceptions.
} catch (e: CommunicationException) {
    // Handle the communication exception - it can happen when the API call could not be established.
} catch (e: Exception) {
    // Handle any other unhandled exception.
}

try {
    val paymentProduct = sdk.getPaymentProduct(paymentProductId, paymentContext)
    // Display the fields to your customer.
} catch (e: ResponseException) {
    // Handle the exception thrown by the API. Usually, these are 4xx exceptions.
} catch (e: CommunicationException) {
    // Handle the communication exception - it can happen when the API call could not be established.
} catch (e: Exception) {
    // Handle any other unhandled exception.
}

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

4. Valider les données fournies

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

// payment request with paymentProduct, accountOnFile, tokenize status
PaymentRequest paymentRequest = new PaymentRequest(paymentProduct, null, false);

var paymentRequest = PaymentRequest(paymentProduct)

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

PaymentRequest paymentRequest = new PaymentRequest(paymentProduct, accountOnFile, true);

var paymentRequest = PaymentRequest(paymentProduct, true)

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

// set a value to the specific field 
paymentRequest.field("cardNumber).setValue("12451254457545")

// or 
paymentRequest.setValue("cvv","123");
paymentRequest.setValue("expiryDate","1225");

// set a value to the specific field
paymentRequest.field("cardNumber").setValue("12451254457545")

// or
paymentRequest.setValue("cvv","123")
paymentRequest.setValue("expiryDate","1225")

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

// validate all fields in the payment request
// validate() returns ValidationResult object with isValid status and errors
ValidationResult validationResult = paymentRequest.validate();

// check if the payment request is valid - result will return isValid: true and errors: []
if (validationResult.isValid()) {
    // payment request is valid
} else {
    // payment request has errors
    List errors = validationResult.getErrors();
    
    for (ValidationErrorMessage error : errors) {
        //show errors
    }
}

// validate all fields in the payment request
// validate() returns ValidationResult object with isValid status and errors
val validationResult = paymentRequest.validate()

// check if the payment request is valid - result will return isValid: true and errors: []
if (validationResult.isValid) {
    // payment request is valid
} else {
    // payment request has errors
    for (error in validationResult.errors) {
      //show errors
    }
}

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

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

Après la validation de PaymentRequest, vous aurez accès à sa version chiffrée, EncryptedRequest. Envoyez les données client cryptées à votre serveur comme suit :

try {
     EncryptedRequest encryptedRequest = sdk.encryptPaymentRequestSync(paymentRequest);
     // Send the encryptedRequest.encryptedCustomerInput to your server and use it to create the payment with the Server SDK.
 } catch (EncryptionException e) {
     // Handle encryption failure (invalid payment data, encryption failed, etc.)
 } catch (ResponseException e) {
     // Handle HTTP/API errors (usually 4xx)
 } catch (CommunicationException e) {
     // Handle communication errors when fetching public key (network issues, timeout, etc.)
 } catch (Exception e) {
    // handle any other unhandled exception
 }

try {
     val encryptedRequest = sdk.encryptPaymentRequest(paymentRequest)
     // Send the encryptedRequest.encryptedCustomerInput to your server and use it to create the payment with the Server SDK.
 } catch (e: EncryptionException) {
     // Handle encryption failure (invalid payment data, encryption failed, etc.)
 } catch (e: ResponseException) {
     // Handle HTTP/API errors (usually 4xx)
 } catch (e: CommunicationException) {
    // Handle communication errors when fetching public key (network issues, timeout, etc.)
 } catch (e: Exception) {
    // Handle any other unhandled exception
 }

6. Finaliser la transaction

Après avoir crypté les données du client, envoyez la chaîne de caractères de saisie client cryptée à votre serveur et utilisez-la pour effectuer une requête CreatePayment avec le SDK serveur. Vous pouvez utiliser l'encryptedCustomerInput fourni dans la requête cryptée pour le champ encryptedCustomerInput de la demande de paiement afin de finaliser le paiement.

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

Objets SDK

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

• OnlinePaymentSdk
• PaymentContext
• BasicPaymentProduct
• AccountOnFile
• PaymentProduct
• PaymentProductField
• PaymentRequest
  
  • Tokeniser la PaymentRequest
  • Définir les valeurs des champs pour la PaymentRequest
  • Valider la PaymentRequest
  • Chiffrer la PaymentRequest
• CreditCardTokenRequest

OnlinePaymentSdk

Une instance de OnlinePaymentSdk est requise pour toutes les interactions avec le SDK. Le fragment de code suivant montre comment initialiser OnlinePaymentSdk. Vous obtenez les détails de la session en effectuant un appel Create Client Session en utilisant l'API Server.

// Create session data
SessionData sessionData = new SessionData(
    "47e9dc332ca24273818be2a46072e006", // client session id
"9991-0d93d6a0e18443bd871c89ec6d38a873", // customer id
    "https://clientapi.com", // client API URL
    "https://assets.com" // asset URL
);

// Create SDK configuration
SdkConfiguration sdkConfiguration = new SdkConfiguration( //optional
    false, // states if the environment is production, this property is used to determine the Google Pay environment
    "Android Example Application/v2.0.4", // your application identifier
    "AndroidSDK/v4.0.0", // SDK identifier, optional
    true // if true, requests and responses will be logged to the console; not supplying this parameter means it is false; should be false in production
);

// Initialise SDK
OnlinePaymentSdk sdk = new OnlinePaymentSdk(
    sessionData,
    getApplicationContext(), // this will get your Java application context
    sdkConfiguration
);

// Create session data
 val sessionData = SessionData(
    clientSessionId = "47e9dc332ca24273818be2a46072e006", // client session id
    customerId = "9991-0d93d6a0e18443bd871c89ec6d38a873", // customer id
    clientApiUrl = "https://clientapi.com", // client API URL
    assetUrl = "https://assets.com" // asset URL
 )

 // Create SDK configuration
 val sdkConfiguration = SdkConfiguration(
    environmentIsProduction = false, // states if the environment is production, this property is used to determine the Google Pay environment
    appIdentifier = "Android Example Application/v2.0.4", // your application identifier
    sdkIdentifier = "AndroidSDK/v4.0.0", // SDK identifier
    loggingEnabled = true // if true, requests and responses will be logged to the console; not supplying this parameter means it is false; should be false in production
 )

 // Initialise SDK
 val sdk = OnlinePaymentsSDK(
    sessionData = sessionData,
    context = getApplication<application>().applicationContext, // application context
    configuration = sdkConfiguration
 )

Toutes les méthodes que fournit l'OnlinePaymentSdk sont des wrappers autour de l'API Client. Elles créent la requête et convertissent la réponse en objets Java pouvant contenir des fonctions de commodité.

PaymentContext

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

public class PaymentContext {
    private AmountOfMoney amountOfMoney; // contains the total amount and the ISO 4217 currency code
    private String countryCode; // ISO 3166-1 alpha-2 country code
    private boolean isRecurring; // Set `true` when payment is recurring. Default false.
}

data class PaymentContext(
    var amountOfMoney: AmountOfMoney? = null, // contains the total amount and the ISO 4217 currency code
    var countryCode: String? = null, // ISO 3166-1 alpha-2 country code
    var isRecurring: Boolean = false // Set `true` when payment is recurring. Default false.
) : Serializable { ... }

BasicPaymentProduct

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

• BasicPaymentProduct
• PaymentProduct

Les instances de BasicPaymentProduct contiennent uniquement les informations nécessaires pour afficher une liste simple de produits de paiement ou de comptes enregistrés pour que le client puisse en choisir un.

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

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

BasicPaymentProducts basicPaymentProducts = sdk.getBasicPaymentProducts(paymentContext)

List<basicpaymentproduct> paymentProducts = basicPaymentProducts.getPaymentProducts();

String label = paymentProducts[0].getLabel();
String logoUrl = paymentProducts[0].getLogo();

val basicPaymentProducts = sdk.getBasicPaymentProducts(paymentContext)

val paymentProducts = basicPaymentProducts.paymentProducts

val label = paymentProducts[0].label
val logoUrl = paymentProducts[0].logo

AccountOnFile

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

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

// All available accounts on file for the payment product
List<accountonfile> allAccountsOnFile = basicPaymentProduct.getAccountsOnFile();

// Get the specific account on file for the payment product
AccountOnFile accountOnFile = null;

for (AccountOnFile aof : basicPaymentProduct.getAccountsOnFile) {
    if (Objects.equals(aof.getId(), identifier)) { // 'identifier' is the ID of the AccountOnFile selected by the customer
        accountOnFile = aof;
        break;
    }
}

// Shows a mask-based formatted value for the obfuscated cardNumber.
String label = accountOnFile.getLabel();

// All available accounts on file for the payment product
val allAccountsOnFile = basicPaymentProduct.accountsOnFile

// Get the specific account on file for the payment product
val accountOnFile = basicPaymentProduct.accountsOnFile
    .firstOrNull { it.id == identifier } // 'identifier' is the ID of the AccountOnFile selected by the customer

// Shows a mask-based formatted value for the obfuscated card number
val label = accountOnFile?.label

PaymentProduct

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

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

Utilisez l'instance OnlinePaymentSdk pour récupérer l'instance de PaymentProduct, comme montré dans l'extrait de code ci-dessous.

// Note that exception handling is omitted here. Check the code above for more info. 
PaymentProduct paymentProduct = sdk.getPaymentProductSync(
    "1", // id of the payment product you want to retrieve
    paymentContext, // PaymentContext
);

// Note that exception handling is omitted here. Check the code above for more info. 
val paymentProduct = sesssdkion.getPaymentProduct(
    "1", // id of the payment product you want to retrieve
    paymentContext, // PaymentContext
)

PaymentProductField

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

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

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

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

Boolean isRequired = ccvField.isRequired(); // state if value is required for this field
Boolean shouldObfuscate = ccvField.shouldObfuscate(); // state if field value should be obfuscated

val ccvField = paymentProduct.getField("cvv")

val isRequired = ccvField.isRequired()
val shouldObfuscate = ccvField.shouldObfuscate()

PaymentRequest

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

L'objet PaymentRequest possède une liste de PaymentRequestFields. Chaque champ fournit les méthodes pour :

• Définir et récupérer des valeurs
• Obtenir l’étiquette du champ
• Obtenir des valeurs masquées pour l'affichage
• Valider la saisie de l'utilisateur par rapport aux restrictions du champ

Une fois que le PaymentRequest est créé, fournissez-lui les valeurs des champs comme suit :

boolean tokenize = true; // true or false 

// provide paymentProduct, accountOnFile, tokenize status
PaymentRequest paymentRequest = new PaymentRequest(paymentProduct, null, tokenize);

// or
PaymentRequest paymentRequest = new PaymentRequest(paymentProduct, accountOnFile, tokenize);

// tokenize status set to false by default
var paymentRequest = PaymentRequest(paymentProduct)

// with account on file
var paymentRequest = PaymentRequest(paymentProduct, accountOnFile)

Lorsqu’aucun AccountOnFile n’est sélectionné pour le PaymentRequest spécifique, tous les champs de la demande de paiement (par exemple, cardNumber) sont modifiables et vous pouvez les définir normalement.

En revanche, lorsque le PaymentRequest contient un AccountOnFile, le SDK se comporte différemment. Le système efface toutes les valeurs des champs précédemment non modifiables du PaymentRequest, et vous ne pouvez plus définir manuellement les champs en lecture seule. L’appel d’un setter déclenchera une InvalidArgumentException, tandis que l’appel de paymentRequest.getField(readOnlyFieldId).getValue() renverra undefined.

Ce comportement garantit que seules les valeurs modifiables sont soumises. Vous pouvez toujours utiliser l’instance accountOnFile pour afficher les valeurs masquées au client.

Tokeniser la PaymentRequest

Une PaymentRequest possède une propriété tokenize. Vous pouvez l'utiliser pour indiquer si une demande de paiement doit être stockée comme un compte dans le fichier pour de futurs paiements. Le fragment de code ci-dessous montre comment construire une demande de paiement lorsque vous souhaitez la stocker comme un compte dans le fichier.

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

// you can supply tokenize via the constructor
var paymentRequest = PaymentRequest(paymentProduct, true)

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

PaymentRequest paymentRequest = new PaymentRequest(
    paymentProduct,
    accountOnFile,
    tokenizeStatus
); // when you do not pass an accountOnFile argument, it will be null

val paymentRequest = PaymentRequest(paymentProduct, 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 = new PaymentRequest(paymentProduct, null, false);

paymentRequest.getField("cardNumber").setValue("12451254457545")
paymentRequest.getField("cvv").setValue("123")
paymentRequest.getField("expiryDate").setValue("1225")

var paymentRequest = PaymentRequest(paymentProduct)

paymentRequest.getField("cardNumber").setValue("12451254457545")
paymentRequest.getField("cvv").setValue("123")
paymentRequest.getField("expiryDate").setValue("1225")

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

Valider la PaymentRequest

Une fois que le PaymentRequest reçoit toutes les valeurs, il peut valider la demande de paiement. La validation utilise les DataRestrictions définies dans les champs ajoutés au PaymentRequest. Le serveur fournira également une liste des erreurs survenues lors de la validation.

S’il n’y a aucune erreur, vous pouvez chiffrer la demande de paiement et l’envoyer à notre plateforme via votre serveur. En cas d’erreurs de validation, vous devez fournir au client un retour d’information concernant ces erreurs.

Les validations renvoient une liste de ValidationErrorMessage à l’intérieur de l’objet ValidationResult.

// validate all fields in the payment request
// validate() return ValidationResult object with isValid status and errors
ValidationResult validationResult = paymentRequest.validate();

// check if the payment request is valid - result will return isValid: true and errors: []
if (validationResult.isValid()) {
    // payment request is valid
} else {
    // payment request has errors
    List<validationerrormessage> errors = validationResult.getErrors();
    
    for (ValidationErrorMessage error : errors) {
        //show errors
    }
}

// validate all fields in the payment request
// validate() return ValidationResult object with isValid status and errors
val validationResult = paymentRequest.validate()

// check if the // check if the payment request is valid - result will return isValid: true and errors: []
if (validationResult.isValid) {
    // payment request is valid
} else {
    // payment request has errors
    for (error in validationResult.errors) {
      //show errors
    }
}

Chiffrer la PaymentRequest

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

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

Après avoir chiffré avec succès la PaymentRequest, vous aurez accès à sa version cryptée. L'EncryptedRequest contient les champs de la demande de paiement chiffrés et les informations de méta-données client encodées.

try {
    EncryptedRequest encryptedRequest = sdk.encryptPaymentRequestSync(paymentRequest);
    // Send the encryptedRequest.encryptedCustomerInput to your server and use it to create the payment with the Server SDK.
} catch (EncryptionException e) {
    // Handle encryption failure (invalid payment data, encryption failed, etc.)
} catch (ResponseException e) {
    // Handle HTTP/API errors (usually 4xx)
} catch (CommunicationException e) {
    // Handle communication errors when fetching public key (network issues, timeout, etc.)
} catch (Exception e) {
    // Handle any other unhandled exception
}

try {
    val encryptedRequest = sdk.encryptPaymentRequest(paymentRequest)

    // Send the encryptedRequest.encryptedCustomerInput to your server and use it to create the payment with the Server SDK.
} catch (EncryptionException e) {
    // Handle encryption failure (invalid payment data, encryption failed, etc.)
} catch (ResponseException e) {
    // Handle HTTP/API errors (usually 4xx)
} catch (CommunicationException e) {
    // Handle communication errors when fetching public key (network issues, timeout, etc.)
} catch (Exception e) {
    // Handle any other unhandled exception
}

CreditCardTokenRequest

Vous pouvez utiliser la classe CreditCardTokenRequest pour créer une demande de CardTokenization. Elle contient les champs essentiels de la carte de crédit tels que : numéro de carte, nom du titulaire de la carte, date d'expiration, cryptogramme visuel (CVV) et l'identifiant du produit de paiement.

CreditCardTokenRequest tokenRequest = new CreditCardTokenRequest();
tokenRequest.setCardNumber("1234567890123452");
tokenRequest.setCardHolderName("John Doe");
tokenRequest.setExpiryDate("1225");
tokenRequest.setSecurityCode("123");
tokenRequest.setPaymentProductId(1);

val tokenRequest = CreditCardTokenRequest()
tokenRequest.cardNumber = "1234567890123452"
tokenRequest.cardholderName = "John Doe"
tokenRequest.expiryDate = "1225"
tokenRequest.securityCode = "123"
tokenRequest.paymentProductId = 1

Notez qu'aucune règle de validation n'est appliquée aux valeurs définies dans la requête de jeton, car elle est détachée de l'instance du produit de paiement. Vous devriez utiliser cette classe comme une aide pour chiffrer les données nécessaires à la création d'un jeton à l'aide du SDK Server. Cependant, si des données non valides sont fournies, la requête de CreateToken échouera.

try {
    EncryptedRequest encryptedRequest = sdk.encryptTokenRequest(tokenRequest);
    // Send the encryptedRequest.encryptedCustomerInput to your server and use it to create the payment with the Server SDK.
} catch (EncryptionException e) {
    // Handle encryption failure (invalid payment data, encryption failed, etc.)
} catch (ResponseException e) {
    // Handle HTTP/API errors (usually 4xx)
} catch (CommunicationException e) {
    // Handle communication errors when fetching public key (network issues, timeout, etc.)
} catch (Exception e) {
    // Handle any other unhandled exception
}

try {
    val encryptedRequest = sdk.encryptTokenRequest(tokenRequest)
    // Send the encryptedRequest.encryptedCustomerInput to your server and use it to create the payment with the Server SDK.
} catch (EncryptionException e) {
    // Handle encryption failure (invalid payment data, encryption failed, etc.)
} catch (ResponseException e) {
    // Handle HTTP/API errors (usually 4xx)
} catch (CommunicationException e) {
    // Handle communication errors when fetching public key (network issues, timeout, etc.)
} catch (Exception e) {
    // Handle any other unhandled exception
}

Fonctionnalités supplémentaires

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

• Chiffrer les données sensibles
• Valider les données
• Appliquer la vérification IIN
• Mettre en œuvre les paiements natifs
• Utiliser la journalisation

Chiffrer les données sensibles

L'un des plus grands atouts du SDK est son outil de cryptage. Il offre une excellente sécurité lors du transfert de données sensibles (c'est-à-dire les numéros de carte, la date d'expiration, le code CVC). Un flux complet de cryptage/transfert ressemble à ceci :

Le SDK est conçu pour simplifier ce processus. Voici ce que vous devez faire :

1. Utilisez sdk.encryptPaymentRequest pour chiffrer les informations de paiement fournies dans le PaymentRequest.
2. Le sdk.encryptPaymentRequest renvoie l'EncryptedRequest contenant les données client chiffrées.
3. Récupérez l'entrée client chiffrée à partir de l'EncryptedRequest.
4. Envoyez l'entrée client chiffrée à votre serveur.
5. Envoyez les données chiffrées depuis votre serveur en utilisant la demande CreatePayment. Fournissez les données chiffrées dans le champ encryptedCustomerInput.
6. Envoyez le résultat de la transaction à l'application cliente.

// Note that exception handling is omitted here. Check the code above for more info. 
EncryptedRequest encryptedRequest = sdk.encryptPaymentRequest(paymentRequest);

// Note that exception handling is omitted here. Check the code above for more info. 
val encryptedRequest = sdk.encryptPaymentRequest(paymentRequest)

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

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

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

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, ainsi qu'un message que vous pouvez facilement traduire. Ces validateurs ne sont pas directement accessibles pour vous, mais vous pouvez récupérer une instance de PaymentProductField à partir de l'instance PaymentProduct et appeler les méthodes setValue() et validate().

Appliquer la vérification IIN

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

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

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

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

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

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

// The exception handling is omitted from this example. See the examples above.
sdk.getIinDetailsSync(
    "123456", // partial credit card number
    paymentContext // PaymentContext
);

// The exception handling is omitted from this example. See the examples above.
sdk.getIinDetails("123456", paymentContext)

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 vous n'êtes pas configuré pour traiter ces cartes locales, l'appel API ne renverra pas ce type de carte dans sa réponse. Sinon, l'instance de IinDetailsResponse aura les informations sur les co-marques.

Mettre en œuvre les paiements natifs

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

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

Pour les appareils Android, vous commencez par vérifier si le système répond au critère de version minimum (6.0 - Marshmallow). Ensuite, vous utilisez PaymentClient pour effectuer une demande IsReadyToPayRequest afin de renvoyer une valeur en fonction du résultat. Le SDK le fera automatiquement et filtrera les produits de paiement non pris en charge.

Utiliser la journalisation

La journalisation vous permet d'inspecter les requêtes et réponses échangées entre votre application et notre plateforme. Ceci est utile pour le développement et le débogage, mais vous ne devriez pas l'activer dans les environnements de production.

Vous pouvez configurer la journalisation lors de l'initialisation de l'OnlinePaymentSdk. Pour l'activer, définissez le champ loggingEnabled sur true dans le SdkConfiguration.

new SdkConfiguration(
        false, // states if the environment is production, this property is used to determine the Google Pay environment
        "Android Example Application/v2.0.4", // your application identifier
        "AndroidSDK/v4.0.0", // SDK identifier
        true // if true, requests and responses will be logged to the console; not supplying this parameter means it is false; should be false in production
    )

// Create SDK configuration
 val sdkConfiguration = SdkConfiguration(
    environmentIsProduction = false, // states if the environment is production, this property is used to determine the Google Pay environment
    appIdentifier = "Android Example Application/v2.0.4", // your application identifier
    sdkIdentifier = "AndroidSDK/v4.0.0", // SDK identifier
    loggingEnabled = true // if true, requests and responses will be logged to the console; not supplying this parameter means it is false; should be false in production
 )