# Integración para iOS ## Introducción El **Cliente de Khipu para iOS** ofrece una solución integral para desarrolladores que desean implementar un sistema de pago nativo dentro de sus aplicaciones móviles iOS. Este SDK permite incorporar un método de pago directamente en la aplicación, evitando la necesidad de redirigir a los usuarios a una página web externa. Al integrar el Cliente de Khipu para iOS, proporcionas una experiencia de usuario coherente y segura, similar a la ofrecida por la versión web de Khipu. Además, este SDK incluye funcionalidades avanzadas como `openApp`, que permite a los usuarios acceder directamente a sus aplicaciones bancarias para validar pagos, optimizando el proceso de pago y mejorando la experiencia general del usuario. ## Pre-requisitos 1. **Cuenta de Cobrador en Khipu**: Debes tener una cuenta de cobrador en [khipu.com](https://khipu.com). Puedes optar por una cuenta regular o una en "modo desarrollador". Ambas cuentas operan de manera similar en términos de creación, autorización y conciliación de pagos, pero en el "modo desarrollador" se utilizan bancos y dinero ficticios. Es recomendable utilizar una cuenta en "modo desarrollador" durante el desarrollo y pruebas, y cambiar a una cuenta regular al pasar a producción. 2. **Aplicación móvil para iOS**: Debes tener una aplicación móvil desarrollada para iOS. 3. **Versión mínima del SDK**: La aplicación debe soportar como mínimo la versión 12 del SDK de iOS. ### Incorporar Khipu al proyecto #### Paso 1: Agregar el Pod de Khipu Se requiere agregar el pod de Khipu en tu archivo `Podfile` ```ruby platform :ios, '12.0' #Khipu es compatible con iOS 12 o superior target '' do use_frameworks! #Khipu usa Swift, use_frameworks! es necesario pod 'KhipuClientIOS' #Fija la versión antes de pasar a producción, ej. 'KhipuClientIOS', '2.0.0' end ``` ### Entrada A continuación se definen los parametros necesarios para iniciar la API. ### Documentación de `KhipuLauncher.launch` `KhipuLauncher.launch` es una función que crea un `Intent` para iniciar el proceso de pago utilizando el SDK de Khipu. Este `Intent` es esencial para lanzar la actividad de pago de Khipu. #### Parámetros - **presenter**: `UIViewController` La vista que esta presente en la aplicación justo antes de invocar a Khipu. - **operationId**: `String` El identificador único de la [intención de pago](/payment-solutions/instant-payments/khipu-integration#creaci%C3%B3n-de-intenci%C3%B3n-de-pago) - **options**: `KhipuOptions` Configuraciones para personalizar la interfaz y el comportamiento del proceso de pago, definidas mediante `KhipuOptions.Builder()`. - **header**: `KhipuHeader` (Opcional) Configura la cabecera de la actividad de pago con elementos como títulos y logos. - **topBarTitle**: `String` (Opcional) Título para la barra superior durante el proceso de pago. - **topBarImageUrl**: `String` (Opcional) URL de la imagen en la barra superior. - **topBarImageResourceName**: `String` (Opcional) Nombre del recurso en el bundle principal para la imagen en la barra superior. - **topBarImageScale**: `CGFloat` (Optional) El valor va desde 0.0 hasta 1.0, escala la imagen de la barra superior. - **skipExitPage**: `Boolean` Si es verdadero, se omite la página al final del proceso de pago, ya sea exitosa o fallida. - **showFooter**: `Boolean` Si es verdadero, se muestra un mensaje en la parte inferior con el logo de Khipu. - **theme**: `KhipuOptions.Theme` Tema de la interfaz, puede ser: - **.system**: Se usa el tema oscuro/claro dependiendo de la configuración del dispositivo - **.light**: Se utiliza el tema claro - **.dark**: Se utiliza el tema oscuro - **locale**: `String` Configuración regional para el idioma de la interfaz. El formato estándar que combina un código de idioma ISO 639-1 y un código de país ISO 3166. Por ejemplo, `"es_CL"` para español de Chile. - **colors**: `KhipuColors` Permite personalizar los colores de la interfaz de usuario. - **onComplete**: `(KhipuResult) -> Void)` (Opcional) Funcion de callback que se llamará al terminar el proceso de pago, donde se entregará un objeto `KhipuResult` como parámetro. ### Documentación de `KhipuHeader` `KhipuHeader` facilita la personalización del encabezado en el proceso de pago. #### Parámetros - **headerUIView**: `UIView & KhipuHeaderProtocol` (Opcional) UIView que debe cumplir el protocolo `KhipuHeaderProtocol`. - **height**: `Int` (Opcional) Altura en pixeles que se le dará al encabezado. ### Documentación de `KhipuColors` `KhipuColors` facilita la personalización de los colores en la interfaz de usuario del proceso de pago. #### Parámetros - **lightTopBarContainer**: `String` (Opcional) Color de fondo para la barra superior en modo claro. - **lightOnTopBarContainer**: `String` (Opcional) Color de los elementos en la barra superior en modo claro. - **lightPrimary**: `String` (Opcional) Color primario en modo claro. - **lightOnPrimary**: `String` (Opcional) Color de los elementos sobre el color primario en modo claro. - **lightBackground**: `String` (Opcional) Color de fondo general en modo claro. - **lightOnBackground**: `String` (Opcional) Color de los elementos sobre el fondo general en modo claro. - **darkTopBarContainer**: `String` (Opcional) Color de fondo para la barra superior en modo oscuro. - **darkOnTopBarContainer**: `String` (Opcional) Color de los elementos en la barra superior en modo oscuro. - **darkPrimary**: `String` (Opcional) Color primario en modo oscuro. - **darkOnPrimary**: `String` (Opcional) Color de los elementos sobre el color primario en modo oscuro. - **darkBackground**: `String` (Opcional) Color de fondo general en modo oscuro. - **darkOnBackground**: `String` (Opcional) Color de los elementos sobre el fondo general en modo oscuro. Esta configuración permite adaptar visualmente el proceso de pago a la estética de la aplicación móvil. ### Configuración de OpenApp Para asegurar que la aplicación OpenApp funcione correctamente y pueda abrir las aplicaciones bancarias, es esencial definir adecuadamente las URLs de las otras apps en el archivo `Info.plist`, para esto se debe agregar la llave `LSApplicationQueriesSchemes` que en Xcode se ve como `Queried URL Schemes` con un arreglo de String con cada URL de app bancaria. :::attention Importante Para el caso de Chile son las siguientes: ::: ```xml LSApplicationQueriesSchemes bancochilemipass2 BciPassApp BICEPassApp scotiabankgo SantanderPassApp tupass bancoestado itau.cl SecurityPass ``` ### Invocación API El siguiente es un ejemplo de invocación de la API ```Swift import KhipuClientIOS ... KhipuLauncher.launch( presenter: self, operationId: , options: KhipuOptions.Builder() .build() ) { result in print("Operation result \(result.asJson())") } ``` ### Parametro `presenter` El parametro presenter es un `UIViewController`, en el caso que la app use UIKit, normalmente basta con usar `self` que correspone al `UIViewController` activo. Si en cambio la app utiliza `SwiftUI` es necesario obtener el `UIViewController` actual, para eso se puede usar el siguiente código. ```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 } ``` Entonces se puede llamar la función `topMostViewController()` para obtener la vista superior actual. ### Salida A continuación se definen los parametros que retornara la API al terminar el proceso. ### Documentación de `KhipuResult` #### Retorno - **operationId**:`String` El identificador único de la intención de pago - **exitTitle**: `String` Título que se mostrará al usuario en la pantalla de salida, reflejando el resultado de la operación. - **exitMessage**:`String` Mensaje que se mostrará al usuario, proporcionando detalles adicionales sobre el resultado de la operación. - **exitUrl**: `String` URL a la que retornará la aplicación al terminar el proceso. - **result**: `String` Resultado general de la operación, los valores posibles son: - **OK**: Se autorizó correctamente el pago en el banco de origen. El pago se está validando y se enviará una notificación por el servidor cuando este validado. ([Caso de prueba](/payment-solutions/instant-payments/khipu-client-test-cases#pago-exitoso)) - **ERROR**: El pago no se autorizó correctamente, en exitMessage se encuentra el motivo a entregar al cliente y en failureReason el tipo de error. ([Caso de prueba](/payment-solutions/instant-payments/khipu-client-test-cases#pago-con-error)) - **WARNING**: El pago no se ha completado pero es posible que ocurra. Por ejemplo, el banco de origen tuvo un error al generar el comprobante de pago pero el dinero si se envió o faltan más firmantes en una transferencia de varios actores. Khipu comenzó el proceso de monitoreo de la cuenta de destino para validar el pago. ([Caso de prueba](/payment-solutions/instant-payments/khipu-client-test-cases#pago-con-resultado-dudoso)) - **CONTINUE**: Operación necesita más pasos para que pago sea terminado. Por ejemplo, los pagos en Bancos Empresa que necesitan mas firmas. ([Caso de prueba](/payment-solutions/instant-payments/khipu-client-test-cases#pago-que-debe-ser-continuado-por-otro-pagador)) - **failureReason**: `String` (Opcional) Describe la razón del fallo, si la operación no fue exitosa. - **continueUrl**: `String`(Opcional) Disponible solo cuando el resultado es "CONTINUE", que indica la URL a seguir para continuar la operación. - **events**: `Array` Pasos realizados para generar el pago, con sus estampas de tiempo