Android integration guide

• Add the the payment SDK to your application
• Initialize the SDK
• Make a payment
• Check the transaction status

This page provides information on how to:

• View our integration examples
• Customize the SDK
• Cancel a payment in progress
• Enable NFC feature
• Enable the card scanning feature

View our integration examples

You will find many examples of our SDK's integration codes in different languages in the Github repository.

Add the the payment SDK to your application

To add the payment SDK to your application, it is necessary to add the following dependency in your build.gradle, :

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

We recommend to regularly update the payment SDK in order to guarantee optimal security of your payments.

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

Optimize the efficiency of our support service

Our SDK can send Sentry messages to our servers when an unusual situation or problem occurs. In this case, no sensitive data is transferred nor any data from your application.

Uniquement si votre minSdkVersion est <= 23, il est alors nécessaire de suivre la procédure suivante https://developer.android.com/studio/write/java8-support afin de permettre aux devices Android <= 6 de bénéficier de l'envoi des messages sentry. Lors du filtrage des données sensibles, notre SDK utilise du code Java8.

En résumé, voici les modifications à apporter au build.gradle de votre application :

// 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")
}

Initialize the SDK

Comme mentionné dans le chapitre sur le fonctionnement de la solution, il est nécessaire d'effectuer l'initialisation du SDK au lancement de votre application, typiquement dans la méthode onCreate de votre activité principale.

Pour cela, il suffit d'appeler la méthode Lyra.initialize avec les paramètres suivants :

Example of a call:

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

The possible keys in this dictionary are:

Make a payment

Making a payment is divided into 2 steps: initializing the display of the form and processing the payment itself.

Initialize the display of the payment form

When the user decides to pay, you can initialize the payment form display.

Pour cela, vous devez appeler votre serveur marchand, pour y vérifier les achats de l'utilisateur, puis générer un identifiant de formulaire (appelé formToken) en appelant le Web Service Charge/createPayment (toujours depuis votre serveur marchand). Dans cette requête, vous devez passer un paramètre formTokenVersion qui correspond au résultat de la méthode getFormTokenVersion du SDK. La réponse du Web Service ou cet identifiant de formulaire doit ensuite être renvoyé à votre application mobile.

Here is a sample code based on the Android code examples and the provided merchant server.

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

• The step of shopping cart validation is crucial. You must also check on your servers that the amount matches the amount in the cart before transferring it to us.
• Calling the Web Service from the mobile application is amounts to making your call keys available to it (and to potential hackers), which is contrary to the security rules.

Displaying the payment screen

Once the formToken is received in the mobile app, you need to pass it to our Payment SDK by calling the Lyra.process method with the following parameters:

The SDK then checks the formToken consistency and displays the available payment methods.

Example of a call:

    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 paymentHandler est une interface que vous devez implémenter et qui contient 2 méthodes :

Object descriptionLyraResponse

Le même objet LyraResponse est retourné dans les deux cas : onSuccess et onError. C'est un objet de type JSONObject. En cas de succès, il est nécessaire de vérifier son intégrité avant d'afficher le résultat du paiement.

In case the transaction was initiated on the server side, it will be possible to simply retrieve the payment details.

Example: .

{
   "kr-hash":"80f5188e757c1828e8d4ccab87467eb50c4299e4057fa03b3f3185342f6d509c",
   "kr-hash-algorithm":"sha256_hmac",
   "kr-answer-type":"V4\/Payment",
   "kr-answer": "{
      "shopId":"65512466",
      "orderCycle":"CLOSED",
      "orderStatus":"PAID",
      "serverDate":"2019-03-01T10:54:45+00:00",
      "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,
            ...
         },
         "extraDetails":{
            "browserAccept":null,
            "fingerPrintId":null,
            "ipAddress":"77.136.84.251",
            "browserUserAgent":"{\"deviceName\":\"Xiaomi Mi MIX 2S\",\"os\":\"Android\",\"osVersion\":\"[9]\",\"sdkVersion\":28,\"isMobile\":true}",
            "_type":"V4\/Customer\/ExtraDetails"
         },
         "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",
            "creationDate":"2019-03-01T10:54:44+00:00",
            ...
         }
      ],
      "_type":"V4\/Payment"
   }"
}

The response contains the same elements as the ones sent in the IPN:

L'objet kr-answer contient les éléments décrits ici.

In some cases, it may be that the transaction could not be initiated on the server side. It will be possible to find the error returned by the API in the json (you can find the format here: Error codes ).

Check the transaction status

Once the payment has been finalized, regardless of whether was accepted or rejected, you will be notified in two 2 ways:

• via a call (IPN) to your merchant server, if you have correctly configured the notification rules,
• by the call ofpaymentHandlermobile application side.

Il est nécessaire de vérifier l'intégrité du message (voir ici pour plus de détails) et de lancer les traitements métiers coté serveur (lors de la réception de l'IPN).

