# 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 1. **Khipu Collector Account**: You must have a collector account on [khipu.com](https://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. 2. **iOS Mobile Application**: You must have a mobile application developed for iOS. 3. **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` ```ruby platform :ios, '12.0' # Khipu is compatible with iOS 12 or higher 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](/en/payment-solutions/instant-payments/khipu-integration#creation-of-payment-intent). - **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. - **topBarImageScale**: `CGFloat` (Optional) From 0.0 to 1.0, scales the top bar image. - **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. :::attention Important For Chile, the following URLs are used: ::: ```xml LSApplicationQueriesSchemes bancochilemipass2 BciPassApp BICEPassApp scotiabankgo SantanderPassApp tupass bancoestado itau.cl SecurityPass ``` ### API Invocation The following is an example of API invocation ```Swift import KhipuClientIOS ... KhipuLauncher.launch( presenter: self, 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. ```swift 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](/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 performed to generate the payment, with their timestamps.