# # Khipu's Client 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](https://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:



```xml
    <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:



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


```bash
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:


```groovy
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:


```groovy
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:


```groovy
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:


```groovy
-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:

:::attention Important
For Chile, the following apps are relevant:
:::


```xml
<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.go" />
    <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.

:::attention Important
For Chile, the following URLs are relevant:
:::


```xml
  <key>LSApplicationQueriesSchemes</key>
  <array>
    <string>bancochilemipass2</string>
    <string>BciPassApp</string>
    <string>BICEPassApp</string>
    <string>scotiabankgo</string>
    <string>SantanderPassApp</string>
    <string>tupass</string>
    <string>bancoestado</string>
    <string>itau.cl</string>
    <string>SecurityPass</string>
  </array>
```

## Usage


```javascript

  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](/en/payment-solutions/instant-payments/khipu-client-test-cases#successful-payment))
  - **ERROR**: Payment was not authorized. The reason is detailed in `exitMessage`, and the type of error in `failureReason`. ([Test Case](/en/payment-solutions/instant-payments/khipu-client-test-cases#payment-with-error))
  - **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](/en/payment-solutions/instant-payments/khipu-client-test-cases#payment-with-uncertain-result))
  - **CONTINUE**: Operation requires further steps to complete the payment, e.g., business payments requiring additional signatories. ([Test Case](/en/payment-solutions/instant-payments/khipu-client-test-cases#payment-to-be-continued-by-another-payer))
- **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.