Guide d'integration React Native

Pour intégrer le SDK de paiement à votre application React Native et réaliser un paiement, 4 étapes sont nécessaires :

Sur cette page vous pouvez trouver aussi :

Afin d'optimiser l'efficacité de notre support, notre SDK peut envoyer des messages Sentry vers nos serveurs lorsqu'une situation inhabituelle ou un problème survient. Dans ce cas, aucune donnée sensible n'est transférée, ni aucune donnée de votre application.

Consulter notre exemple d'intégration

Vous trouverez un exemple de code d'intégration de notre SDK dans une application React Native dans le dépôt Github

Ajouter le SDK de paiement à votre application

Pour ajouter le sdk de paiement à votre application react native :

Ajoutez dans votre fichier package.json la dépendance à notre [Native Module] (https://www.npmjs.com/package/@lyracom/react-native-sdk-payment-module).

{
  "dependencies": {
   	 "@lyracom/react-native-sdk-payment-module": "^1.0.0",
    },
}

Ajoutez dans les dépendances du développement la référence à pod-install :

 "devDependencies": {
   "pod-install": "^0.1.0"
 },

Modifiez le fichier Podfile dans votre dossier iOS :

Ajoutez use_frameworks! suite aux "require_relative" instructions.
Désactivez Flipper: mettez en commentaire la ligne :flipper_configuration => FlipperConfiguration.enabled.
Mettez à false les parametres suivantes: :hermes_enabled => false et :fabric_enabled => false.

Run yarn.
Run yarn pod-install --quiet.

Initialiser le SDK

Comme mentionné dans le chapitre sur le fonctionnement de la solution, il est nécessaire d'effectuer l'initialisation du SDK.

Pour cela, il suffit d'appeler la méthode initialize avec les paramètres suivants :

Paramètre	Format	Description
publicKey	string	Votre clé publique (disponible dans le Back Office Marchand : Paramètres > Boutique > Clés de l’API REST, cf. la page Prérequis).
options	Object	Objet qui vous permet de configurer le comportement du SDK.

Exemple d'appel :

            // Initialize Payment SDK
            initialize(
              config.publicKey,
              {
                cardScanningEnabled: true,
                apiServerName: "MY_API_SERVER_NAME",
              },
              async (result) => {
                // onError
                Alert.alert(result.error.errorMessage);
              }
           );

Les clés possibles du objet options sont :

Clés	Format valeur	Description	Requis
apiServerName	string	Votre nom du serveur de l’API REST (disponible dans le Back Office Marchand : Paramètres > Boutique > Clés de l’API REST), cf. la page Prérequis).	Requis
cardScanningEnabled	boolean	Active/Désactive la fonctionnalité de scan de la carte, cf. Activer la fonctionnalité de scan de la carte.	Optionnel

Il faut aussi noter que le SDK ne permet pas de faire plusieurs process en parallèle. Durant le traitement du premier appel, les autres appels seront ignorés.

Réaliser un paiement

La réalisation d'un paiement se décline en 2 étapes : l'initialisation de l'affichage du formulaire de paiement et le traitement du paiement proprement dit.

Initialisation de l'affichage du formulaire de paiement

Lorsque l'utilisateur décide de payer, vous devez initialiser l'affichage du formulaire de paiement.

Pour cela, vous devez appeler votre serveur marchand, pour y vérifier les achats de l'utilisateur, puis générer un identifiant de formulaire (appelé formToken) en appelant le Web Service Charge/CreatePayment (toujours depuis votre serveur marchand). Dans cette requête, vous devez passer un paramètre formTokenVersion qui correspond au résultat de la méthode getFormTokenVersion du SDK. La réponse du Web Service ou cet identifiant de formulaire doit ensuite être renvoyé à votre application.

            const getProcessPaymentContext = async () => {
              var formTokenVersion = getFormTokenVersion();
              return fetch(config.merchantServerUrl + "/createPayment", {
                method: "POST",
                headers: {
                  Accept: "application/json",
                  "Content-Type": "application/json",
                },
                body: paymentParams,
              })
              .then((result) => result.json())
              .then((json) => json.answer.formToken)
              .catch((error) => {
                console.error(error);
              });
            };

