Integración del Cliente Khipu 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

Cuenta de Cobrador en Khipu : Debes tener una cuenta de cobrador en 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.
Aplicación móvil para iOS : Debes tener una aplicación móvil desarrollada para iOS.
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

Copy

Copied

platform :ios, '12.0' #Khipu es compatible con iOS 12 o superior

target '<El target de tu app>' 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
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.
- 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.

Importante

Para el caso de Chile son las siguientes:

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>

Invocación API

El siguiente es un ejemplo de invocación de la API

Copy

Copied

import KhipuClientIOS


...

        KhipuLauncher.launch(
            presenter: self,
            operationId: <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.

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
}

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 : Éxito
- ERROR : Error
- WARNING : Advertencias
- CONTINUE : Operación necesita más pasos
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

Integración del Cliente Khipu para iOS

Introducción

Pre-requisitos

Incorporar Khipu al proyecto

Paso 1: Agregar el Pod de Khipu

Entrada

Documentación de KhipuLauncher.launch

Parámetros

Documentación de KhipuHeader

Parámetros

Documentación de KhipuColors

Parámetros

Configuración de OpenApp

Importante

Invocación API

Parametro presenter

Salida

Documentación de KhipuResult

Retorno

Documentación de `KhipuLauncher.launch`

Documentación de `KhipuHeader`

Documentación de `KhipuColors`

Parametro `presenter`

Documentación de `KhipuResult`