Guide d'intégration Android

1. Ajouter le SDK mobile à votre application

Pour ajouter le SDK mobile de paiement à votre application, il est nécessaire d'ajouter la dépendance suivante dans votre build.gradle :

implementation 'com.lyra:sdk:1.6.+'

2. Initialiser le SDK mobile

1. Dans la la méthode onCreate, appelez la méthode initialize avec ces paramètres :

   Paramètre	Format	Description	Exemple
   publicKey	String	Clé publique. Pour plus d'info, consultez le tableau des clés API REST	69876357:testpublickey_DEMOPUBLICKEY95me92597fd28tGD4r5
   options	HashMap	Map pour configurer le comportement du SDK mobile ( NFC, scan de la carte).	Voir étape 2.

2. Configurez la Map options avec ces paramètres :

   Clés	Format	Description	Exemple
   apiServerName	String	Nom du serveur de l'API REST. Pour plus d'info, consultez le tableau des clés API REST. Obligatoire	https://api.lyra.com
   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
   nfcEnabled	Bool	Active/Désactive la fonctionnalité de scan de la carte par NFC. Si elle n’est pas définie, la fonctionnalité sera désactivée. Facultatif	True

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

val options = HashMap<String, Any>()
options[Lyra.OPTION_API_SERVER_NAME] = "MY_API_SERVER_NAME"
Lyra.initialize(applicationContext, PUBLIC_KEY, options)

HashMap options = new HashMap();
options.put(Lyra.OPTION_API_SERVER_NAME, "MY_API_SERVER_NAME");
Lyra.INSTANCE.initialize(getApplicationContext(), PUBLIC_KEY, options);

3. Réaliser un paiement

3.1 Créer un formToken

    requestQueue.add(JsonObjectRequest(Request.Method.POST,
    "${SERVER_URL}/createPayment",
    paymentParams,
    Response.Listener { response ->
        //Extract the formToken from the serverResponse
        val answer = JSONObject(response).getJSONObject("answer")
        val formToken = answer.getString("formToken")
        //Now, call Lyra.process() with the formToken
    },
    Response.ErrorListener { error ->
        //Please manage your error behaviour here
        Toast.makeText(
            applicationContext,
            "Error Creating Payment",
            Toast.LENGTH_LONG
        ).show()
    }
    ))

    requestQueue.add(new JsonObjectRequest(Request.Method.POST, SERVER_URL + "/createPayment", getPaymentParams(), new Response.Listener<JSONObject>() {
        //Process merchant server response
        @Override
        public void onResponse(JSONObject response) {
            //Extract the formToken from the serverResponse
            JSONObject answer = new JSONObject(response).getJSONObject("answer");
            String formToken = answer.getString("formToken");
            //Now, call Lyra.process() with the formToken
        }
    }, new Response.ErrorListener() {
        //Error when calling merchant server
        @Override
        public void onErrorResponse(VolleyError error) {
            //Please manage your error behaviour here
            Toast.makeText(getApplicationContext(), "Error Creating Payment", Toast.LENGTH_LONG).show();
        }
    }));

3.2 Afficher l'écran de paiement

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

   Paramètre	Format	Description
   supportFragmentManager	FragmentManager	Référence vers votre UI afin que le SDK mobile puisse afficher le formulaire de paiement. Obligatoire.
   formToken	String	Réponse du Web Service Charge/CreatePayment. Obligatoire.
   paymentHandler	LyraHandler	Callback pour traiter le résultat du paiement. Obligatoire.
   options	HashMap<String, Any>	Options permettant de personnaliser le paiement. Facultatif.

2. Implémentez les 2 méthodes du paymentHandler :

   Callback	Description
   onSuccess	Fonction de callback appelée lorsque le paiement s'est déroulé correctement.
   onError	Fonction de callback appelée lorsque le paiement n'a pu être initié ou a été refusé.

   Si la fonction onError retourne un objet LyraException, consultez : Gestion des erreurs.

3. Pour personnaliser le paiement, utilisez les clés de la Map options :

   Clés	Format	Description	Exemple
   CUSTOM_PAY_BUTTON_LABEL	String	Définit le label utilisé sur le bouton "Payer".	"MyPayButtonLabel"
   CUSTOM_HEADER_LABEL	String	Définit le label dans le header de la page de paiement.	"MyHeaderLabel"
   CUSTOM_POPUP_LABEL	String	Définit le label de la popup lorsqu'un paiement est en cours de traitement.	"MyPopupLabel"
   PAYMENT_METHOD_TYPE	LyraPaymentMethods	Définit la méthode de paiement utilisée.	LyraPaymentMethods.ALL

