Guide d'intégration Android

• Ajouter le SDK de paiement à votre application
• Initialiser le SDK
• Réaliser un paiement
• Analyser le résultat du paiement

Ajouter le SDK de paiement à votre application

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

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

Nous vous conseillons de mettre à jour régulièrement le SDK de paiement, afin de garantir une sécurité optimale de vos paiements.

Pour être tenu informé des nouvelles versions du SDK, vous pouvez consulter régulièrement notre repository GitHub .

Initialiser le SDK

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

Dans la Map options, utilisez ces paramètres :

Exemple pour la boutique DEMO

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

• apiServerName par https://api.systempay.fr
• publicKey par 73239078:testpublickey_Zr3fXIKKx0mLY9YNBQEan42ano2QsdrLuyb2W54QWmUJQ

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

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

Exemple avec la génération du 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();
        }
    }));

B. 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 :

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

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.

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

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 .

Optimisation du support

Notre SDK 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 <= 23, suivez cette procédure https://developer.android.com/studio/write/java8-support, modifiez le build.gradle de votre application pour bénéficier de l'envoi des 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")
}

Copyrights