Integración del Plugin Khipu para Capacitor

Introducción

El Plugin de Khipu para Capacitor ofrece una solución integral para desarrolladores que desean implementar un sistema de pago nativo dentro de sus aplicaciones multiplataforma basados en Capacitor. Este plugin 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 Plugin de Khipu para Capacitor, proporcionas una experiencia de usuario coherente y segura, similar a la ofrecida por la versión web de Khipu. Además, este plugin 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 en Capacitor : Debes tener una aplicación móvil desarrollada para Capacitor.
  3. Versión mínima de Capacitor : El plugin ha sido probado con versiones 6 o superiores de Capacitor.

Instalación

Copy
Copied
npm install capacitor-khipu
npx cap sync

Configuración para Android

Repositorio principal de Khipu

Para que Android pueda localizar el archivo aar de khenshin, necesitas agregar el repositorio maven de khenshin a la sección allprojects del archivo android/build.gradle.

Algo así:

Copy
Copied
allprojects {
    repositories {
        google()
        mavenCentral()
        maven { url 'https://dev.khipu.com/nexus/content/repositories/khenshin' }
    }
}

Ten en cuenta que los repositorios google() y mavenCentral() generalmente ya están agregados.

Jetpack Compose y Kotlin

El cliente de Khipu para Android utiliza la tecnología Jetpack Compose, para ello es necesario habilitar el plugin de Kotlin.

En el archivo android/build.gradle agrega el classpath para el artefacto org.jetbrains.kotlin:kotlin-gradle-plugin:<version>

Copy
Copied
buildscript {
    
    repositories {
        google()
        mavenCentral()
    }
    dependencies {
        classpath 'com.android.tools.build:gradle:8.2.1'
        classpath 'com.google.gms:google-services:4.4.0'
        classpath 'org.jetbrains.kotlin:kotlin-gradle-plugin:1.9.0'

        // NOTA: No coloques las dependencias de tu aplicación aquí; estas pertenecen
        // a los archivos build.gradle de los módulos individuales.
    }
}

Ten en cuenta que los classpath para com.android.tools.build:gradle:<version> y com.google.gms:google-services:<version> generalmente ya están allí.

Luego, en el archivo android/app/build.gradle agrega el plugin en la parte superior del archivo

Copy
Copied
apply plugin: 'com.android.application'
apply plugin: 'org.jetbrains.kotlin.android'

Ten en cuenta que el plugin com.android.application generalmente ya está allí.

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 *;
}

Autorización para abrir otras aplicaciones

Khipu abre automáticamente las apps bancarias cuando se requiere autorización reforzada (2FA), para poder hacer eso, tu app debe declarar cuales son las apps bancarias que se podrían abrir, para esto es necesario agregar el tag <queries> como un elemento hijo dentro del tag <manifest> en el archivo AndroidManifest.xml:

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>

Configuración para iOS

Al igual que en Android, en iOS, es esencial definir adecuadamente las URLs de las otras apps que se pueden abrir desde Khipu en el archivo Info.plist, para esto se debe agregar la llave LSApplicationQueriesSchemes que en Xcode se ve como Queried URL Schemes con un arreglo de String con cada URL de app bancaria.

Importante

Para el caso de Chile son las siguientes:

Copy
Copied
  <key>LSApplicationQueriesSchemes</key>
  <array>
    <string>bancochilemipass2</string>
    <string>BciPassApp</string>
    <string>BICEPassApp</string>
    <string>keypass</string>
    <string>SantanderPassApp</string>
    <string>tupass</string>
    <string>bancoestado</string>
    <string>itau.cl</string>
    <string>SecurityPass</string>
  </array>

API

startOperation(...)

Copy
Copied
startOperation(options: StartOperationOptions) => Promise<KhipuResult>
Parámetro Tipo
options StartOperationOptions

Devuelve: Promise<KhipuResult>


Interfaces

KhipuResult

Propiedad Tipo
operationId string
exitTitle string
exitMessage string
exitUrl string
result 'OK' | 'ERROR' | 'WARNING' | 'CONTINUE'
failureReason string
continueUrl string
events KhipuEvent[]

KhipuEvent

Propiedad Tipo
name string
timestamp string
type string

StartOperationOptions

Propiedad Tipo
operationId string
options KhipuOptions

KhipuOptions

Propiedad Tipo
locale string
title string
titleImageUrl string
skipExitPage boolean
theme 'light' | 'dark' | 'system'
colors KhipuColors

KhipuColors

Propiedad Tipo
lightBackground string
lightOnBackground string
lightPrimary string
lightOnPrimary string
lightTopBarContainer string
lightOnTopBarContainer string
darkBackground string
darkOnBackground string
darkPrimary string
darkOnPrimary string
darkTopBarContainer string
darkOnTopBarContainer string