Integración del Cliente de Khipu para Web

Introducción

El Cliente de Khipu para Web ofrece una solución integral para desarrolladores que desean implementar un sistema de pago nativo en aplicaciones Web.

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.

Incorporar Khipu al proyecto

Paso 1: Incluir la biblioteca KWS

Se debe incluir en la página la biblioteca kws.js dentro del tag de la página.

Copy
Copied
<head>
    ...
    <script src="https://js.khipu.com/v1/kws.js"></script>
    ...
</head>

Paso 2: Agregar el elemento ancla

Khipu embebido se puede utilizar en modo "modal" o "incrustado". En ambos casos se debe definir un elemento donde se anclará. Se recomienda usar un con id khipu-web-root, pero puede ser cualquier id.

Copy
Copied
<div id="khipu-web-root"></div>

Entrada

A continuación se definen los parametros necesarios para iniciar la API.

Parámetros:

  • modal : Boolean Determina si el proceso de pago se presentará en una ventana modal.
    • true : Activa el modo modal.
    • false : Desactiva el modo modal.
  • modalOptions : Configura las dimensiones de la ventana modal cuando el modo modal está activado.
    • maxWidth : El ancho máximo que la ventana modal puede ocupar.
    • maxHeight : La altura máxima que la ventana modal puede ocupar.
  • options :
    • style : El estilo gráfico de Khipu Inside Web se puede modificar con los siguiente parámetros
      • primaryColor : Color principal de la interfaz.
    • skipExitPage : Boolean Controla si se omite la página de salida al final del proceso de pago.
      • true : Omite la página de salida.
      • false : Muestra la página de salida.

Invocación API

En el caso de Khipu Web los links y botones de salida se configuran automáticamente con las urls enviadas al crear el pago a través de nuestra API. Con comportamientos especiales para la configuración modal.

Finalmente y con un identificador único de pago como se explica en intención de pago se puede iniciar un pago usando Khipu Inside Web.

Copy
Copied
const callback = (result) => {
  console.log(`calback invoked:`, result);
};

const options = {
  mountElement: document.getElementById('khenshin-web-root'), 
  modal: true, 
  modalOptions: {
    maxWidth: 450,
    maxHeight: 860,
},
  options: {
  style: {
    primaryColor: '#8347AD',
    fontFamily: 'Roboto',
    },
  skipExitPage: false, 
  },
}

const khipu = new Khipu();

khipu.startOperation('Identificador de pago', callback, options);

Salida

A continuación se definen los parametros que retornara la API al terminar el proceso.

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 )
    • 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 )
    • 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 )
    • 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 )
  • 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

Cerrar ventana de pago

Si se desease cerrar la ventana de pago, por ejemplo, al capturar un mensaje de salida, basta con llamar el método

Copy
Copied
khipu.close();

Adicionalmente, para el caso de la ventana Modal, esta acción se realizará de forma interna en los links de:

  • Anular pago y volver : Disponible durante el pago. Lo que llama al callback errorHandler con un mensaje del tipo: OPERATION FAILURE con failureReason: USER CANCELED
  • Finalizar y volver : Se muestra al finalizar el pago. Sin hacer llamadas adicionales a los callback, ya que al completarse la transacción se envió una llamada al successHandler.

Reiniciar el pago

Si se desease reiniciar el pago actual en caso de error u algún otro problema se puede utilizar el método

Copy
Copied
khipu.restart();