Integración del Plugin Khipu para React Native

Introducción

El Plugin de Khipu para React Native ofrece una solución integral para desarrolladores que desean implementar un sistema de pago nativo dentro de sus aplicaciones multiplataforma basados en React Native. 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 React Native, 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 React Native : Debes tener una aplicación móvil desarrollada para React Native.
3. Versión mínima de React Native : El plugin ha sido probado con versiones 0.71 o superiores de React Native.

Instalación

npm install react-native-khipu

o

yarn add react-native-khipu

Android

Añade el repositorio de Khipu a la sección allprojects del archivo android/build.gradle. Además, Khipu necesita que el plugin de kotlin gradle sea, al menos, versión 1.9.0 y con eso compilar contra el SDK de Android 34, por lo que asegúrate de que el archivo android/build.gradle se vea así:

buildscript {
    ext {
        buildToolsVersion = "34.0.0"
        minSdkVersion = 21
        compileSdkVersion = 34
        targetSdkVersion = 34

        // Usamos NDK 23, que tiene soporte para M1 y es la versión NDK side-by-side de AGP.
        ndkVersion = "23.1.7779620"
    }
    repositories {
        google()
        mavenCentral()
    }
    dependencies {
        classpath("com.android.tools.build:gradle:7.3.1")
        classpath("com.facebook.react:react-native-gradle-plugin")
        classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:1.9.0")
    }
}

allprojects {
    repositories {
        maven { url 'https://dev.khipu.com/nexus/content/repositories/khenshin' }
    }
}

Si estás utilizando jetifier, excluye el paquete jackson-core en el archivo android/gradle.properties:

android.jetifier.ignorelist = jackson-core

Además, asegúrate que el plugin kotlin esté habilitado en tu app. Para esto revisa que en archivo android/app/build.gradle esté aplicado el plugin:

apply plugin: 'kotlin-android'

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.

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

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

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:

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

iOS

Instala las dependencias de cocoapods:

cd ios
pod install --repo-update
cd ..

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.

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

Uso

import {
  type KhipuColors,
  type KhipuOptions,
  type KhipuResult,
  startOperation,
} from 'react-native-khipu';

// ...

const result: KhipuResult = await startOperation({
  operationId: '<paymentId>',
  options: {
    title: '<Title to display in the payment process>', // Título para la barra superior durante el proceso de pago.
    titleImageUrl: '<Image to display centered in the topbar>', // URL de la imagen para mostrar en la barra superior.
    locale: 'es_CL', // Configuración regional para el idioma de la interfaz. El formato estándar 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 (Chile).
    theme: 'light', // El tema de la interfaz, puede ser 'dark', 'light' o 'system'.
    skipExitPage: false, // Si es verdadero, omite la página de salida al final del proceso de pago, ya sea exitoso o fallido.
    colors: {
      lightTopBarContainer: '<colorHex>', // Color de fondo opcional para la barra superior en modo claro.
      lightOnTopBarContainer : '<colorHex>', // Color opcional de los elementos en la barra superior en modo claro.
      lightPrimary : '<colorHex>', // Color primario opcional en modo claro.
      lightOnPrimary : '<colorHex>', // Color opcional de los elementos en el color primario en modo claro.
      lightBackground : '<colorHex>', // Color de fondo general opcional en modo claro.
      lightOnBackground : '<colorHex>', // Color opcional de los elementos en el fondo general en modo claro.
      darkTopBarContainer : '<colorHex>', // Color de fondo opcional para la barra superior en modo oscuro.
      darkOnTopBarContainer : '<colorHex>', // Color opcional de los elementos en la barra superior en modo oscuro.
      darkPrimary : '<colorHex>', // Color primario opcional en modo oscuro.
      darkOnPrimary : '<colorHex>', // Color opcional de los elementos en el color primario en modo oscuro.
      darkBackground : '<colorHex>', // Color de fondo general opcional en modo oscuro.
      darkOnBackground : '<colorHex>', // Color opcional de los elementos en el fondo general en modo oscuro.
    } as KhipuColors
  } as KhipuOptions
})

Retorno

El objeto result del ejemplo tiene los siguiente campos.

• 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

API

• startOperation(...)
• Interfaces

startOperation(...)

startOperation(options: StartOperationOptions) => Promise<KhipuResult>

Devuelve: Promise<KhipuResult>

Interfaces

KhipuResult

KhipuEvent

StartOperationOptions

KhipuOptions

KhipuColors