Integration of the Khipu Plugin for Cordova

Introduction

The Khipu Plugin for Cordova provides an all-in-one solution for developers who want to implement a native payment system within their cross-platform Cordova applications. This plugin allows you to embed a payment method directly in the app, avoiding the need to redirect users to an external web page. By integrating the Khipu Plugin for Cordova, you provide a consistent and secure user experience, similar to the web version of Khipu. Additionally, this plugin includes advanced features like openApp, which allows users to directly access their banking applications to validate payments, optimizing the payment process and enhancing the overall user experience.

Prerequisites

  1. Collector Account in Khipu : You must have a collector account on khipu.com . You can choose between a regular account or a "developer mode" account. Both accounts operate similarly in terms of payment creation, authorization, and reconciliation, but "developer mode" uses fictional banks and money. It is recommended to use a "developer mode" account during development and testing and switch to a regular account for production.
  2. Cordova Mobile Application : You must have a mobile application developed for Cordova.
  3. Minimum Cordova Version : The plugin has been tested with Cordova version 11 or higher.
  4. iOS Deployment Target : The plugin requires iOS version 12 or later. To ensure this version, you can modify your app's config.xml file to include something like:
Copy
Copied
    <platform name="ios">
        <preference name="deployment-target" value="12.0" />
    </platform>
  1. Minimum Versions for Android (Required for Cordova versions below 12) : The plugin requires Kotlin version 1.9 or higher, Gradle 8.7 or higher, Android Gradle plugin version 8.3.0 or higher, and Android SDK 34 or higher. To ensure this, you can modify your app's config.xml file to include:
Copy
Copied
    <platform name="android">
        <preference name="GradlePluginKotlinVersion" value="1.9.10" />
        <preference name="GradleVersion" value="8.7" />
        <preference name="AndroidGradlePluginVersion" value="8.3.0" />
        <preference name="android-targetSdkVersion" value="34" />
        <preference name="android-compileSdkVersion" value="34" />
    </platform>

Installation

Copy
Copied
cordova plugin add cordova-khipu

Android Configuration

Updating Configuration Files (Required for Cordova versions below 12)

Avoid Using the kotlin-android-extensions Plugin

Kotlin 1.9.0 no longer requires or supports the kotlin-android-extensions plugin. If you encounter the error The 'kotlin-android-extensions' Gradle plugin is no longer supported, remove or comment out the following line in your platform/android/app/build.gradle file:

Copy
Copied
apply plugin: 'kotlin-android-extensions'

Configure the App's namespace

In modern versions of the Android Gradle plugin, the namespace property is configured in Gradle files instead of the AndroidManifest.xml.

Ensure that the following exists in the platform/android/app/build.gradle file under the android section:

Copy
Copied
android {
    namespace '<the main package of the application>'
    ...

The app's main package can be obtained from the package property in the manifest element in the AndroidManifest.xml file.

And in the platform/android/CordovaLib/build.gradle file:

Copy
Copied
android {
    namespace 'org.apache.cordova'
    ...

Proguard

If your project uses Proguard with very aggressive settings, you might encounter issues when generating the APK in release mode. To fix this, include the following rule in your proguard-rules.pro file:

Copy
Copied
-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 enhanced authorization (2FA) is required. To do this, your app must declare which banking apps it might open. Add the <queries> tag as a child element within the <manifest> tag in the AndroidManifest.xml file:

Important

For Chile, the following apps are relevant:

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 Configuration

As with Android, in iOS, it is essential to properly define the URLs of other apps that Khipu may open in the Info.plist file. Add the LSApplicationQueriesSchemes key, which appears in Xcode as Queried URL Schemes, with an array of strings for each banking app URL.

Important

For Chile, the following URLs are relevant:

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>

Usage

Copy
Copied
  window.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. Format: ISO 639-1 language code + ISO 3166 country code, e.g., "es_CL" for Spanish (Chile).
              theme: 'light', // Interface theme: 'dark', 'light', or 'system'
              showFooter: true, // If true, displays a footer message with the Khipu logo.
              showMerchantLogo: true, // If true, displays the merchant's logo in the top bar.
              showPaymentDetails: true, // If true, displays the payment code and a link to view details.
              skipExitPage: false, // If true, skips the exit page after the payment process.
              colors: {
                  lightTopBarContainer: '<colorHex>', // Optional background color for the top bar in light mode.
                  lightOnTopBarContainer: '<colorHex>', // Optional element color for the top bar in light mode.
                  lightPrimary: '<colorHex>', // Optional primary color in light mode.
                  lightOnPrimary: '<colorHex>', // Optional color of elements on the primary color in light mode.
                  lightBackground: '<colorHex>', // Optional general background color in light mode.
                  lightOnBackground: '<colorHex>', // Optional color of elements on the general background in light mode.
                  darkTopBarContainer: '<colorHex>', // Optional background color for the top bar in dark mode.
                  darkOnTopBarContainer: '<colorHex>', // Optional element color for the top bar in dark mode.
                  darkPrimary: '<colorHex>', // Optional primary color in dark mode.
                  darkOnPrimary: '<colorHex>', // Optional color of elements on the primary color in dark mode.
                  darkBackground: '<colorHex>', // Optional general background color in dark mode.
                  darkOnBackground: '<colorHex>', // Optional color of elements on the general background in dark mode.
              }
          }
      },
      (success) => {
        console.log(JSON.stringify(success))
      },
      (error) => {
        console.error(JSON.stringify(error))
      }
  )

Return Values

The success and error objects in the example contain the following fields:

  • operationId : String
    Unique identifier of the payment intent.
  • exitTitle : String
    Title shown to the user on the exit screen, reflecting the operation result.
  • exitMessage : String
    Message displayed to the user, providing additional details about the operation result.
  • exitUrl : String
    URL to which the app will return after the process ends.
  • result : String
    General operation result. Possible values:
    • OK : Payment was successfully authorized at the source bank. The payment is being validated, and a notification will be sent once validated. ( Test Case )
    • ERROR : Payment was not authorized. The reason is detailed in exitMessage , and the type of error in failureReason . ( Test Case )
    • WARNING : Payment is incomplete but may still occur. For instance, if the bank failed to generate a payment receipt but the money was sent, or if additional signatures are required. ( Test Case )
    • CONTINUE : Operation requires further steps to complete the payment, e.g., business payments requiring additional signatories. ( Test Case )
  • failureReason : String (Optional)
    Describes the reason for failure if the operation was unsuccessful.
  • continueUrl : String (Optional)
    Available only when the result is "CONTINUE," indicating the URL to proceed with the operation.
  • events : Array
    Steps performed to generate the payment, with timestamps.