L'étape de validation du panier est une étape cruciale et il vous revient de vérifier sur vos serveurs que le montant correspond bien au panier avant de nous le transmettre.
Appeler le Web Service depuis l'application mobile revient à mettre à sa disposition (et à des pirates potentiels) vos clés d'appels, ce qui est contraire aux règles de sécurité.

Affichage de l'écran de paiement

Une fois le formToken reçu dans l'application mobile, vous devez le transmettre à notre SDK de paiement en appelant la méthode process avec les paramètres suivants :

Paramètre	Format	Description
formToken	string	Le formToken, extrait de la réponse du createPayment précédemment appelé.
options	Object	Objet qui vous permet personnaliser le formulaire de paiement.
onSuccess	(result: any) => void,	Fonction de callback appelée si le paiement s'est déroulé correctement.
onError	(result: any) => void,	Fonction de callback appelée si le paiement est en échec ou n'a pu être initié. Cette situation peut se produire si le paiement a été refusé ou si une erreur fonctionnelle ou technique est survenue pendant le paiement. Pour en savoir plus consulter : Gestion des erreurs.

Le SDK se charge alors de vérifier la cohérence du formToken puis affiche les moyens de paiements disponibles.

Exemple d'appel :

            process(
            formToken!,
            options,
            async (result) => {
              // onSuccess
              // Verify the payment using your server
              verifyPayment(result.response)
              .then(() => {
                Alert.alert(`Payment success`);
              })
              .catch(() => {
                Alert.alert(`Payment verification fail`);
              });
            },
            async (result) => {
              // onError
              Alert.alert(result.error.errorMessage);
            }
           );

Description de l'objet LyraResponse

L'objet LyraResponse est retourné dans les deux cas : onSuccess et onError. C'est un objet de type JSON Object. En cas de succès, il est nécessaire de vérifier son intégrité avant d'afficher le résultat du paiement.

Dans le cas où la transaction a été initiée côté serveur, il sera possible de récupérer simplement les informations du paiement.

Exemple :

{
   "kr-hash":"80f5188e757c1828e8d4ccab87467eb50c4299e4057fa03b3f3185342f6d509c",
   "kr-hash-algorithm":"sha256_hmac",
   "kr-answer-type":"V4\/Payment",
   "kr-answer": "{
      "shopId":"65512466",
      "orderCycle":"CLOSED",
      "orderStatus":"PAID",
      "serverDate":"2019-03-01T10:54:45+00:00",
      "orderDetails":{
         "orderTotalAmount":1100,
         "orderEffectiveAmount":1100,
         "orderCurrency":"EUR",
         "mode":"TEST",
         "orderId":null,
         "_type":"V4\/OrderDetails"
      },
      "customer":{
         "billingDetails":{
            "address":null,
            "category":null,
            "cellPhoneNumber":null,
            ...
         },
         "email":null,
         "reference":null,
         "shippingDetails":{
            "address":null,
            "address2":null,
            "category":null,
            ...
         },
         "extraDetails":{
            "browserAccept":null,
            "fingerPrintId":null,
            "ipAddress":"77.136.84.251",
            "browserUserAgent":"{\"deviceName\":\"Xiaomi Mi MIX 2S\",\"os\":\"Android\",\"osVersion\":\"[9]\",\"sdkVersion\":28,\"isMobile\":true}",
            "_type":"V4\/Customer\/ExtraDetails"
         },
         "shoppingCart":{
            "insuranceAmount":null,
            "shippingAmount":null,
            "taxAmount":null,
            "cartItemInfo":null,
            "_type":"V4\/Customer\/ShoppingCart"
         },
         "_type":"V4\/Customer\/Customer"
      },
      "transactions":[
         {
            "shopId":"65512466",
            "uuid":"64d704a9bb664898954c3ef537982f99",
            "amount":1100,
            "currency":"EUR",
            "paymentMethodType":"CARD",
            "status":"PAID",
            "detailedStatus":"AUTHORISED",
            "operationType":"DEBIT",
            "creationDate":"2019-03-01T10:54:44+00:00",
            ...
         }
      ],
      "_type":"V4\/Payment"
   }"
}

La réponse contient les mêmes éléments que ceux envoyés dans l'IPN :

Paramètre	Description
kr-hash	Hash de l'objet JSON stocké dans kr-answer. Il permet de vérifier l'authenticité de la réponse
kr-hash-algorithm	Algorithme utilisé pour calculer le hash
kr-hash-key	Clé utilisée pour signer kr-answer
kr-answer-type	Type de l'objet JSON contenu dans kr-answer
kr-answer	Objet contenant les objets transactions complets encodés en JSON

