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
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 usingKhipuOptions.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.
-
header
:
-
onComplete
:
(KhipuResult) -> Void
(Optional)
Callback function that will be called upon completion of the payment process, where aKhipuResult
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 theKhipuHeaderProtocol
. -
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:
<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
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.
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 : 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 performed to generate the payment, with their timestamps.