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


```sh
npm install react-native-khipu
```

or


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


```groovy
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' }
    }
}
```

Additionally, make sure that the Kotlin plugin is enabled in your app. To do this, check that the `android/app/build.gradle` file includes the following:


```groovy
apply plugin: 'kotlin-android'
```

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.


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

**Important**
For Chile, the following apps are required:


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

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.

**Important**
For Chile, the following apps are required:


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


```typescript
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](/en/payment-solutions/instant-payments/khipu-client-test-cases#successful-payment))
  - **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](/en/payment-solutions/instant-payments/khipu-client-test-cases#payment-with-error))
  - **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](/en/payment-solutions/instant-payments/khipu-client-test-cases#payment-with-uncertain-result))
  - **CONTINUE**: The operation needs more steps to complete the payment. For example, payments at Business Banks that need more signatures. ([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 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(...)`](#startoperation)
* [Interfaces](#interfaces)


### startOperation(...)


```typescript
startOperation(options: StartOperationOptions) => Promise<KhipuResult>
```

| Parameter | Type |
|  --- | --- |
| **`options`** | StartOperationOptions |


**Returns:** Promise<KhipuResult>

### Interfaces

#### KhipuResult

| Property | Type |
|  --- | --- |
| **`operationId`** | string |
| **`exitTitle`** | string |
| **`exitMessage`** | string |
| **`exitUrl`** | string |
| **`result`** | 'OK' | 'ERROR' | 'WARNING' | 'CONTINUE' |
| **`failureReason`** | string |
| **`continueUrl`** | string |
| **`events`** | KhipuEvent[] |


#### KhipuEvent

| Property | Type |
|  --- | --- |
| **`name`** | string |
| **`timestamp`** | string |
| **`type`** | string |


#### StartOperationOptions

| Property | Type |
|  --- | --- |
| **`operationId`** | string |
| **`options`** | KhipuOptions |


#### KhipuOptions

| Property | Type |
|  --- | --- |
| **`locale`** | string |
| **`title`** | string |
| **`titleImageUrl`** | string |
| **`skipExitPage`** | boolean |
| **`showFooter`** | boolean |
| **`theme`** | 'light' | 'dark' | 'system' |
| **`colors`** | KhipuColors |


#### KhipuColors

| Property | Type |
|  --- | --- |
| **`lightBackground`** | string |
| **`lightOnBackground`** | string |
| **`lightPrimary`** | string |
| **`lightOnPrimary`** | string |
| **`lightTopBarContainer`** | string |
| **`lightOnTopBarContainer`** | string |
| **`darkBackground`** | string |
| **`darkOnBackground`** | string |
| **`darkPrimary`** | string |
| **`darkOnPrimary`** | string |
| **`darkTopBarContainer`** | string |
| **`darkOnTopBarContainer`** | string |