Nos exemples de code fournissent un exemple de contrôle d'intégrité du message via votre serveur marchand. Il s'agit du endPoint verifyResult appelé dans la méthode verifyResult de l'application.

Here is a sample code based on the Android code examples and the provided merchant server.

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

Customize the SDK

Theme

It is possible to customize the SDK so that the views generated via the SDK (payment form) are displayed with the same colors and font as those used in your application.

You can define:

• One main color,
• A secondary color,
• the font to be used for all the texts that appear in the SDK.

The main color allows to modify:

• the header background color,
• The background color of the “Pay” button,
• the color of the word for closing the CVV tooltip pop-up,
• the color of the word for closing the brand selection pop-up,
• the color for highlighting the field and of its label when it is being edited,
• the color of the text in the payment in progress message,
• the color of the spinner in the current payment message.

The secondary color allows to change:

• the color of the arrow image for going back in the SDK header,
• the color of the texts in the SDK header,
• the text color of the “Pay” button.

To customize the colors, simply define them in your colors.xml file:

<color name="payment_sdk_PrimaryColor">#293C7A</color>
<color name="payment_sdk_SecondaryColor">#FFFFFF</color>

Pour personnaliser la police vous devez juste surcharger le style nécessaire dans le fichier styles.xml :

<style name="PaymentSDK_Theme">
    <item name="android:fontFamily"></i>casual</item></style>

Texts

It is also possible to personalize certain texts. To do this, specify the optional "options" parameter when calling the Lyra.process().

PAY button

• The text of the PAY button can be customized.

Specify the key Lyra.CUSTOM_PAY_BUTTON_LABEL.

Header

• Si le texte est forcé et qu'il n'y a pas d'orderId, il remplacera le texte par défaut qui est "Paiement" ou "Enregistrement de la carte".
• Par contre, si un orderId est précisé alors on continuera à afficher "Commande OrderId".

Specify the key Lyra.CUSTOM_HEADER_LABEL.

Payment popup

• The popup text that opens when clicked PAY button can also be customized.

Specify the key Lyra.CUSTOM_POPUP_LABEL.

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

Cancel a payment in progress

It is possible to cancel a payment in progress using the Lyra.cancelProcess() method. In general, this method exits the payment form correctly, but there are different scenarios:

1. The payment process can be cancelled:

• the payment form closes correctly.
• thehandler onErrorwho passed toLyra.process()is called with the errorMOB_009 - Payment cancelled, indicating that the payment process has been canceled.

2. Le processus de paiement ne peut pas être annulé. Si leLyra.cancelProcess()est invoqué pendant que le SDK est en communication avec la plateforme de paiement (l'utilisateur vient de cliquer sur le bouton payer) :

• the payment form remains displayed.
• thehandler onErrorwho passed toLyra.process()is called with the errorMOB_013 - Payment cannot be cancelledindicating that the payment process cannot be canceled.
• normal SDK behavior continues:
  • if the payment completes correctly then thehandler onSuccesswill be called.
  • if the payment is unsuccessful. Depending on the error, the payment form remains displayed or thehandler onErrorwill be called.

3. If there is no payment process in progress, callingLyra.cancelProcess()will have no effect.

Enable NFC feature

It is possible, in the SDK, to activate the NFC functionality. This feature allows a user not to enter his card information manually but to use NFC to scan it and automatically fill in the payment form.

To enable this feature, you need to:

1. When initializing the SDK, sendtrueas value for keynfcEnabledin the configuration options (SeeInitialize the SDK).

    options[Lyra.OPTION_NFC_ENABLED] = true

    options.put(Lyra.OPTION_NFC_ENABLED, true);

2. Add the following permission to the fileAndroidManifest.xmlof your application:

<uses-permission android:name="android.permission.NFC" />

Enable the card scanning feature

It is possible, in the SDK, to enable the card scanning functionality by camera. This feature allows a user to not enter his card information manually but use the camera of his mobile device to scan it and automatically fill in the payment form.

To enable this feature, you need to:

1. Integrate the libraryCardsCameraRecognizerin your Android project by adding the following dependency to yourbuild.gradle:

    // Lyra Cards Camera Recognizer SDK
    implementation 'com.lyra:cards-camera-recognizer:1.0.+'

2. When initializing the SDK, sendtrueas value for keycardScanningEnabledin the configuration options (SeeInitialize the SDK).

    options[Lyra.OPTION_CARD_SCANNING_ENABLED] = true

    options.put(Lyra.OPTION_CARD_SCANNING_ENABLED, true);

A noter que les permissions suivantes seront directement ajoutées dans le fichier AndroidManifest.xml lors de la compilation du projet :

<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.FLASHLIGHT" />
<uses-feature android:name="android.hardware.CAMERA" android:required="false" />
<uses-feature android:name="android.hardware.camera.AUTOFOCUS" android:required="false" />

Copyrights