Guía de integración para Android
- Añadir el SDK de pago a su aplicación
- Inicializar el SDK
- Realizar un pago
- Verificar el estado de la transacción
En esta página encontrará cómo:
- Consultar nuestros ejemplos de integración
- Personalizar el SDK
- Cancelar un pago en curso
- Habilitar la funcionalidad NFC
- Deshabilitar la funcionalidad de escaneo de tarjeta con la cámara
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
Para agregar el SDK de pago a su aplicación, debe añadir la siguiente dependencia a su build.gradle
, :
implementation 'com.lyra:sdk:1.6.+'
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
Optimizar la eficacia de nuestro 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.
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") }
Inicializar el 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 :
CARACTERÍSTICAS | Formato | Descripción |
---|---|---|
publicKey | String | Votre clé publique (disponible dans le |
options | HashMap | Map permettant de configurer le SDK: NFC, scan de la carte |
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 | 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 |
Realizar un pago
La réalisation d'un paiement se décline en 2 étapes : l'initialisation de l'affichage du formulaire et le traitement du paiement proprement dit.
Inicialización de la visualización del formulario de pago
Cuando el usuario decide pagar, puede inicializar la visualización del formulario de pago.
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.
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(); } }));
- La etapa de validación del carrito es una etapa crucial, y es su responsabilidad verificar en sus servidores que el monto corresponde bien al carrito antes de enviárnoslo.
- Llamar al Web Service 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
Une fois le formToken
reçu dans l'application mobile, vous devez le transmettre à notre SDK de paiement en appelant la méthode Lyra.process
avec les paramètres suivants :
CARACTERÍSTICAS | 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(); } });
Le paymentHandler
est une interface que vous devez implémenter et qui contient 2 méthodes :
Callback | Descripción |
---|---|
onSuccess | Se llama si el pago se ha realizado correctamente. |
onError | Cette méthode est appelée si le paiement est en échec ou n'a pu être initié. Cette situation peut se produire si une erreur fonctionnelle (le paiement a été refusé) ou technique est survenue pendant le paiement. Pour en savoir plus consulter: Gestion des erreurs. |
Description de l'objetLyraResponse
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.
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:
CARACTERÍSTICAS | 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 contenido en kr-answer. |
kr-answer | Objeto que contiene los objetos transacciones completos codificados en JSON |
L'objet kr-answer
contient les éléments décrits ici.
En algunos casos, puede que no se haya podido iniciar la transacción por el lado del servidor. El error devuelto por la API se encuentra en el json (consulte el formato 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,
- par l'appel du
paymentHandler
coté application mobile.
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.
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
Tema
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”.
Pour personnaliser les couleurs, il suffit de les définir dans votre fichier colors.xml :
<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>
Textos
Il est aussi possible de personnaliser certains textes. Pour cela, spécifier le paramètre optionnel "options" lors de l'appel au Lyra.process()
.
Botón PAGAR
- El texto del botón PAGAR puede personalizarse.
Especifique la clave Lyra.CUSTOM_PAY_BUTTON_LABEL
.
Cabecera
- 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 unorderIdest précisé alors on continuera à afficher "CommandeOrderId".
Especifique la clave Lyra.CUSTOM_HEADER_LABEL
.
Ventana de pago
- También se puede personalizar el texto de la ventana emergente que se abre al pulsar el botón PAGAR.
Especifique la clave 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"))
Cancelar un pago en curso
Il est possible d'annuler un paiement en cours en utilisant la méthode Lyra.cancelProcess()
. En général, cette méthode permet de quitter correctement le formulaire de paiement mais il existe différents scénarios :
- El proceso de pago puede cancelarse:
- el formulario de pago se cierra correctamente.
- el
handler onError
qui est passé auLyra.process()
est appelé avec l'erreurMOB_009 - Payment cancelled, indiquant que le processus de paiement a été annulé.
- Le processus de paiement ne peut pas être annulé. Si le
Lyra.cancelProcess()
est invoqué pendant que le SDK est en communication avec la plateforme de paiement (l'utilisateur vient de cliquer sur le bouton payer) :
- el formulario de pago permanece en pantalla.
- el
handler onError
qui est passé auLyra.process()
est appelé avec l'erreurMOB_013 - Payment cannot be cancelledindiquant que le processus de paiement ne peut pas être annulé. - el comportamiento normal del SDK continúa:
- si le paiement se termine correctement alors le
handler onSuccess
sera appelé. - si le paiement est en échec. Suivant l'erreur, le formulaire de paiement reste affiché ou le
handler onError
sera appelé.
- si le paiement se termine correctement alors le
- S'il n'y a pas de processus de paiement en cours, l'appel au
Lyra.cancelProcess()
n'aura aucun effet.
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:
- Lors de l'initialisation du SDK, envoyertruecomme valeur pour la clé
nfcEnabled
dans les options de configuration (VoirInicializar el SDK).
options[Lyra.OPTION_NFC_ENABLED] = true
options.put(Lyra.OPTION_NFC_ENABLED, true);
- Ajouter la permission suivante dans le fichier
AndroidManifest.xml
de votre application :
<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:
- Intégrer la librairie
CardsCameraRecognizer
dans votre projet Android en ajoutant la dépendance suivante à votrebuild.gradle
:
// Lyra Cards Camera Recognizer SDK
implementation 'com.lyra:cards-camera-recognizer:1.0.+'
- Lors de l'initialisation du SDK, envoyertruecomme valeur pour la clé
cardScanningEnabled
dans les options de configuration (VoirInicializar el 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" />