Biblioteca Javascript

Objetivo

Esta biblioteca permite a los comercios implementar un botón de pago para pagar sin abandonar la página. Si el usuario no tiene instalado la aplicación khipu entonces es redirigido a una página de instalación, para luego volver a la página de pago en el comercio.

Como funciona

Este es el flujo de un pago utilizando la biblioteca:

  • Al cargar la página del comercio la biblioteca comprueba si el la aplicación khipu está instalada. Si se ha configurado un id de botón de pago entonces se configurará el botón que llame a la aplicación khipu y complete el pago. Si no está especificado un botón entonces la aplicación se levantará de manera automática.
  • Si el terminal de pagos no está instalado entonces se enviará al usurio al portal de khipu para que realize la instalación y complete el pago. Cuanto el pago es completado el usuario es devuelto a la página del comercio especificadada al crear el cobro.
  • Cuando el terminal se levanta en el portal del comercio, khipu avisa al navegador mediante websockets para que el usuario sea redirigido a una página del comercio que le dice que el pago está en verificación.
  • Cuando la transferencia esta confirmada, el servidor de khipu avisa al comercio usando una llamada POST indicando que el pago está completo.

Requisitos de esta biblioteca

API REST

La biblioteca se usa en conjunto con los cobros generados usando la API REST de khipu, por lo cual es muy recomendable estar familiarizado con dicha documentación.

Los cobros deben estar completamente configurados al momento de pagar, esto quiere decir que deben tener asignados un correo para el pagador y un banco asociado. Para esto se deben usar la llamada receiverBanks (para dar a elegir al pagador un listado de bancos disponibles) y la llamada para crear un pago para crear el cobro usando el correo del pagador y el banco seleccionado.

El cobro además debe llevar el parámetro notify_url para que al terminar el pago el usuario sea redirigido a una página avisando que está siendo verificado.

JQuery

La biblioteca javascript usa jQuery para el manejo de DOM y eventos. El uso de jQuery se hace con la opción noConlict por lo que puede ser usada de manera segura con otras bibliotecas.

Es recomendable usar la versión que provee google en sus servidores.

Atmosphere

Khipu utiliza el framework de websockets atmosphere-javascript para crear y utilizar
websockets. Esta plataforma viene incluida al incluir khipu, así pues, no es necesario incluirla de manera externa.

Integración con la página

Los siguientes son los pasos necesarios para integrar la biblioteca en una página de comercio. La idea es usar la biblioteca en una página donde exista un botón (o una imagen) para pagar. Al llegar a esta página ya debe existir un cobro en khipu y un código único de operación (id de pago) generado usando la API Rest en un paso anterior.

Lo primero que debemos hacer es incluir jQuery:


<script src=“//ajax.googleapis.com/ajax/libs/jquery/1.11.0/jquery.min.js”></script>

Luego incluimos la biblioteca de khipu.


<script src=“//storage.googleapis.com/installer/khipu.js”></script>

Ahora basta escribir un trozo de javascript parecido al siguiente:

<script>
window.onload = function () {
    KhipuLib.onLoad({
        elementId: 'pay-button'
        , data: {
                "id":"vzkeh1wk82ax"
                ,"bill-id":"V1A6y"
                ,"url":"https://khipu.com/payment/show/vzkeh1wk72ax"
                ,"manual-url":"https://khipu.com/payment/manual/vzkeh1wk72ax"
                ,"mobile-url":"khipu:///pos/vzkeh1wk72ax"
                ,"ready-for-terminal":true}
    })
}

</script>
Importante: ¿Por qué debe estar este código en en onload de la página y no cuando la página está ready?. Google deprecó de Chrome la API de plugins NPAPI. Es por esto que khipu utiliza una extensión para chrome para levantar el terminal. Esta extensión se conecta a los eventos de la página y la biblioteca necesita comuncarse con la extensión después de que esta está lista, esto es, justo antes de ejecutar onLoad.

Los parámetros de esta llamada se explican a continuación:

  • elementId: Es el id del botón en la página. La biblioteca busca en la página este objeto y escucha el evento onClick para levantar el terminal. Si este parámetro
    no se envía, la biblioteca intentará levantar el terminal tan pronto como se haya comprobado que este se encuentra instalado.
  • data: Es información que se obtiene mediante la llamada a llamada crear un pago. Contiene los datos necesarios para saber si el el cobro está listo para ser pagado usando la aplicación o es necesario enviar al usuario al portal de khipu y completar el proceso.

El último paso es agregar un elemento DIV con el id khipu-chrome-extension-div. Este DIV sirve para la comunicación de la biblioteca con la extensión chrome.

Código fuente:

<div id=“khipu-chrome-extension-div” style=“display: none”></div>

Importante: Este DIV debe estar creado en el html de la página y no debe ser generado de manera dinámica usando javascript, de lo contrario la extensión lo buscará antes de que se ejecuten los javascript de la página y no lo encontrará.

Ejemplo en línea

En la dirección http://demo.khipu.com hay un comercio de ejemplo que utiliza esta biblioteca. Este ejemplo pide los datos necesarios (correo y banco para pagar) y al hacer el envío genera un cobro en khipu obteniendo su código único de operación. En la siguiente página aparece un botón de pago configurado para llamar al terminal.

En la demo se usa una cuenta de cobro de desarrollo, por lo que solo aparecerá el banco de pruebas, cambiando la configuración se tendrá el listado completo de bancos.

Puedes descargar el código de este ejemplo desde nuestro repositorio en github