4. Pour définir la méthode de paiement à utiliser, utilisez une des valeurs de PAYMENT_METHOD_TYPE :

   Clés	Description
   LyraPaymentMethods.ALL	Permet d'ouvrir une fenêtre modale pour sélectionner les moyens de paiement disponibles en appelant la méthode Lyra.process(). Valeur par défaut.
   LyraPaymentMethods.GOOGLE_PAY	Permet de déclencher automatiquement un paiement Google Pay en appelant la méthode Lyra.process().
   LyraPaymentMethods.CARD	Permet de déclencher automatiquement un paiement par carte en appelant la méthode Lyra.process().

    val options = hashMapOf(Lyra.CUSTOM_PAY_BUTTON_LABEL to "MyPayButtonLabel", Lyra.CUSTOM_HEADER_LABEL to "MyHeaderLabel")            
    Lyra.process(supportFragmentManager, formToken, object : LyraHandler {
        override fun onSuccess(lyraResponse: LyraResponse) {
            verifyPayment(lyraResponse)
        }

        override fun onError(lyraException: LyraException, lyraResponse: LyraResponse?) {
            Toast.makeText(
                applicationContext,
                "Payment fail: ${lyraException.errorMessage}",
                Toast.LENGTH_LONG
            ).show()
        }
    }, options)

    val options = hashMapOf(Lyra.CUSTOM_PAY_BUTTON_LABEL to "MyPayButtonLabel", Lyra.CUSTOM_HEADER_LABEL to "MyHeaderLabel")
    Lyra.INSTANCE.process(getSupportFragmentManager(), formToken, new LyraHandler() {
        @Override
        public void onSuccess(LyraResponse lyraResponse) {
            verifyPayment(lyraResponse);
        }

        @Override
        public void onError(LyraException e, LyraResponse lyraResponse) {
            Toast.makeText(getApplicationContext(), "Payment fail: " + e.getErrorMessage(), Toast.LENGTH_LONG).show();
        }
    }, options);

Le SDK mobile vérifie la cohérence du formToken et affiche les moyens de paiement disponibles.

3.3 Intégrer Google Pay

Principe de fonctionnement

Prérequis

Pour intégrer Google Pay via notre SDK mobile, vous devez :

