# Khipu's Client for Flutter

## Introduction

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


## Plugin Installation

Add this plugin to your dependencies:


```bash
flutter pub add flutter_khipu
```

Then get the dependency:


```bash
flutter pub get
```

## Platform Setup

### Android

#### Repository

Add the Khipu repository to the `android/build.gradle` file:


```groovy
allprojects {
    repositories {
        google()
        mavenCentral()
        maven { url 'https://dev.khipu.com/nexus/content/repositories/khenshin' }
    }
}
```

Note that the `google()` and `mavenCentral()` repositories are usually already added.

#### Jetifier

If you are still using Jetifier, please add `jackson-core` to the list of ignored jars by adding the line:


```groovy
android.jetifier.ignorelist = jackson-core
```

to the `android/gradle.properties` file.

#### Gradle Plugins

Khipu needs the Kotlin Android Gradle Plugin to be at least version 1.9.0, so please make sure the `android/settings.gradle` file has at least that version:


```groovy
plugins {
    id "org.jetbrains.kotlin.android" version "1.9.0" apply false
}
```

#### Proguard

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

#### Authorization to Open Other Applications

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

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


```dart
import 'package:flutter_khipu/flutter_khipu.dart';

...

KhipuResult? result =
    await FlutterKhipu().startOperation(KhipuStartOperationOptions(
                                            operationId: "<string>", // The unique identifier of the payment intent
                                            title: "<string>", // Text to show in the top bar
                                            titleImageUrl: "<string>", // Image to show centered in the top bar (replaces the title)
                                            locale: "<string>", // 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).
                                            skipExitPage: false, // If true, skips the exit page at the end of the payment process, whether successful or failed.
                                            theme: "<string>", // The interface theme, can be light, dark, or system.
                                            colors: KhipuColors(
                                                lightBackground: "<hexColor>", // Optional general background color in light mode
                                                lightOnBackground: "<hexColor>", // Optional color of elements on the general background in light mode
                                                lightPrimary: "<hexColor>", // Optional primary color in light mode.
                                                lightOnPrimary: "<hexColor>", // Optional color of elements on the primary color in light mode.
                                                lightTopBarContainer: "<hexColor>", // Optional background color for the top bar in light mode.
                                                lightOnTopBarContainer: "<hexColor>", // Optional color of elements in the top bar in light mode.
                                                darkBackground: "<hexColor>", // Optional general background color in dark mode
                                                darkOnBackground: "<hexColor>", // Optional color of elements on the general background in dark mode
                                                darkPrimary: "<hexColor>", // Optional primary color in dark mode.
                                                darkOnPrimary: "<hexColor>", // Optional color of elements on the primary color in dark mode.
                                                darkTopBarContainer: "<hexColor>", // Optional background color for the top bar in dark mode.
                                                darkOnTopBarContainer: "<hexColor>", // Optional color of elements in the top bar in dark mode.
                                            )));
```

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