Integración del Plugin Khipu para Flutter

Introducción

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

Instalación del plugin

Añade este plugin a tus dependencias

Copy
Copied
flutter pub add flutter_khipu

Luego obtén la dependencia

Copy
Copied
flutter pub get

Configuración de la plataforma

Android

Repositorio

Agrega el repositorio de Khipu al archivo android/build.gradle

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.

Jetifier

Si aún estás utilizando jetifier, por favor añade jackson-core a la lista de archivos jar ignorados añadiendo la línea

Copy
Copied
android.jetifier.ignorelist = jackson-core

al archivo android/gradle.properties

Plugins de Gradle

Khipu necesita que el plugin de Kotlin Android Gradle sea al menos la versión 1.9.0, así que por favor asegúrate de que el archivo android/settings.gradle tenga al menos esa versión

Copy
Copied
plugins {
    id "org.jetbrains.kotlin.android" version "1.9.0" apply false
}

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>

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>

Uso

Copy
Copied
import 'package:flutter_khipu/flutter_khipu.dart';

...

KhipuResult? result =
    await FlutterKhipu().startOperation(KhipuStartOperationOptions(
                                            operationId: "<string>", // El identificador único de la intención de pago
                                            title: "<string>", // Texto para mostrar en la barra superior
                                            titleImageUrl: "<string>", // Imagen para mostrar centrada en la barra superior (reemplaza el título)
                                            locale: "<string>", // 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).
                                            skipExitPage: false, // Si es verdadero, omite la página de salida al final del proceso de pago, ya sea exitoso o fallido.
                                            theme: "<string>", // El tema de la interfaz, puede ser claro, oscuro o del sistema.
                                            colors: KhipuColors(
                                                lightBackground: "<hexColor>", // Color de fondo general opcional en modo claro
                                                lightOnBackground: "<hexColor>", // Color opcional de los elementos en el fondo general en modo claro
                                                lightPrimary: "<hexColor>", // Color primario opcional en modo claro.
                                                lightOnPrimary: "<hexColor>", // Color opcional de los elementos en el color primario en modo claro.
                                                lightTopBarContainer: "<hexColor>", // Color de fondo opcional para la barra superior en modo claro.
                                                lightOnTopBarContainer: "<hexColor>", // Color opcional de los elementos en la barra superior en modo claro.
                                                darkBackground: "<hexColor>", // Color de fondo general opcional en modo oscuro
                                                darkOnBackground: "<hexColor>", // Color opcional de los elementos en el fondo general en modo oscuro
                                                darkPrimary: "<hexColor>", // Color primario opcional en modo oscuro.
                                                darkOnPrimary: "<hexColor>", // Color opcional de los elementos en el color primario en modo oscuro.
                                                darkTopBarContainer: "<hexColor>", // Color de fondo opcional para la barra superior en modo oscuro.
                                                darkOnTopBarContainer: "<hexColor>", // Color opcional de los elementos en la barra superior en modo oscuro.
                                            )));

El objeto KhipuResult contendrá los siguientes 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 la aplicación retornará al final del proceso.
  • result : String Resultado general de la operación, los valores posibles son:
    • OK : Éxito
    • ERROR : Error
    • WARNING : Advertencias
    • CONTINUE : La 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", indicando la URL a seguir para continuar la operación.
  • events : Array Los pasos realizados para generar el pago, con sus marcas de tiempo.