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

  1. 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.
  2. Aplicación móvil para Android : Debes tener una aplicación móvil desarrollada para Android.
  3. 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 probelmas 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 *;
}

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.
    • 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 : É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