Khipu Client Integration for iOS

Introduction

The Khipu Client for iOS provides a comprehensive solution for developers looking to implement a native payment system within their iOS mobile applications. This SDK enables the integration of a payment method directly into the app, avoiding the need to redirect users to an external web page. By integrating the Khipu Client for iOS, you offer a consistent and secure user experience, similar to the web version of Khipu. Additionally, this SDK includes advanced functionalities such as openApp, which allows users to directly access their banking applications to validate payments, optimizing the payment process and enhancing the overall user experience.

Prerequisites

Khipu Collector Account : You must have a collector account on 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 in "developer mode" fictitious 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.
iOS Mobile Application : You must have a mobile application developed for iOS.
Minimum SDK Version : The application must support at least version 12 of the iOS SDK.

Incorporating Khipu into the Project

Step 1: Add the Khipu Pod

You need to add the Khipu pod in your Podfile

Copy

Copied

platform :ios, '12.0' # Khipu is compatible with iOS 12 or higher

target '<Your app target>' do
    use_frameworks! # Khipu uses Swift, use_frameworks! is necessary

    pod 'KhipuClientIOS' # Pin the version before going to production, e.g., 'KhipuClientIOS', '2.0.0'
end

Input

The following are the necessary parameters to initiate the API.

`KhipuLauncher.launch` Documentation

KhipuLauncher.launch 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

presenter : UIViewController
The view present in the application just before invoking Khipu.
operationId : String
The unique identifier of the payment intention .
options : KhipuOptions
Settings to customize the interface and behavior of the payment process, defined using KhipuOptions.Builder() .
- header : KhipuHeader (Optional)
  Configures the header of the payment activity with elements like titles and logos.
- topBarTitle : String (Optional)
  Title for the top bar during the payment process.
- topBarImageUrl : String (Optional)
  URL of the image in the top bar.
- topBarImageResourceName : String (Optional)
  Resource name in the main bundle for the image in the top bar.
- skipExitPage : Boolean
  If true, the page at the end of the payment process is skipped, whether successful or failed.
- showFooter : Boolean
  If true, a message is displayed at the bottom with the Khipu logo.
- theme : KhipuOptions.Theme
  Interface theme, can be:
- .system : Uses dark/light theme depending on device settings
- .light : Uses light theme
- .dark : Uses dark theme
- locale : String
  Regional setting 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 Chilean Spanish.
- colors : KhipuColors
  Allows customizing the user interface colors.
onComplete : (KhipuResult) -> Void (Optional)
Callback function that will be called upon completion of the payment process, where a KhipuResult object will be provided as a parameter.

`KhipuHeader` Documentation

KhipuHeader facilitates the customization of the header in the payment process.

Parameters

headerUIView : UIView & KhipuHeaderProtocol (Optional)
UIView that must comply with the KhipuHeaderProtocol .
height : Int (Optional)
Height in pixels for the header.

`KhipuColors` Documentation

KhipuColors facilitates the customization of the 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 in the top bar in light mode.
lightPrimary : String (Optional)
Primary color in light mode.
lightOnPrimary : String (Optional)
Color of the elements on the primary color in light mode.
lightBackground : String (Optional)
General background color in light mode.
lightOnBackground : String (Optional)
Color of the 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 in the top bar in dark mode.
darkPrimary : String (Optional)
Primary color in dark mode.
darkOnPrimary : String (Optional)
Color of the elements on the primary color in dark mode.
darkBackground : String (Optional)
General background color in dark mode.
darkOnBackground : String (Optional)
Color of the elements on the general background in dark mode.

This configuration allows visually adapting the payment process to the aesthetic of the mobile application.

OpenApp Configuration

To ensure that the OpenApp function works correctly and can open banking applications, it is essential to properly define the URLs of other apps in the Info.plist file. You must add the LSApplicationQueriesSchemes key, which appears as Queried URL Schemes in Xcode, with an array of Strings for each banking app URL.

Important

For Chile, the following URLs are used:

Copy

Copied

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

API Invocation

The following is an example of API invocation

Copy

Copied

import KhipuClientIOS

...

        KhipuLauncher.launch(
            presenter: self,
            operationId: <OperationId>,
            options: KhipuOptions.Builder()
                .build()
                ) { result in
                    print("Operation result \(result.asJson())")
                }

`presenter` Parameter

The presenter parameter is a UIViewController. If the app uses UIKit, usually self, which corresponds to the active UIViewController, is enough.

If the app uses SwiftUI, it is necessary to get the current UIViewController. You can use the following code.

Copy

Copied

extension UIViewController {
    
    func topMostViewController() -> UIViewController {
        if self.presentedViewController == nil {
            return self
        }
        
        if let navigation = self.presentedViewController as? UINavigationController {
            return navigation.visibleViewController!.topMostViewController()
        }
        
        if let tab = self.presentedViewController as? UITabBarController {
            if let selectedTab = tab.selectedViewController {
                return selectedTab.topMostViewController()
            }
            return tab.topMostViewController()
        }
        
        return self.presentedViewController!.topMostViewController()
    }
    
}

func topMostViewController() -> UIViewController? {
    
    let vc = UIApplication.shared.connectedScenes.filter {
        $0.activationState == .foregroundActive
    }.first(where: { $0 is UIWindowScene })
        .flatMap( { $0 as? UIWindowScene })?.windows
        .first(where: \.isKeyWindow)?
        .rootViewController?
        .topMostViewController()
    
    return vc
}

Then you can call the topMostViewController() function to get the current topmost view.

Output

The following are the parameters returned by the API upon completion of the process.

`KhipuResult` Documentation

Return

operationId : String
The unique identifier of the payment intention.
exitTitle : String
Title displayed 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 application will return upon completion of the process.

result : String
General result of the operation, possible values are:
- OK : Success
- ERROR : Error
- WARNING : Warnings
- CONTINUE : Operation needs more steps
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 performed to generate the payment, with their timestamps.

Khipu Client Integration for iOS

Introduction

Prerequisites

Incorporating Khipu into the Project

Step 1: Add the Khipu Pod

Input

KhipuLauncher.launch Documentation

Parameters

KhipuHeader Documentation

Parameters

KhipuColors Documentation

Parameters

OpenApp Configuration

Important

API Invocation

presenter Parameter

Output

KhipuResult Documentation

Return

`KhipuLauncher.launch` Documentation

`KhipuHeader` Documentation

`KhipuColors` Documentation

`presenter` Parameter

`KhipuResult` Documentation