Integración del Cliente Khipu para Android
Introducción
El Cliente de Khipu para Android ofrece una solución integral para desarrolladores que desean implementar un sistema de pago nativo dentro de sus aplicaciones móviles Android. Este SDK permite incorporar un método de pago directamente en la aplicación, evitando la necesidad de redirigir a los usuarios a una página web externa. Al integrar el Cliente de Khipu para Android, proporcionas una experiencia de usuario coherente y segura, similar a la ofrecida por la versión web de Khipu. Además, este SDK incluye funcionalidades avanzadas como openApp
, que permite a los usuarios acceder directamente a sus aplicaciones bancarias para validar pagos, optimizando el proceso de pago y mejorando la experiencia general del usuario.
Pre-requisitos
- Cuenta de Cobrador en Khipu : Debes tener una cuenta de cobrador en khipu.com . Puedes optar por una cuenta regular o una en "modo desarrollador". Ambas cuentas operan de manera similar en términos de creación, autorización y conciliación de pagos, pero en el "modo desarrollador" se utilizan bancos y dinero ficticios. Es recomendable utilizar una cuenta en "modo desarrollador" durante el desarrollo y pruebas, y cambiar a una cuenta regular al pasar a producción.
- Aplicación móvil para Android : Debes tener una aplicación móvil desarrollada para Android.
- Versión mínima del SDK : La aplicación debe soportar como mínimo la versión 21 del SDK de Android.
Incorporar Khipu al proyecto
Agregar el Repositorio de Khipu
Se requiere agregar el repositorio de Khipu en tu archivo build.gradle
a nivel de proyecto en la sección repositories
:
allprojects {
repositories {
maven { url "https://dev.khipu.com/nexus/content/repositories/khenshin" }
}
}
Agregar la Dependencia
Para utilizar la API de Khipu, necesitas incluir la biblioteca en tu proyecto. Agrega la siguiente dependencia en el archivo build.gradle
de tu módulo (no el de nivel de proyecto):
dependencies {
implementation 'com.khipu:khipu-client-android:+' // + trae la versión mas nueva del SDK, la recomendación es en producción fijar a una versión definida al pasar a producción
}
Configuración para Proguard
Si tu proyecto usa proguard y tiene un configuración muy agresiva es posible que tengas probelmas al generar el APK
en modo release
. Para corregir esto incluye la siguiente regla en tu archivo proguard-rules.pro
.
-keep public class com.khipu.client.**{
public protected *;
}
Entrada
A continuación se definen los parametros necesarios para iniciar la API.
Documentación de Khipu.getKhipuLauncherIntent
getKhipuLauncherIntent
es una función que crea un Intent
para iniciar el proceso de pago utilizando el SDK de Khipu. Este Intent
es esencial para lanzar la actividad de pago de Khipu.
Parámetros
-
context
:
Context
El contexto de la aplicación, utilizado para acceder a los recursos y servicios del entorno de la app. -
operationId
:
String
El identificador único de la intención de pago -
options
:
KhipuOptions
Configuraciones para personalizar la interfaz y el comportamiento del proceso de pago, definidas medianteKhipuOptions.Builder()
.-
header
:
KhipuHeader
(Opcional)
Configura la cabecera de la actividad de pago con elementos como títulos y logos. -
topBarTitle
:
String
Título para la barra superior durante el proceso de pago. -
topBarImageResourceId
:
Int
(Opcional)
Imagen en la barra superior. -
skipExitPage
:
Boolean
Si es verdadero, se omite la página al final del proceso de pago, ya sea exitosa o fallida. -
showFooter
:
Boolean
Si es verdadero, se muestra un mensaje en la parte inferior con el logo de Khipu. -
theme
:
KhipuOptions.Theme
Tema de la interfaz, puede ser:- .SYSTEM : Se usa el tema oscuro/claro dependiendo de la configuración del dispositivo
- .LIGHT : Se utiliza el tema claro
- .DARK : Se utiliza el tema oscuro
-
locale
:
String
Configuración regional para el idioma de la interfaz. El formato estándar que combina un código de idioma ISO 639-1 y un código de país ISO 3166. Por ejemplo,"es_CL"
para español de Chile. -
colors
:
KhipuColors
Permite personalizar los colores de la interfaz de usuario.
-
header
:
Documentación de KhipuColors
KhipuColors
facilita la personalización de los colores en la interfaz de usuario del proceso de pago.
Parámetros
-
lightTopBarContainer
:
String
(Opcional)
Color de fondo para la barra superior en modo claro. -
lightOnTopBarContainer
:
String
(Opcional)
Color de los elementos en la barra superior en modo claro. -
lightPrimary
:
String
(Opcional)
Color primario en modo claro. -
lightOnPrimary
:
String
(Opcional)
Color de los elementos sobre el color primario en modo claro. -
lightBackground
:
String
(Opcional)
Color de fondo general en modo claro. -
lightOnBackground
:
String
(Opcional)
Color de los elementos sobre el fondo general en modo claro. -
darkTopBarContainer
:
String
(Opcional)
Color de fondo para la barra superior en modo oscuro. -
darkOnTopBarContainer
:
String
(Opcional)
Color de los elementos en la barra superior en modo oscuro. -
darkPrimary
:
String
(Opcional)
Color primario en modo oscuro. -
darkOnPrimary
:
String
(Opcional)
Color de los elementos sobre el color primario en modo oscuro. -
darkBackground
:
String
(Opcional)
Color de fondo general en modo oscuro. -
darkOnBackground
:
String
(Opcional) Color de los elementos sobre el fondo general en modo oscuro.
Esta configuración permite adaptar visualmente el proceso de pago a la estética de la aplicación móvil.
Configuración de OpenApp
Para asegurar que la aplicación OpenApp funcione correctamente y pueda abrir las aplicaciones bancarias, es esencial definir adecuadamente las queries en el archivo AndroidManifest.xml
.
Definición de Queries en el Manifest
A continuación se explica cómo configurar las queries en el archivo AndroidManifest.xml
para permitir que tu aplicación interactúe con aplicaciones bancarias específicas. Es necesario agregar el tag <queries>
como un elemento hijo dentro del tag <manifest>
:
Importante
Para el caso de Chile son las siguientes:
<queries>
<package android:name="cl.bci.pass" />
<package android:name="cl.bancochile.mi_pass2" />
<package android:name="net.veritran.becl.prod" />
<package android:name="cl.scotiabank.keypass" />
<package android:name="cl.santander.santanderpasschile" />
<package android:name="com.konylabs.ItauMobileBank" />
<package android:name="cl.bancosecurity.securitypass" />
<package android:name="cl.bice.bicepassmobile2" />
<package android:name="cl.consorcio.tupass" />
</queries>
Invocación API
El siguiente es un ejemplo de invocación de la API
import com.khipu.client.KHIPU_RESULT_EXTRA
import com.khipu.client.KhipuOptions
import com.khipu.client.KhipuResult
import com.khipu.client.example.ui.theme.KhipuClientExampleTheme
import com.khipu.client.getKhipuLauncherIntent
//Creamos un lanzador de la actividad del cliente de khipu y definimos un callback para mostrar la respuesta
val khipuLauncher =
rememberLauncherForActivityResult(ActivityResultContracts.StartActivityForResult()) { result: ActivityResult ->
if (result.resultCode == Activity.RESULT_OK) {
val intent = result.data
val metadata = intent?.getSerializableExtra(KHIPU_RESULT_EXTRA) as KhipuResult
resultText = metadata.toString()
Log.v("TAG", metadata.asJson())
}
}
...
//Mas adelante, iniciamos la actividad
khipuLauncher.launch(
getKhipuLauncherIntent(
context = context,
operationId = text.value,
options = KhipuOptions.Builder()
.build()
)
)
Salida
A continuación se definen los parametros que retornara la API al terminar el proceso.
Documentación de KhipuResult
Retorno
-
operationId
:
String
El identificador único de la intención de pago -
exitTitle
:
String
Título que se mostrará al usuario en la pantalla de salida, reflejando el resultado de la operación. -
exitMessage
:
String
Mensaje que se mostrará al usuario, proporcionando detalles adicionales sobre el resultado de la operación. -
exitUrl
:
String
URL a la que retornará la aplicación al terminar el proceso. -
result
:
String
Resultado general de la operación, los valores posibles son:- OK : Éxito
- ERROR : Error
- WARNING : Advertencias
- CONTINUE : Operación necesita más pasos
-
failureReason
:
String
(Opcional) Describe la razón del fallo, si la operación no fue exitosa. -
continueUrl
:
String
(Opcional) Disponible solo cuando el resultado es "CONTINUE", que indica la URL a seguir para continuar la operación. -
events
:
Array
Pasos realizados para generar el pago, con sus estampas de tiempo