Integration of the Khipu Plugin for React Native

Introduction

The Khipu Plugin for React Native offers a comprehensive solution for developers who want to implement a native payment system within their cross-platform applications based on React Native. This plugin allows incorporating a payment method directly into the app, avoiding the need to redirect users to an external web page. By integrating the Khipu Plugin for React Native, 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. React Native Mobile App : You must have a mobile app developed for React Native.
3. Minimum Version of React Native : The plugin has been tested with versions 0.71 or higher of React Native.

Installation

npm install react-native-khipu

or

yarn add react-native-khipu

Android

Add the Khipu repository to the allprojects section of the android/build.gradle file. Additionally, Khipu requires the Kotlin Gradle plugin to be at least version 1.9.0 and to compile against the Android SDK 34, so ensure that the android/build.gradle file looks like this:

buildscript {
    ext {
        buildToolsVersion = "34.0.0"
        minSdkVersion = 21
        compileSdkVersion = 34
        targetSdkVersion = 34

        // We use NDK 23, which has support for M1 and is the NDK side-by-side version of AGP.
        ndkVersion = "23.1.7779620"
    }
    repositories {
        google()
        mavenCentral()
    }
    dependencies {
        classpath("com.android.tools.build:gradle:7.3.1")
        classpath("com.facebook.react:react-native-gradle-plugin")
        classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:1.9.0")
    }
}

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

If you are using Jetifier, exclude the jackson-core package in the android/gradle.properties file:

android.jetifier.ignorelist = jackson-core

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.** { *; }

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

Install the cocoapods dependencies:

cd ios
pod install --repo-update
cd ..

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 {
    type KhipuColors,
    type KhipuOptions,
    type KhipuResult,
    startOperation,
} from 'react-native-khipu';

// ...

const result: KhipuResult = await 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.
        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
})

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