Integration of the Khipu Plugin for Flutter

Introduction

The Khipu Plugin for Flutter offers a comprehensive solution for developers who want to implement a native payment system within their cross-platform applications based on Flutter. This plugin allows incorporating a payment method directly into the application, avoiding the need to redirect users to an external web page. By integrating the Khipu Plugin for Flutter, you provide a consistent and secure user experience, similar to the one offered by Khipu's web version. Additionally, this plugin includes advanced functionalities like openApp, which allows users to access their banking apps directly to validate payments, optimizing the payment process and enhancing the overall user experience.

Prerequisites

1. Khipu Merchant Account : You must have a merchant account on khipu.com . You can opt for a regular account or a "developer mode" account. Both accounts operate similarly in terms of creating, authorizing, and reconciling payments, but in "developer mode," fictional banks and money are used. It is recommended to use a "developer mode" account during development and testing and switch to a regular account when moving to production.
2. Flutter Mobile App : You must have a mobile app developed for Flutter.
3. Minimum Version of Flutter : The plugin has been tested with versions 3 or higher of Flutter.

Plugin Installation

Add this plugin to your dependencies:

flutter pub add flutter_khipu

Then get the dependency:

flutter pub get

Platform Setup

Android

Repository

Add the Khipu repository to the android/build.gradle file:

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

Note that the google() and mavenCentral() repositories are usually already added.

Jetifier

If you are still using Jetifier, please add jackson-core to the list of ignored jars by adding the line:

android.jetifier.ignorelist = jackson-core

to the android/gradle.properties file.

Gradle Plugins

Khipu needs the Kotlin Android Gradle Plugin to be at least version 1.9.0, so please make sure the android/settings.gradle file has at least that version:

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

Proguard

If your project uses Proguard and has a very aggressive configuration, you may encounter issues when generating the APK in release mode. To correct this, include the following rule in your proguard-rules.pro file:

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

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

Authorization to Open Other Applications

Khipu automatically opens banking apps when strong authentication (2FA) is required. To do this, your app must declare which banking apps can be opened. To achieve this, you need to add the <queries> tag as a child element within the <manifest> tag in the AndroidManifest.xml file:

<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

As with Android, in iOS, it is essential to properly define the URLs of the other apps that can be opened from Khipu in the Info.plist file. To do this, you must add the LSApplicationQueriesSchemes key, which in Xcode appears as Queried URL Schemes, with an array of strings for each banking app URL.

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

Usage

import 'package:flutter_khipu/flutter_khipu.dart';

...

KhipuResult? result =
    await FlutterKhipu().startOperation(KhipuStartOperationOptions(
                                            operationId: "<string>", // The unique identifier of the payment intent
                                            title: "<string>", // Text to show in the top bar
                                            titleImageUrl: "<string>", // Image to show centered in the top bar (replaces the title)
                                            locale: "<string>", // Regional settings for the interface language. The standard format combines an ISO 639-1 language code and an ISO 3166 country code. For example, "es_CL" for Spanish (Chile).
                                            skipExitPage: false, // If true, skips the exit page at the end of the payment process, whether successful or failed.
                                            theme: "<string>", // The interface theme, can be light, dark, or system.
                                            colors: KhipuColors(
                                                lightBackground: "<hexColor>", // Optional general background color in light mode
                                                lightOnBackground: "<hexColor>", // Optional color of elements on the general background in light mode
                                                lightPrimary: "<hexColor>", // Optional primary color in light mode.
                                                lightOnPrimary: "<hexColor>", // Optional color of elements on the primary color in light mode.
                                                lightTopBarContainer: "<hexColor>", // Optional background color for the top bar in light mode.
                                                lightOnTopBarContainer: "<hexColor>", // Optional color of elements in the top bar in light mode.
                                                darkBackground: "<hexColor>", // Optional general background color in dark mode
                                                darkOnBackground: "<hexColor>", // Optional color of elements on the general background in dark mode
                                                darkPrimary: "<hexColor>", // Optional primary color in dark mode.
                                                darkOnPrimary: "<hexColor>", // Optional color of elements on the primary color in dark mode.
                                                darkTopBarContainer: "<hexColor>", // Optional background color for the top bar in dark mode.
                                                darkOnTopBarContainer: "<hexColor>", // Optional color of elements in the top bar in dark mode.
                                            )));

Return

The result object from the example has the following fields:

• operationId : String The unique identifier of the payment intent.
• exitTitle : String Title that will be displayed to the user on the exit screen, reflecting the outcome of the operation.
• exitMessage : String Message that will be displayed to the user, providing additional details about the outcome of the operation.
• exitUrl : String URL to which the application will return at the end of the process.
• result : String General outcome of the operation, possible values are:
  • OK : The payment was successfully authorized at the originating bank. The payment is being validated and a notification will be sent by the server once validated. ( Test Case )
  • ERROR : The payment was not successfully authorized; exitMessage contains the reason to be provided to the client, and failureReason contains the type of error. ( Test Case )
  • WARNING : The payment has not been completed, but it may occur. For example, the originating bank had an error generating the payment receipt, but the money was sent, or more signatories are needed in a multiple-party transfer. Khipu began the process of monitoring the destination account to validate the payment. ( Test Case )
  • CONTINUE : The operation needs more steps to complete the payment. For example, payments at Business Banks that need more signatures. ( Test Case )
• failureReason : String (Optional) Describes the reason for the failure if the operation was not successful.
• continueUrl : String (Optional) Available only when the result is "CONTINUE," indicating the URL to follow to continue the operation.
• events : Array Steps taken to generate the payment, with their timestamps.

API

• startOperation(...)
• Interfaces

startOperation(...)

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

Returns: Promise<KhipuResult>

Interfaces

KhipuResult

KhipuEvent

StartOperationOptions

KhipuOptions

KhipuColors