L'objet kr-answer contient les éléments décrits ici.

Dans certains cas, il se peut que la transaction n'ait pu être initiée, côté serveur. Il sera possible de retrouver l'erreur renvoyée par l'API dans le json (vous trouverez le format ici : Codes d'erreur).

Vérifier le statut de la transaction

Une fois le paiement terminé, qu'il soit accepté ou refusé, vous serez notifié de 2 manières :

par un appel (IPN) vers votre serveur marchand, si ce dernier est enregistré auprès de notre plateforme de paiement,
par l'appel des callback onSuccess ou onError côté application mobile.

Il est nécessaire de vérifier l'intégrité du message (voir ici pour plus de détails), et de lancer les traitements métiers côté serveur (lors de la réception de l'IPN).

Nos exemples de code fournissent un exemple de contrôle d'intégrité du message via votre serveur marchand. Il s'agit du endPoint verifyResult appelé dans la méthode verifyResult de l'application.

Voici un code exemple se basant sur le serveur marchand mis à votre disposition.

            const verifyPayment = async (paymentResult: any) => {
              return fetch(config.merchantServerUrl + "/verifyResult", {
                method: "POST",
                headers: {
                  Accept: "application/json",
                  "Content-Type": "application/json",
                },
                body: paymentResult,
              });
            };

Personnaliser le SDK

Thème

Il est possible de personnaliser le SDK, de sorte que les vues générées à partir du SDK (formulaire de paiement) soient affichées avec les mêmes couleurs et la même police que celles utilisées dans votre application.

Vous pouvez définir :

une couleur principale,
une couleur secondaire,
la police à utiliser sur l'ensemble des textes affichés dans le SDK.

La couleur principale permet de modifier :

la couleur de fond de l'entête,
la couleur de fond du bouton "Payer",
la couleur de mot de fermeture de la popup d'aide au CVV,
la couleur de mot de fermeture de la popup du choix de la marque,
la couleur du surlignage et libellé du champ lorsque celui-ci est édité,
la couleur du texte dans le message de paiement en cours,
la couleur du spinner dans le message de paiement en cours.

La couleur secondaire permet de modifier :

la couleur du logo de la flèche de retour arrière dans l'entête du SDK,
la couleur des textes dans l'entête du SDK,
la couleur du texte dans le bouton "Payer".

Pour que la personnalisation soit prise en compte il faudra faire les modifications suivantes dans la partie native du projet: iOS et Android :

iOS

Ajouter un fichier PaymentSdkTheme.plist dans le dossier iOS de votre projet et spécifier dans ce fichier les couleurs à utiliser en hexadécimal :

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<key>PaymentSDKColor</key>
	<dict>
		<key>PaymentSDK_PrimaryColor</key>
		<string>#293C7A</string>
		<key>PaymentSDK_SecondaryColor</key>
		<string>#FFFFFF</string>
	</dict>
</dict>
</plist>

Il est également possible de modifier la police utilisée avec la clé PaymentSDKFont.

Puis, ajouter le fichier PaymentSdkTheme.plist et celui de la police à votre projet iOS (depuis Xcode ouvrir le fichier.xcworkspace)

Android

Définir les couleurs dans votre fichier colors.xml :

<color name="payment_sdk_PrimaryColor">#293C7A</color>
<color name="payment_sdk_SecondaryColor">#FFFFFF</color>

Pour personnaliser la police vous devez juste surcharger le style nécessaire dans le fichier styles.xml :

<style name="PaymentSDK_Theme">
    <item name="android:fontFamily"></i>casual</item></style>

Textes

Il est aussi possible de personnaliser certains textes. Pour cela, vous pouvez utiliser le paramètre options lors de l'appel au process.

Bouton PAYER

Le texte du bouton PAYER peut être personnalisé.

Spécifier la clé customPayButtonLabel.

Entête

Si le texte est forcé et qu'il n'y a pas d'orderId, il remplacera le texte par défaut qui est "Paiement" ou "Enregistrement de la carte".
Par contre, si un orderId est précisé alors, on continuera à afficher "Commande OrderId".

Spécifier la clé customHeaderLabel.

