Khipu's Client for Android Integration

Introduction

The Khipu's Client for Android provides a comprehensive solution for developers wanting to implement a native payment system within their Android mobile applications. This SDK enables the incorporation of a payment method directly into the app, eliminating the need to redirect users to an external web page. By integrating the Khipu SDK for Android, you provide a consistent and secure user experience, akin to that offered by Khipu's web version. Additionally, this SDK includes advanced functionalities such as openApp, which allows users to directly access their banking apps for payment validation, optimizing the payment process and enhancing the overall user experience.

Prerequisites

1. Khipu Merchant Account : You must have a merchant account at khipu.com . You can opt for a regular account or a "developer mode" account. Both accounts operate similarly in terms of creation, authorization, and reconciliation of payments, but "developer mode" uses fictional banks and money. It is advisable to use a "developer mode" account during development and testing, and switch to a regular account when going to production.
2. Android Mobile App : You must have an Android mobile application developed.
3. Minimum SDK Version : The application must support at least Android SDK version 21.

Incorporating API into the Project

Add the Khipu Repository

You need to add the Khipu repository to your project-level build.gradle file in the repositories section:

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

Add the Dependency

To use the Khipu API, you need to include the library in your project. Add the following dependency to your module's build.gradle file (not the project-level one):

dependencies {
    implementation 'com.khipu:khipu-client-android:+' // + will retrive the newest package, please fix this to a given version in production
}

Proguard Configuration

If your project uses Proguard and has a very aggressive configuration, you might encounter issues when generating the APK in release mode. To fix 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.** { *; }

Input

Below are the parameters necessary to initiate the API.

Documentation for Khipu.getKhipuLauncherIntent

getKhipuLauncherIntent is a function that creates an Intent to start the payment process using the Khipu SDK. This Intent is essential for launching the Khipu payment activity.

Parameters

• context : Context
  The application context, used to access the resources and services of the app environment.
• operationId : String
  The unique identifier of the payment intent
• options : KhipuOptions
  Settings to customize the interface and behavior of the payment process, defined through KhipuOptions.Builder() .
  • header : KhipuHeader (Optional)
    Configures the header of the payment activity with elements such as titles and logos.
  • topBarTitle : String
    Title for the top bar during the payment process.
  • topBarImageResourceId : Int (Optional)
    Image on the top bar.
  • skipExitPage : Boolean
    If true, skips the exit page at the end of the payment process, whether successful or failed.
  • showFooter : Boolean
    If true, a message is displayed at the bottom with the Khipu logo.
  • theme : KhipuOptions.Theme
    The theme of the interface, can be:
  • .SYSTEM : Uses the dark/light theme depending on the device settings.
  • .LIGHT : Uses the light theme.
  • .DARK : Uses the dark theme.
  • 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).
  • colors : KhipuColors
    Allows customization of the user interface colors.

Documentation for KhipuColors

KhipuColors facilitates the customization of colors in the user interface of the payment process.

Parameters

• lightTopBarContainer : String (Optional)
  Background color for the top bar in light mode.
• lightOnTopBarContainer : String (Optional)
  Color of the elements on the top bar in light mode.
• lightPrimary : String (Optional)
  Primary color in light mode.
• lightOnPrimary : String (Optional)
  Color of elements on the primary color in light mode.
• lightBackground : String (Optional)
  General background color in light mode.
• lightOnBackground : String (Optional)
  Color of elements on the general background in light mode.
• darkTopBarContainer : String (Optional)
  Background color for the top bar in dark mode.
• darkOnTopBarContainer : String (Optional)
  Color of the elements on the top bar in dark mode.
• darkPrimary : String (Optional)
  Primary color in dark mode.
• darkOnPrimary : String (Optional)
  Color of elements on the primary color in dark mode.
• darkBackground : String (Optional)
  General background color in dark mode.
• darkOnBackground : String (Optional) Color of elements on the general background in dark mode.

This configuration allows for visually adapting the payment process to the aesthetics of the mobile app.

OpenApp Configuration

To ensure that the OpenApp functions correctly and can open banking apps, it is essential to properly define the queries in the AndroidManifest.xml.

Definition of Queries in the Manifest

Below is an explanation of how to configure the queries in the AndroidManifest.xml file to allow your application to interact with specific banking apps. It is necessary to add the <queries> tag as a child element within the <manifest> tag:

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

API Invocation

The following is an example of API invocation:

import com.khipu.client.KHIPU_RESULT_EXTRA
import com.khipu.client.KhipuColors
import com.khipu.client.KhipuOptions
import com.khipu.client.KhipuResult
import com.khipu.client.getKhipuLauncherIntent


// We create a launcher for the Khipu activity and define a callback to display the response
val khipuLauncher =
  rememberLauncherForActivityResult(ActivityResultContracts.StartActivityForResult()) { result: ActivityResult ->
    if (result.resultCode == Activity.RESULT_OK) {
      val intent = result.data
      val metadata = intent?.getSerializableExtra(KHIPU_RESULT_EXTRA) as KhipuResult
      resultText = metadata.toString()
    }
  }
...

// Later, we initiate the activity
khipuLauncher.launch(
  getKhipuLauncherIntent(
    context = context,
    operationId = text.value,
    options = KhipuOptions.Builder()
      .topBarTitle("Khipu")
      .skipExitPage(false)
      .locale("es_CL")
      .build()
  )
)

Output

Below are the parameters that the API will return at the end of the process.

Documentation for KhipuResult

Return

• operationId : String The unique identifier for 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 The steps taken to generate the payment, with their timestamps.