# Integración para Cordova

## Introducción

El **Plugin de Khipu para Cordova** ofrece una solución integral para desarrolladores que desean implementar un sistema de pago nativo dentro de sus aplicaciones multiplataforma basados en Cordova. Este plugin 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 Plugin de Khipu para Cordova, proporcionas una experiencia de usuario coherente y segura, similar a la ofrecida por la versión web de Khipu. Además, este plugin 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 en Cordova**: Debes tener una aplicación móvil desarrollada para Cordova.
3. **Versión mínima de Cordova**: El plugin ha sido probado con versiones 11 o superiores de Cordova.
4. **Deployment target de iOS**: El plugin necesita la versión 12 de iOS al menos. Para asegurar esa versión puede modificar el archivo `config.xml` de su app para incluir algo como:



```xml
    <platform name="ios">
        <preference name="deployment-target" value="12.0" />
    </platform>
```

1. **Versiones mínimas en Android (necesario para Cordova inferior a 12)**: El plugin necesita Kotlin versión 1.9 o superior, Gradle 8.7 o superior, el plugin de Gradle para Android versión 8.3.0 o superior y el SDK de Android 34 o superior. Para asegurar esto se puede modificar el archivo `config.xml` de su app para incluir:



```xml
    <platform name="android">
        <preference name="GradlePluginKotlinVersion" value="1.9.10" />
        <preference name="GradleVersion" value="8.7" />
        <preference name="AndroidGradlePluginVersion" value="8.3.0" />
        <preference name="android-targetSdkVersion" value="34" />
        <preference name="android-compileSdkVersion" value="34" />
    </platform>
```

## Instalación


```bash
cordova plugin add cordova-khipu
```

## Configuración para Android

### Actualización de archivos de configuración (necesario para Cordova inferior a 12).

#### No usar el plugin `kotlin-android-extensions`

Kotlin 1.9.0 ya no requiere ni soporta el plugin `kotlin-android-extensions`, si al compilar obtiene el error `The 'kotlin-android-extensions' Gradle plugin is no longer supported.` Elimine o comente la siguiente línea en su archivo `platform/android/app/build.gradle`


```groovy
apply plugin: 'kotlin-android-extensions'
```

#### Configurar el `namespace` de la app

En versiones modernas del plugin Gradle para Android, la propiedad `namespace` se configura en los archivos Gradle en vez del `AndroidManifest.xml`

Verifique que en el archivo `platform/android/app/build.gradle` en la sección `android` exista lo siguiente:


```groovy
android {
    namespace '<el package principal de la aplicación>'
    ...
```

El package principal de la app puede obtenerse de la propiedad `package` del elemento `manifest` en el archivo `AndroidManifest.xml`.

Y en el archivo `platform/android/CordovaLib/build.gradle` lo siguiente:


```groovy
android {
    namespace 'org.apache.cordova'
    ...
```

### Proguard

Si tu proyecto usa proguard y tiene un configuración muy agresiva es posible que tengas problemas al generar el `APK` en modo `release`. Para corregir esto incluye la siguiente regla en tu archivo `proguard-rules.pro`.


```groovy
-keep public class com.khipu.client.**{
    public protected *;
}

-keep class com.khipu.khenshin.protocol.** { *; }
```

### Autorización para abrir otras aplicaciones

Khipu abre automáticamente las apps bancarias cuando se requiere autorización reforzada (2FA), para poder hacer eso, tu app debe declarar cuales son las apps bancarias que se podrían abrir, para esto es necesario agregar el tag `<queries>` como un elemento hijo dentro del tag `<manifest>` en el archivo `AndroidManifest.xml`:

:::attention Importante
Para el caso de Chile son las siguientes:
:::


```xml
<queries>
    <package android:name="cl.bci.pass" />
    <package android:name="cl.bancochile.mi_pass2" />
    <package android:name="net.veritran.becl.prod" />
    <package android:name="cl.scotiabank.go" />
    <package android:name="cl.santander.santanderpasschile" />
    <package android:name="com.konylabs.ItauMobileBank" />
    <package android:name="cl.bancosecurity.securitypass" />
    <package android:name="cl.bice.bicepassmobile2" />
    <package android:name="cl.consorcio.tupass" />
</queries>
```

## Configuración para iOS

Al igual que en Android, en iOS, es esencial definir adecuadamente las URLs de las otras apps que se pueden abrir desde Khipu 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
  <key>LSApplicationQueriesSchemes</key>
  <array>
    <string>bancochilemipass2</string>
    <string>BciPassApp</string>
    <string>BICEPassApp</string>
    <string>scotiabankgo</string>
    <string>SantanderPassApp</string>
    <string>tupass</string>
    <string>bancoestado</string>
    <string>itau.cl</string>
    <string>SecurityPass</string>
  </array>
```

## Uso


```javascript

  window.Khipu.startOperation({
          operationId: '<paymentId>',
          options: {
              title: '<Title to display in the payment process>', // Title for the top bar during the payment process.
              titleImageUrl: '<Image to display centered in the topbar>', // Url of the image to display in the top bar.
              locale: 'es_CL', // Regional settings 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 Spanish (Chile).
              theme: 'light', // The theme of the interface, can be 'dark', 'light' or 'system'
              showFooter: true, // If true, a message is displayed at the bottom with the Khipu logo.
              showMerchantLogo: true, // If true, the merchant's logo is displayed in the top bar.
              showPaymentDetails: true, // If true, the payment code and a link to view the details are displayed.
              skipExitPage: false, // If true, skips the exit page at the end of the payment process, whether successful or failed.
              colors: {
                  lightTopBarContainer: '<colorHex>', // Optional background color for the top bar in light mode.
                  lightOnTopBarContainer: '<colorHex>', // Optional color of the elements on the top bar in light mode.
                  lightPrimary: '<colorHex>', // Optional primary color in light mode.
                  lightOnPrimary: '<colorHex>', // Optional color of elements on the primary color in light mode.
                  lightBackground: '<colorHex>', // Optional general background color in light mode.
                  lightOnBackground: '<colorHex>', // Optional color of elements on the general background in light mode.
                  darkTopBarContainer: '<colorHex>', // Optional background color for the top bar in dark mode.
                  darkOnTopBarContainer: '<colorHex>', // Optional color of the elements on the top bar in dark mode.
                  darkPrimary: '<colorHex>', // Optional primary color in dark mode.
                  darkOnPrimary: '<colorHex>', // Optional color of elements on the primary color in dark mode.
                  darkBackground: '<colorHex>', // Optional general background color in dark mode.
                  darkOnBackground: '<colorHex>', // Optional color of elements on the general background in dark mode.
              }
          }
      },
      (success) => {
        console.log(JSON.stringify(success))
      },
      (error) => {
        console.error(JSON.stringify(error))
      }
  )
```

## Retorno

Los objetos `success` y `error` del ejemplo tienen los siguiente campos.

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