Guide d'integration React Native

Ajouter le SDK de paiement à votre application

Procédure

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.

Ajout du SDK pour un projet 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.

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.

Initialiser le SDK

Appelez la méthode initialize avec ces paramètres :

Paramètre	Format	Description	Ex
publicKey	String	2 ème clé du tableau des clés API REST	42229744:testpublickey_tPXxrUVsoGkggk9LuO8o0PBRdWg8jWUhWmYMURwCbc8ap
options	Object	Objet pour configurer le comportement du SDK.	Voir tableau ci-dessous

Dans l'objet options, utilisez ces paramètres :

Clés	Format	Description	Ex
apiServerName	String	1 ère donnée du tableau des clés API REST. Obligatoire	https://api.scelliuspaiement.labanquepostale.fr
cardScanningEnabled	Bool	Active/Désactive la fonctionnalité de scan de la carte par caméra. Si elle n’est pas définie, la fonctionnalité sera désactivée. Facultatif.	True

Exemple pour la boutique DEMO

Avec les clés de la boutique de DEMO, valorisez dans la fonction initialize :

apiServerName par https://api.scelliuspaiement.labanquepostale.fr
publicKey par 42229744:testpublickey_tPXxrUVsoGkggk9LuO8o0PBRdWg8jWUhWmYMURwCbc8ap

Méthode initialize

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

En cas d'echec de l'initialisation du SDK, voir : Gestion des erreurs.

Le SDK ne permet pas de faire plusieurs process en parallèle (pas de callback , pas d'exception). Durant le traitement du premier appel, les autres appels sont ignorés.

Réaliser un paiement

A. Créer un formToken

Requête

Appelez le Web Service Charge/CreatePayment (toujours depuis votre serveur marchand), avec le contexte de paiement (montant, devise, numéro de commande, coordonnées de l'acheteur, etc.). Dans cette requête, utilisez ce paramètre `formTokenVersion` correspondant au résultat de la méthode `getFormTokenVersion` du SDK.

Retrouvez l'intégralité et la description des champs dans notre playground Playground

Exemple avec la génération du formToken

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

Réponse

La réponse de l'appel Web Service REST Charge/CreatePayment correspond au `formToken`.

C'est une clé générée par la plateforme de paiement. Elle contient les données du paiement (montant, devise, coordonnées de l'acheteur, etc...).

Intégrez le formToken pour afficher le formulaire.

B. Afficher l'écran de paiement

Transmettez le formToken lors de l'appel de la méthode Lyra.process avec ces paramètres :

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.

Exemple de code : méthode `process`

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

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

C. Procéder au paiement

En mode TEST, des exemples de carte de test sont disponibles : Cartes de test.

Pour passer en mode PRODUCTION, voir : lien.

Analyser le résultat du paiement

La plateforme de paiement envoie le résultat du paiement dans un JSON Object LyraResponse :

vers la fonction callback onSuccess ou onError, côté application mobile.
vers une IPN (Instant Payment Notification), appel de serveur à serveur. Voir le paramétrage : "IPN".

A. Structure de la réponse

Paramètre	Description
kr-hash-key	Type de clé pour signer le `kr-answer`. Les valeurs possibles sont : `password` pour l'IPN / `sha256_hmac` pour le retour vers l'application mobile.
kr-hash-algorithm	Algorithme utilisé pour calculer le hash. Sa valeur est sha256_hmac.
kr-answer	Objet contenant le résultat du paiement, encodé en JSON.
kr-answer-type	Type de l'objet JSON contenu dans kr-answer.
kr-hash	Hash de l'objet JSON stocké dans kr-answer. Il permet de vérifier l'authenticité de la réponse.

Exemple de réponse

{
   "kr-hash":"80f5188e757c1828e8d4ccab87467eb50c4299e4057fa03b3f3185342f6d509c",
   "kr-hash-algorithm":"sha256_hmac",
   "kr-answer-type":"V4\/Payment",
   "kr-answer": "{
      "shopId":"65512466",
      "orderCycle":"CLOSED",
      "orderStatus":"PAID",
     (...)
      "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,
            ...
         },
         (...)
         "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",
            ...
         }
      ],
      "_type":"V4\/Payment"
   }"
}

Retrouvez l'intégralité et la description des champs de la réponse : Payment.

B. Analyse du résultat, côté application

Le kr-answer est l'objet contenant le résultat du paiement, encodé en JSON.

Récupérez le JSON envoyé par la plateforme de paiement
Calculez le kr-hash en utilisant la fonction hash_hmac et la clé HMAC-SHA-256 pour vérifier l'authenticité de la réponse.
- Algorithme de chiffrement : sha256.
- Clé secrète : Clé HMAC-SHA-256. (**3 ème** clé du tableau des clés API REST)
- Base d'encodage : héxadécimale (base 16).
Si le calcul de votre kr-hash est égal à celui de la plateforme alors le message est authentique.

Vérifiez le statut du paiement (Voir : références de status)

Exemple de code (sans le calcul du kr-hash)

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

C. Analyse du résultat depuis l'IPN

Intégrez l'IPN : Analyse de l'IPN (URL de notification).

D. Gestion des erreurs

Voir : Codes d'erreur.

Restrictions

Les fonctionnalités suivantes ne sont pas disponibles :

la méthode cancelProcess() pour annuler le processus de paiement.
les fonctions du scan de la carte et du NFC.

Catégories

Tags