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.+'

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

Paramètre	Format	Description	Exemple
publicKey	String	2^e clé du tableau des clés API REST	73239078:testpublickey_Zr3fXIKKx0mLY9YNBQEan42ano2QsdrLuyb2W54QWmUJQ
options	HashMap	Map pour configurer le comportement du SDK mobile ( NFC, scan de la carte).	Voir étape 2.

Configurez la Map options avec ces paramètres :

Clés	Format	Description	Exemple
apiServerName	String	1^e donnée du tableau des clés API REST. Obligatoire	https://api.systempay.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.

Exemple pour la boutique de démonstration

La fonction initialize est initialisée avec :

apiServerName valorisé à https://api.systempay.fr
publicKey valorisé à 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);

3. Réaliser un paiement

3.1 Créer un formToken

Requête

Depuis votre serveur marchand, appelez le Web Service Charge/CreatePayment en envoyant le contexte de paiement (montant, devise, numéro de commande, coordonnées de l'acheteur, etc.).

Pour des raison de sécurité et éviter des erreurs CORS, n'appelez pas le Web Service Charge/CreatePayment depuis votre application mobile.
Valorisez le paramètre formTokenVersion avec le résultat de la méthode getFormTokenVersion du SDK mobile.

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

Réponse

La réponse du Web Service Charge/CreatePayment contient un 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.).

Le formToken est utilisé pour afficher le formulaire dans l'étape suivante.

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

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.

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

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

Exemple de code

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

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 les fonctions de callback
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"
   }"
}

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

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

L'application mobile transmet l'objet LyraResponse au serveur marchand.
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.
Le serveur marchand vérifie le statut du paiement (voir : références de status).
Le serveur marchand communique le résultat à l'application mobile pour qu'elle l'affiche à l'acheteur.

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

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

Catégories

Tags