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:

Copy

Copied

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

Copy

Copied

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 problemas al generar el APK en modo release. Para corregir esto incluye la siguiente regla en tu archivo proguard-rules.pro.

Copy

Copied

-keep public class com.khipu.client.**{
    public protected *;
}

-keep class com.khipu.khenshin.protocol.** { *; }

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 mediante KhipuOptions.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.

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:

Copy

Copied

<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

Copy

Copied

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 : Se autorizó correctamente el pago en el banco de origen. El pago se está validando y se enviará una notificación por el servidor cuando este validado. ( Caso de prueba )
- ERROR : El pago no se autorizó correctamente, en exitMessage se encuentra el motivo a entregar al cliente y en failureReason el tipo de error. ( Caso de prueba )
- WARNING : El pago no se ha completado pero es posible que ocurra. Por ejemplo, el banco de origen tuvo un error al generar el comprobante de pago pero el dinero si se envió o faltan más firmantes en una transferencia de varios actores. Khipu comenzó el proceso de monitoreo de la cuenta de destino para validar el pago. ( Caso de prueba )
- CONTINUE : Operación necesita más pasos para que pago sea terminado. Por ejemplo, los pagos en Bancos Empresa que necesitan mas firmas. ( Caso de prueba )
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

Integración del Cliente Khipu para Android

Introducción

Pre-requisitos

Incorporar Khipu al proyecto

Agregar el Repositorio de Khipu

Agregar la Dependencia

Configuración para Proguard

Entrada

Documentación de Khipu.getKhipuLauncherIntent

Parámetros

Documentación de KhipuColors

Parámetros

Configuración de OpenApp

Definición de Queries en el Manifest

Importante

Invocación API

Salida

Documentación de KhipuResult

Retorno

Documentación de `Khipu.getKhipuLauncherIntent`

Documentación de `KhipuColors`

Documentación de `KhipuResult`