Guía de integración para Android

En esta página encontrará cómo:

Con el fin de mejorar la eficacia de nuestro servicio de soporte, nuestro SDK puede enviar mensajes de Sentry a nuestros servidores cuando se presenta un problema o una situación inusual. En este caso, no se transfieren datos confidenciales ni datos de su aplicación.

Consultar nuestros ejemplos de integración

Encontrará varios ejemplos de códigos de integración de nuestro SDK en diferentes idiomas en el repositorio de Github.

Añadir el SDK de pago a su aplicación

Es necesario activar el multidex y la compatibilidad con Java 1.8:

android {
    defaultConfig {
        multiDexEnabled true
    }
    compileOptions {
        sourceCompatibility 1.8
        targetCompatibility 1.8
    }
}

Para añadir el SDK de pago a su solicitud, es necesario añadir la siguiente dependencia en su build.gradle :

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

Le recomendamos que actualice periódicamente el SDK de pago para asegurar un nivel de seguridad óptimo para sus pagos.

Para mantenerse informado de las nuevas versiones del SDK, consulte periódicamente nuestro repositorio de GitHub.

Inicializar el SDK

Como se menciona en el capítulo sobre el funcionamiento de la solución, es necesario inicializar el SDK al iniciar su aplicación, generalmente con el método “onCreate” de su actividad principal.

Para hacerlo, simplemente llame al método Lyra.initialize con los siguientes parámetros:

Parámetro Formato Descripción
publicKey String Votre clé publique (disponible dans le Back Office Expert : Paramètres -> Boutique -> Clés de l’API REST, cf. la página Prerrequisitos).
options HashMap Map para configurar el SDK: NFC, escaneo de la tarjeta,

Ejemplo de llamada:

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

Las claves posibles en este diccionario son:

Claves Formato del valor Descripción Obligatorio
apiServerName String Nom du serveur de l’API REST (disponible dans le Back Office Expert : Paramètres -> Boutique-> Clés de l’API REST), cf. la página Prerrequisitos). Obligatorio
cardScanningEnabled Bool Habilita/Deshabilita la funcionalidad de escaneo de la tarjeta utilizando la cámara. Si no se define, la funcionalidad se deshabilitará. Opcional
nfcEnabled Bool Habilita/Deshabilita la funcionalidad de escaneo de la tarjeta mediante NFC. Si no se define, la funcionalidad se deshabilitará. Opcional

Atención: este método puede devolver un error si ha fallado la inicialización del SDK. Consulte la página Control de errores para resolver la situación. También debe tener en cuenta que el SDK no permite que se ejecuten múltiples procesos en paralelo. Durante el procesamiento de la primera llamada, las demás llamadas serán ignoradas (no habrá callbacks ni excepciones).

Realizar un pago

La realización de un pago se divide en 2 etapas: la inicialización de la visualización del formulario y el procesamiento del pago en sí.

Inicialización de la visualización del formulario de pago

Cuando el usuario decide pagar, puede inicializar la visualización del formulario de pago.

Para ello, debe llamar a su servidor del vendedor para comprobar las compras del usuario y generar un identificador de formulario (llamado formToken) llamando al servicio web Charge/CreatePayment (desde su servidor del vendedor). En esta solicitud, debe pasar un parámetro formTokenVersion que corresponde al resultado del método getFormTokenVersion del SDK. A continuación, debe reenviar la respuesta del servicio web o el identificador del formulario a su aplicación móvil.

El siguiente código de ejemplo se basa en los ejemplos de código Android y el servidor del vendedor a su disposición.

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

Importante: no llame al servicio web Charge/CreatePayment desde su aplicación móvil.

  • La validación del carrito es una etapa crucial: usted es responsable de comprobar en sus servidores que el monto corresponde al carrito antes de enviárnoslo.
  • Llamar al servicio web desde la aplicación móvil significa poner sus claves de llamadas a su disposición (y a disposición de posibles piratas informáticos), lo que va en contra de las normas de seguridad.

Visualización de la pantalla de pago

Una vez que la aplicación móvil haya recibido el formToken, debe transmitirlo a nuestro SDK de pago llamando el método Lyra.process con los siguientes parámetros:

Parámetro Formato Descripción
supportFragmentManager FragmentManager Referencia a su IU para que el SDK pueda mostrar el formulario de pago.
formToken String El formToken, extraído de la respuesta del createPayment llamado anteriormente.
paymentHandler LyraHandler Callback para procesar el resultado del pago.

El SDK se encarga de verificar la coherencia del formToken antes de mostrar los medios de pago disponibles.

Ejemplo de llamada:

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

paymentHandler es una interfaz que debe implementar y que contiene 2 métodos:

Callback Descripción
onSuccess Se llama si el pago se ha realizado correctamente.
onError Se llama a este método si el pago falló o no se pudo iniciar. Esta situación puede ocurrir si se produjo un error funcional (pago rechazado) o técnico durante el pago. Para más información, consulte: Control de errores.

Descripción del objeto LyraResponse