• Souscrire à l'offre Lyra incluant Google Pay. Contactez votre interlocuteur commercial.
• Paramétrer votre contrat Google Pay. [Consultez le guide d'intégration Google Pay](/fr-FR/payment-method/googlepay/redirection-form/sitemap.html).
• Appliquer les prérequis sur l'intégration du SDK mobile.
• Avoir dans votre application, une version minSdkVersion de 21 au minimum.
• Avoir dans votre application, une version compileSdkVersion de 34 au minimum.
• Ajoutez la dépendance Google ci-dessous dans le build.gradle :

  implementation "com.google.android.gms:play-services-wallet:19.4.0"
• Ajoutez la métadonnée suivante à l'élément application du fichier Android.Manifest.xml :

  <meta-data android:name="com.google.android.gms.wallet.api.enabled" android:value="true"/>

Choisir comment afficher le bouton Google Pay avec le SDK mobile

Si vous avez déjà intégré le formulaire de paiement via notre SDK mobile, le bouton Google Pay s'affichera directement dans le parcours d'achat lorsque l'acheteur clique sur Payer.

Pour ajouter un bouton de paiement direct Google Pay dans votre application :

1. Positionez un bouton Google Pay dans votre fichier xml.

   <com.google.android.gms.wallet.button.PayButton android:id="@+id/googlePayButton" android:layout_width="match_parent" android:layout_height="match_parent"/>
2. Ajoutez la gestion de ce bouton dans votre onCreate.

   // Add Google Pay Button
   
         val googlePayButton = binding.googlePayButton       
         googlePayButton.initialize(            
         ButtonOptions
            .newBuilder()
            .setButtonType(ButtonConstants.ButtonType.PLAIN)
            .setAllowedPaymentMethods(Lyra.getAllowedPaymentMethodsMock())
            .build()
         )
3. Gérez le clic sur le bouton Google Pay en valorisant l'option options[Lyra.PAYMENT_METHOD_TYPE] = LyraPaymentMethods.GOOGLE_PAY.

   googlePayButton.setOnClickListener
         {
         // TODO Call the merchant server to creates the session on server and retrieves
         // the payment information necessary to continue the process
         val options = HashMap<String, Any>()
         options[Lyra.PAYMENT_METHOD_TYPE] = LyraPaymentMethods.GOOGLE_PAY
         Lyra.process(supportFragmentManager, formToken, LyraHandler, options)
         }

Déployer en production

Pour passer en production, vous devez :

• déployer votre application sur la plateforme Play Store,
• suivre les recommandations listées dans cette page de la documentation Google Developer.

3.4 Procéder au paiement

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

Pour passer en mode production, consultez la procédure.

4. Analyser le résultat du paiement

La plateforme de paiement envoie le résultat du paiement :

• au SDK mobile en envoyant un objet LyraResponse à l'une des fonctions de callback onSuccess ou onError
• au serveur marchand en appelant l'IPN. Nécessite le paramétrage des règles de notification.

4.1 Structure de la réponse

L'objet LyraResponse ainsi que l'objet JSON transmis dans l'IPN contiennent les données ci-dessous :

{
   "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 tous les champs et leur description dans le playground.

4.2 Analyser le résultat transmis à l'application

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

1. L'application mobile transmet l'objet LyraResponse au serveur marchand.

2. Le serveur marchand calcule 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 : SHA-256
   • Clé secrète : Clé HMAC-SHA-256 (3^e clé du tableau des clés API REST)
   • Base d'encodage : héxadécimale (base 16)

   Si la valeur du kr-hash calculée par le serveur marchand est égale à celle contenue dans l'objet LyraResponse, alors le message est authentique.

3. Le serveur marchand vérifie le statut du paiement (voir : références de status).
4. Le serveur marchand communique le résultat à l'application mobile pour qu'elle l'affiche à l'acheteur.

    requestQueue.add(JsonObjectRequest(Request.Method.POST,
    "${SERVER_URL}/verifyResult",
    payload,
    Response.Listener { response ->
        //Check the response integrity by verifying the hash on your server
        Toast.makeText(
            applicationContext,
            "Payment success",
            Toast.LENGTH_LONG
        ).show()
    },
    Response.ErrorListener { error ->
        //Manage error here, please refer to the documentation for more information
        Toast.makeText(
            applicationContext,
            "Payment verification fail",
            Toast.LENGTH_LONG
        ).show()
    }
    ))

    requestQueue.add(new JsonObjectRequest(Request.Method.POST, SERVER_URL + "/verifyResult", response, new Response.Listener<JSONObject>() {
        @Override
        public void onResponse(JSONObject response) {
            //Check the response integrity by verifying the hash on your server
            Toast.makeText(getApplicationContext(), "Payment Success", Toast.LENGTH_LONG).show();
        }
    }, new Response.ErrorListener() {
        //Error when verifying payment
        @Override
        public void onErrorResponse(VolleyError error) {
            //Manage error here, please refer to the documentation for more information
            Toast.makeText(getApplicationContext(), "Payment verification fail", Toast.LENGTH_LONG).show();
        }
    }));

4.3 Analyser le résultat depuis l'IPN

Voir : Analyse de l'IPN (URL de notification).

4.4 Gérer les erreurs

Voir : Codes d'erreur.

Messages Sentry

En cas d'erreur, le SDK mobile peut envoyer des messages Sentry. Ces données sont transférées de manière sécurisée.

Si votre minSdkVersion est inférieur ou égal à 23, modifiez le build.gradle de votre application pour recevoir les messages Sentry :

// only if your minSdkVersion <= 23
android {
    compileOptions {
        // Flag to enable support for the new language APIs
        coreLibraryDesugaringEnabled = true
        // Sets Java compatibility to Java 8
        sourceCompatibility = JavaVersion.VERSION_1_8
        targetCompatibility = JavaVersion.VERSION_1_8
    }
}
dependencies {
    // Needed by coreLibraryDesugaringEnabled compileOptions
    coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:1.1.5")
}

Pour plus d'informations, consultez [cette procédure](https://developer.android.com/studio/write/java8-support).