Integration of the Khipu Plugin for Cordova

Introduction

The Khipu Plugin for Cordova provides a comprehensive solution for developers who want to implement a native payment system within their cross-platform applications based on Cordova. This plugin enables the integration of a payment method directly into the app, avoiding the need to redirect users to an external web page. By integrating the Khipu Plugin for Cordova, you provide a seamless and secure user experience, similar to the Khipu web version. Additionally, this plugin includes advanced functionalities like openApp, allowing users to directly access their banking apps to validate payments, optimizing the payment process and enhancing the overall user experience.

Prerequisites

Khipu Collector Account : You must have a collector account on khipu.com . You can opt for a regular account or a "developer mode" account. Both types operate similarly in terms of creating, authorizing, and reconciling payments, but "developer mode" uses fictitious banks and money. It's recommended to use a "developer mode" account during development and testing, and switch to a regular account for production.
Cordova-based Mobile Application : You must have a mobile application developed for Cordova.
Minimum Cordova Version : The plugin has been tested with Cordova versions 12 or higher.
iOS Deployment Target : The plugin requires at least iOS version 12. To ensure this version, you can modify the config.xml file of your app to include:

Copy

Copied

    <platform name="ios">
        <preference name="deployment-target" value="12.0" />
    </platform>

Installation

Copy

Copied

cordova plugin add cordova-khipu

Configuration for Android

Proguard

If your project uses Proguard with an aggressive configuration, you may encounter issues when generating the APK in release mode. To address 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. For this to work, your app must declare the banking apps that might be opened. Add the <queries> tag as a child element inside the <manifest> tag in the AndroidManifest.xml file:

Important

For Chile, the following are required:

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>

Configuration for iOS

As in 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 (shown in Xcode as Queried URL Schemes) with an array of strings, each representing a banking app's URL scheme.

Important

For Chile, the following are required:

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. Use ISO 639-1 language code and ISO 3166 country code (e.g., "es_CL" for Spanish, Chile).
              theme: 'light', // The theme of the interface, can be 'dark', 'light', or 'system'.
              showFooter: true, // If true, a message with the Khipu logo is displayed at the bottom.
              showMerchantLogo: true, // If true, the merchant's logo is displayed in the top bar.
              showPaymentDetails: true, // If true, the payment code and a link to view the details are displayed.
              skipExitPage: false, // If true, skips the exit page at the end of the payment process, whether successful or failed.
              colors: {
                  lightTopBarContainer: '<colorHex>', // Optional background color for the top bar in light mode.
                  lightOnTopBarContainer: '<colorHex>', // Optional color of the elements on 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 color of the elements on 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))
      }
  )

Response

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

operationId : String
The unique identifier of the payment intent.
exitTitle : String
Title displayed to the user on the exit screen, reflecting the operation's result.
exitMessage : String
Message displayed to the user, providing additional details about the operation's result.
exitUrl : String
URL to which the application returns upon completing the process.
result : String
General result of the operation, possible values include:
- OK : Payment was successfully authorized at the originating bank. The payment is being validated, and a server notification will be sent once validated. ( Test case )
- ERROR : The payment was not authorized correctly. The reason is found in exitMessage , and the type of error is in failureReason . ( Test case )
- WARNING : The payment has not been completed but may occur. For example, the originating bank encountered an error generating the payment receipt, but the money was sent, or additional signers are required for a multi-party transfer. Khipu has started monitoring the destination account to validate the payment. ( Test case )
- CONTINUE : Operation requires additional steps to complete the payment. For example, business bank payments that require more signatures. ( Test case )
failureReason : String (Optional)
Describes the failure reason if the operation was unsuccessful.
continueUrl : String (Optional)
Available only when the result is "CONTINUE," indicating the URL to continue the operation.
events : Array
Steps performed to generate the payment, with their timestamps.