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	2e clé du tableau des clés API REST	42229744:testpublickey_tPXxrUVsoGkggk9LuO8o0PBRdWg8jWUhWmYMURwCbc8ap
   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	1e 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
   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

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

(*) Le paymentHandler est une interface à implémenter avec 2 méthodes :

(**) Les options possibles pour personnaliser le paiement :

(***) Liste des méthodes de paiement PAYMENT_METHOD_TYPE :

Exemple d'utilisation des options :

val options = hashMapOf(Lyra.CUSTOM_PAY_BUTTON_LABEL to "MyPayButtonLabel", Lyra.CUSTOM_HEADER_LABEL to "MyHeaderLabel", Lyra.CUSTOM_POPUP_LABEL to "MyPopupLabel")
Lyra.process(supportFragmentManager, formToken, LyraHandler, options)

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

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

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

3.3 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 dans un objet JSON LyraResponse :

• vers la fonction callback onSuccess ou onError, côté application mobile.

• vers une IPN, appel de serveur à serveur. Nécessite le paramétrage des règles de notification.

4.1 Structure 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.

4.2 Analyser le résultat, côté application

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

1. Récupérez le JSON envoyé par la plateforme de paiement

2. 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.

3. Vérifiez le statut du paiement (voir : références de status).

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

       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).

D. Gérer les erreurs

Voir : Codes d'erreur.

Optimisation du support

Le SDK mobile peut envoyer des messages Sentry en cas de problème. Ces données sont transférées en toute sécurité.

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).