Integration of the Khipu Plugin for Capacitor

Introduction

The Khipu Plugin for Capacitor offers a comprehensive solution for developers who want to implement a native payment system within their cross-platform applications based on Capacitor. 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 Capacitor, 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. Capacitor Mobile App : You must have a mobile app developed for Capacitor.
3. Minimum Version of Capacitor : The plugin has been tested with versions 6 or higher of Capacitor.

Installation

npm install capacitor-khipu
npx cap sync

Android Setup

Main Khipu Repository

For Android to be able to locate the khenshin aar file, you need to add the khenshin maven repository to the allprojects section of the android/build.gradle file.

Something like this:

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.

Jetpack Compose and Kotlin

The Khipu client for Android uses Jetpack Compose technology; therefore, it is necessary to enable the Kotlin plugin.

In the android/build.gradle file, add the classpath for the org.jetbrains.kotlin:kotlin-gradle-plugin:<version> artifact:

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'

        // NOTE: Do not place your application dependencies here; they belong
        // in the individual module build.gradle files.
    }
}

Note that the classpaths for com.android.tools.build:gradle:<version> and com.google.gms:google-services:<version> are usually already there.

Then, in the android/app/build.gradle file, add the plugin at the top of the file:

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

Note that the com.android.application plugin is usually already there.

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 Setup

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 {Khipu, KhipuColors, KhipuOptions, KhipuResult, StartOperationOptions} from "capacitor-khipu"

// ...

const result: KhipuResult = await Khipu.startOperation({
        operationId: '<paymentId>',
        options: {
            title: '<Title to display in the payment process>', // Title for the top bar during the payment process.
            titleImageUrl: '<Image to display centered in the topbar>', // URL of the image to display in the top bar.
            locale: 'es_CL', // 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).
            theme: 'light', // The interface theme, can be 'dark', 'light', or 'system'.
            skipExitPage: false, // If true, skips the exit page at the end of the payment process, whether successful or failed.
            showFooter: true, // If true, a message is displayed at the bottom with the Khipu logo.
            colors: {
                lightTopBarContainer: '<colorHex>', // Optional background color for the top bar in light mode.
                lightOnTopBarContainer : '<colorHex>', // Optional color for elements in the top bar in light mode.
                lightPrimary : '<colorHex>', // Optional primary color in light mode.
                lightOnPrimary : '<colorHex>', // Optional color for elements in the primary color in light mode.
                lightBackground : '<colorHex>', // Optional general background color in light mode.
                lightOnBackground : '<colorHex>', // Optional color for elements in the general background in light mode.
                darkTopBarContainer : '<colorHex>', // Optional background color for the top bar in dark mode.
                darkOnTopBarContainer : '<colorHex>', // Optional color for elements in the top bar in dark mode.
                darkPrimary : '<colorHex>', // Optional primary color in dark mode.
                darkOnPrimary : '<colorHex>', // Optional color for elements in the primary color in dark mode.
                darkBackground : '<colorHex>', // Optional general background color in dark mode.
                darkOnBackground : '<colorHex>', // Optional color for elements in the general background in dark mode.
            } as KhipuColors,
        } as KhipuOptions
    } as StartOperationOptions
)

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