Le texte de la popup qui s'ouvre suite au clic sur le bouton PAYER peut aussi être personnalisé.

Spécifier la clé customPopupLabel.

Activer la fonctionnalité de scan de la carte

La fonctionnalité de scan de la carte permet à un utilisateur de ne pas saisir les informations de sa carte manuellement mais d'utiliser la caméra de son appareil mobile pour la scanner et remplir automatiquement le formulaire de paiement.

Attention: Pour l'instant, cette fonctionnalité est seulement disponible pour les dispositifs iOS.

Pour activer cette fonctionnalité, vous devez lors de l'initialisation du SDK, envoyez true comme valeur à la clé cardScanningEnabled dans le dictionnaire des options de configuration (Voir Initialiser le SDK).

Dans le fichier Info.plist de votre application (dans le dossier iOS), ajoutez la clé NSCameraUsageDescription et décrivez la raison de l'utilisation de la caméra.

Activer la fonctionnalité NFC

La fonctionnalité NFC permet à un utilisateur de ne pas saisir les informations de sa carte manuellement mais d'utiliser le NFC pour la scanner et remplir automatiquement le formulaire de paiement.

Attention: Cette fonctionnalité est seulement disponible pour les dispositifs Android.

Pour activer cette fonctionnalité, vous devez lors de l'initialisation du SDK, envoyer true comme valeur pour la clé nfcEnabled dans les options de configuration (Voir Initialiser le SDK).

Ajouter la permission suivante dans le fichier AndroidManifest.xml de votre application :

<uses-permission android:name="android.permission.NFC" />

Limitations

Les fonctionnalités suivantes du SDK ne sont pas disponibles dans le Native Module :

La méthode cancelProcess().
Le scan de la carte sur les dispositifs Android.

Utiliser notre sdk dans une application Expo React Native

Si vous avez un projet Expo (managed workflow) pour ajouter le sdk de paiement à votre application:

Ajoutez dans votre fichier package.json la dépendance à notre [Native Module] (https://www.npmjs.com/package/@lyracom/react-native-sdk-payment-module).

{
  "dependencies": {
   	 "@lyracom/react-native-sdk-payment-module": "^1.0.0",
    },
}

Ajoutez les dépendences suivantes dans votre fichier package.json:

{
  "dependencies": {
   	"expo-build-properties": "~0.4.1",
  		"expo-dev-client": "^2.0.1",
    },
}

Dans votre fichier app.json ajoutez :

{
 "expo": {
   "plugins": [
     [
       "expo-build-properties",
       {
         "ios": {
           "useFrameworks": "dynamic"
         }
       }
     ]
   ]
 }}

Run yarn.

Attention: Une fois que notre [Native Module] (https://www.npmjs.com/package/@lyracom/react-native-sdk-payment-module) est ajouté à votre application Expo (managed workflow), il ne sera pas possible de le tester en utilisant Expo Go. Il faudra construire une application avec l’aide d’expo-dev-client. Pour cela :

Run eas build --profile development --platform ios.
Run eas build --profile development --platform android.
Installer l’application générée sur le périphérique correspondant.
Run expo start --dev-client.

Vous trouverez un exemple de code d'intégration de notre SDK dans une application Expo React Native dans le dépôt Github

Catégories

Tags

Guide d'integration React Native

Consulter notre exemple d'intégration

Ajouter le SDK de paiement à votre application

Initialiser le SDK

Réaliser un paiement

Initialisation de l'affichage du formulaire de paiement

Affichage de l'écran de paiement

Vérifier le statut de la transaction

Personnaliser le SDK

Thème

iOS

Android

Textes

Bouton PAYER

Entête

Activer la fonctionnalité de scan de la carte

Activer la fonctionnalité NFC

Limitations

Utiliser notre sdk dans une application Expo React Native

Catégories

Tags

Guide d'integration React Native

Consulter notre exemple d'intégration

Ajouter le SDK de paiement à votre application

Initialiser le SDK

Réaliser un paiement

Initialisation de l'affichage du formulaire de paiement

Affichage de l'écran de paiement

Vérifier le statut de la transaction

Personnaliser le SDK

Thème

iOS

Android

Textes

Bouton PAYER

Entête

Popup de paiement

Activer la fonctionnalité de scan de la carte

Activer la fonctionnalité NFC

Limitations

Utiliser notre sdk dans une application Expo React Native