Se devuelve el mismo objeto LyraResponse en ambos casos: onSuccess y onError. Es un objeto de tipo JSONObject. En caso de éxito, es necesario comprobar su integridad antes de mostrar el resultado del pago.

En caso de que la transacción haya sido iniciada por el lado del servidor, es posible obtener la información del pago de manera sencilla.

Ejemplo:

{
   "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"
   }"
}
            

La respuesta contiene los mismos elementos que los enviados en la IPN:

Parámetro Descripción
kr-hash Hash del objeto JSON almacenado en kr-answer. Así podrá confirmar la autenticidad de la respuesta
kr-hash-algorithm Algoritmo utilizado para calcular el hash
kr-hash-key Clave utilizada para firmar kr-answer
kr-answer-type Tipo del objeto JSON almacenado en kr-answer
kr-answer Objeto que contiene los objetos transacciones completos codificados en JSON

El objeto kr-answer contiene los elementos descritos aquí.

En algunos casos, puede que no se haya podido iniciar la transacción por el lado del servidor. Encontrará el error devuelto por la API en el json (cuyo formato encontrará aquí: Códigos de error ).

Verificar el estado de la transacción

Una vez el pago finalizado, haya sido aceptado o rechazado, se le notificará de dos maneras:

  • mediante una llamada (IPN) a nuestro servidor comercial, si configuró las reglas de notificaciones correctamente,
  • mediante llamada del paymentHandler del lado de la aplicación móvil.

Es necesario comprobar la integridad del mensaje (consulte aquí para obtener más detalles) e iniciar el procesamiento comercial del lado servidor (al recibir la IPN).

Nuestros ejemplos de código proporcionan un ejemplo de comprobación de la integridad de los mensajes a través de su servidor de vendedor: el endPoint verifyResult llamado en el método verifyResult de la aplicación.

El siguiente código de ejemplo se basa en los ejemplos de código Android y el servidor del vendedor a su disposición.

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

Personalizar el SDK

Se puede personalizar el SDK de modo que las vistas generadas desde el SDK (formulario de pago) se muestren en los mismos colores y la misma fuente que las utilizadas en su aplicación.

Puede definir:

  • un color principal,
  • un color secundario,
  • la fuente a utilizar en todos los textos que se muestran en el SDK.

El color principal permite modificar:

  • el color de fondo del encabezado,
  • el color de fondo del botón “Pagar”,
  • el color del mensaje de cierre de la ventana emergente de ayuda sobre el CVV,
  • el color del mensaje de cierre de la ventana emergente de ayuda sobre la elección de la marca,
  • el color de resalte y descripción del campo cuando se edita,
  • el color del texto en el mensaje de pago en curso,
  • el color del indicador giratorio en el mensaje de pago en curso.

El color secundario permite modificar:

  • El color del logotipo de la flecha de retroceso en el encabezado del SDK,
  • el color de los textos en el encabezado del SDK,
  • el color del texto en el botón “Pagar”.

Para personalizar los colores, sólo tienes que definirlos en el archivo colores.xml :

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

Para personalizar la fuente sólo tienes que definir el estilo necesario en el archivo styles.xml :

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

Habilitar la funcionalidad NFC

En el SDK, es posible habilitar la funcionalidad NFC. Esta característica le evita al usuario tener que ingresar la información de la tarjeta manualmente, y en su lugar, le permite escanearla mediante NFC y completar automáticamente el formulario de pago.

Para habilitar esta funcionalidad, debe:

  1. Al inicializar el SDK, envíe true como valor para la clave nfcEnabled en las opciones de configuración (consulte Inicialización del SDK).

     options[Lyra.OPTION_NFC_ENABLED] = true
                 
     options.put(Lyra.OPTION_NFC_ENABLED, true);
                 
  2. Añadir el siguiente permiso en el archivo AndroidManifest.xml de su aplicación:

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

Deshabilitar la funcionalidad de escaneo de tarjeta con la cámara

En el SDK, es posible habilitar la funcionalidad de escaneo de la tarjeta mediante cámara. Esta característica le evita al usuario tener que ingresar la información de la tarjeta manualmente, y en su lugar usar la cámara de su dispositivo móvil para escanearla y completar automáticamente el formulario de pago.

Para habilitar esta funcionalidad, debe:

  1. Integrar la biblioteca CardsCameraRecognizer en su proyecto Android añadiendo la siguiente dependencia a su build.gradle:
    // Lyra Cards Camera Recognizer SDK
    implementation 'com.lyra:cards-camera-recognizer:1.0.+'
  1. Al inicializar el SDK, envíe true como valor para la clave cardScanningEnabled en las opciones de configuración (consulte Inicialización del SDK).

     options[Lyra.OPTION_CARD_SCANNING_ENABLED] = true
                 
     options.put(Lyra.OPTION_CARD_SCANNING_ENABLED, true);
                 

Tenga en cuenta que los permisos siguientes se añadirán automáticamente al archivo AndroidManifest.xml durante la compilación del proyecto:

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

Derechos de autor