API de Khipu para crear cobros y recibir pagos

Introducción

La API de Khipu para crear y recibir pagos permite a cobradores (individuos u organizaciones), que tengan una cuenta de cobro activa en Khipu, generar cobros.

El proceso de creación, pago y validación es el siguiente:

1. El cobrador genera un cobro usando la API y despliega un botón para la compra.
2. El pagador pincha el botón de pago en el sitio web, o un enlace de pago en un correo electrónico u otro medio y paga utilizando Khipu.
3. El pagador es redireccionado a la página de retorno definida por el cobrador donde se debe indicar que el pago está en verificación (o a la página de fracaso en el caso que no se haya podido hacer el pago).
4. Unos momentos después Khipu verifica la transacción y notifica al pagador por correo electrónico. Además, se notifica al comercio por correo electrónico y/o por la invocación de un web service.
5. El cobrador valida la notificación de pago y entrega el bien transado al pagador (o descarta la notificación si es inválida).

Cuenta de cobro

Cuando una persona crea una cuenta de usuario en Khipu automáticamente se le creará una “cuenta de cobro”. Esta cuenta de cobro es la cuenta a la que quedarán asociados los pagos que reciba de otras personas.

Para poder cobrar es necesario activarla asociando una cuenta bancaria. La cuenta bancaria es donde, al día hábil siguiente, se deposita la recaudación diaria. Esta cuenta bancaria puede ser cambiada de forma posterior y afectará a todos los pagos que no hayan sido rendidos aún.

Al principio una cuenta de cobro no tiene una cuenta bancaria asociada. Para asociar una cuenta bancaria debes ir a tu cuenta Khipu y tratar de crear un cobro. El sistema te pedirá completar un pago usando esa cuenta bancaria para asegurar que tengas acceso a ella. El monto del pago será devuelto al día hábil siguiente.

Múltiples cuentas de cobro

Una cuenta de usuario en Khipu puede crear (o tener acceso) a múltiples cuentas de cobro. Eso sirve, por ejemplo, para tener distintos comercios y cada uno con su propia cuenta de cobro. Cada cuenta de cobro debe tener configurada su cuenta bancaria, pero varias cuentas de cobro pueden compartir los datos de una misma cuenta bancaria donde se rendirá el dinero.

Credenciales

Toda cuenta de cobro posee credenciales que permiten utilizar la API REST. Estas credenciales se generan al momento de crear la cuenta de cobro.

Esta nueva versión de la API ya no requiere que se firmen las peticiones, puesto que el proceso de autenticación y autorización es manejado por una clave de API secreta asociada a la cuenta de cobro, que debe ser enviada en una cabecera especial (x-api-key) en cada petición. Debido al nivel de acceso que proporcional, la clave no debe ser compartida con nadie. Siempre se puede crear una llave nueva que invalidará la antigua en caso de que quieras cambiarla, el proceso es completamente auto gestionado y puedes revisar los detalles en la sección Autenticación.

De todas formas es importante que sepa ubicar el "Id de cobrador", que puede ser útil para agilizar un ticket de soporte.

Seguridad

En la creación y validación de un pago se usan dos mecanismos de seguridad distintos. Por una parte Khipu utiliza un certificado de validación extendida que permite al cobrador siempre saber que se está comunicando efectivamente con los servidores oficiales de Khipu, además, para esta nueva versión de la API, la cabecera x-api-key permite identificar de forma inequívoca al generador del cobro.

Ambiente de pruebas y paso a producción

En esta sección te mostramos los pasos necesarios para comenzar la integración de Khipu en tu sitio. Lo más importante es notar que, durante el proceso de desarrollo y pruebas, debes usar credenciales de cuentas de cobro de desarrollo. Solo cuando tu sitio esté listo y la integración preparada para hacer pagos reales, debes cambiar las credenciales por las de una cuenta de cobro de producción.

Cuenta de cobro en modo desarrollador

Khipu no tiene una versión de pruebas separada de la versión de producción como otras plataformas. En lugar de eso, se utilizan la API y los servidores de la plataforma principal. Para efectuar pruebas de desarrollo se usa una “cuenta de cobro de desarrollador”. Estas cuentas de cobro son idénticas a las normales, pero tienen algunas diferencias:

Las cuentas corrientes asociadas no son reales pues no se rinde dinero real. Se crean solo para hacer pruebas. Los cobros generados con ellas solo pueden ser pagados usando bancos de prueba.

Para crear una cuenta de desarrollo debes seguir los siguientes pasos:

• Registrarse como usuario acá: https://khipu.com/user/register
• Ir a tu perfil de usuario en Khipu
• En “Opciones de desarrollador” activar el modo desarrollador.
• Luego ir a configurar y elegir “Cuentas de cobro”
• Ahora aparecerá un botón “Crear cuenta en modo desarrollador”

Ahora que tienes una cuenta de desarrollo, lo único que necesitas es la clave para uso de la API. El proceso es auto atendido, en el panel "Opciones de la cuenta", sección "Para integrar Khipu a tu sitio web", revisa la sección Autenticación para más detalles.

Banco de pruebas

Las cuentas de cobro de desarrollo solo pueden recibir pagos desde Bancos de pruebas. Estos bancos son bancos creados por Khipu para hacer pruebas.

El banco de prueba permite probar que el proceso de pago esté completo, incluyendo ir al banco y depositar a Khipu o utilizar la transferencia simplificada. Como estos bancos no operan con dinero real, puedes hacer todas las transferencias que desees pues nunca se acaba el saldo.

Estos bancos, además, tienen instrucciones en pantalla para poder entrar, llenar claves y autorizar transferencias.

Acceso a internet

Para poder acceder a la API REST de Khipu es necesario tener una conexión a internet. Esto es necesario para poder crear y modificar pagos.

Cada vez que Khipu recibe un pago se le avisa al comercio para que este pueda entregar el producto o servicio al cliente, este aviso puede ser por correo electrónico o utilizando la API de notificaciones instantáneas. El mecanismo recomendado es la notificación instantánea pues no requiere intervención humana una vez que está bien configurada. Estas notificaciones son invocaciones que Khipu debe hacer a un web service en el sitio web del comercio, razón por la cual este web service debe ser visible desde Internet. Revisa Webhook para notificaciones para el detalle de cómo usar la API de notificaciones.

Caso de uso común

Vamos a analizar el caso de uso más común de la API REST, que es hacer un pago en un comercio web para obtener un producto. El flujo más común tiene los siguientes pasos:

• El cliente elige sus productos y elige pagar
• El comercio crea un pago usando la API REST
• El comercio envía al cliente a pagar a Khipu
• El cliente paga
• El cliente es redireccionado al sitio web del comercio y espera unos momentos mientras Khipu verifica el pago.
• El pago es verificado y se notifica al comercio vía web service.
• El comercio entrega el producto o servicio.

Veamos ahora los pasos donde es necesaria la integración con Khipu:

Crear un cobro

POST /payments

Después de que el cliente elige sus productos y opta por pagar, comienza el proceso de pago. La mayoría de los software de comercio electrónico funcionan de manera similar. Todos tienen algún tipo de objeto que simboliza la orden de compra. Lo que debemos hacer es relacionar esta orden de compra con un pago en Khipu.

Puedes revisar la documentación del método POST /payments, que incluye trozos de código en varios lenguajes de programación para realizar una prueba rápida. De todas formas recomendamos revisar la sección Generación de código para construir un cliente más robusto.

En el primer paso obtenemos el objeto de orden de compra. Este puede ser creado en el momento o recuperado mediante un identificador propio que permita identificar esa orden de compra/cobro. A nivel de API, ese valor está representado por el parámetro transaction_id de la llamada. Esto es necesario para que en el momento de la conciliación logres obtener la orden de compra y darla por pagada.

La respuesta de la llamada será un objeto con información del cobro creado. El campo payment_id contiene el identificador único de nuestro pago y la url a la cual debemos enviar al usuario a pagar.

Ofrecer listado de bancos (Opcional)

GET /banks

Este paso es opcional, pero puede ser útil para algunos comercios. En la llamada anterior para crear pagos puede verse el parámetro “ID del banco para pagar”. Este ID sirve para crear un pago con un banco ya elegido (solo de los bancos soportados por Khipu). Para obtener este id se puede usar la llamada al método GET /banks que entrega el listado de los bancos soportados por Khipu, sus nombres, su id y otra información.

El resultado de la llamada contiene el valor banks que es un listado de bancos. Cada banco tiene un bank_id con el valor que podemos usar para crear pagos configurados.

Iniciar el pago

Una vez creado un pago debemos empezar el proceso de pagar. Para esto existen dos maneras. La manera recomendada es utilizar nuestra biblioteca javascript que se encargará de comenzar el pago. Puedes encontrar amplia documentación en el sitio de github. Allí puedes encontrar un ejemplo de integración de la biblioteca que simula un comercio que utiliza esta biblioteca.

La otra opción para iniciar el pago es simplemente redirigir al cliente a la url de pago en Khipu. Esta url corresponde al parámetro payment_url que devuelve la llamada de crear pago.

El cliente es redireccionado al comercio

Luego de que el cliente realiza el pago en el portal de Khipu será redireccionado de vuelta al sitio web del comercio. La url del comercio a la que es redirigido el usuario debe ser configurada por cada pago en el campo return_url, aunque podría ser la misma para todos los pagos.

Es muy importante notar que cuando el usuario llega de vuelta a la página del comercio esto no significa que el pago esté verificado. En esta página el comercio debe decir que el pago está en proceso de verificación y que se debe esperar un momento.

El comercio debe implementar en la página de retorno del pago, una forma de consultar el estado del mismo e informar al usuario cuando el pago haya sido confirmado.

Para esto, existen 3 estrategias, siendo las más comunes:

• WebSockets: El servidor del comercio informa al browser del cliente que el pago está confirmado para que lo despliegue. Es la forma más eficiente, pero la más compleja de implementar. Para más información https://es.wikipedia.org/wiki/WebSocket
• Llamadas AJAX: La página verifica mediante una llamada AJAX al servidor del comercio acerca del estado de la orden. Cuando la respuesta es positiva la página le avisa al usuario que el pago ha sido completado.
• Recargar la página periódicamente: Es el mecanismo más sencillo y consiste en utilizar un timer para recargar la página de manera periódica, por ejemplo, cada 10 segundos. Cada vez que la página carga se verifica si la orden está completa. Si lo está, se redirige al usuario a la página de éxito. Si no, debe indicar al usuario que es necesario seguir esperando y usar un nuevo timer.

Recibir la notificación y entregar el servicio

GET /payments/{payment_id}

En cualquier momento posterior a la generación del cobro, se podrá revisar el estado consultando el endpoint GET /payments/{payment_id}.

Si has configurado una URL para recibir una notificación entonces Khipu la invocará inmediatamente después de conciliar el pago. Esta notificación debes recibirla y procesarla en el webhook que configuraste para estos efectos.

La versión de esta API define la manera en que Khipu notifica al comercio, y debes considerar que si usas la API 3.0 de pagos, debes usar la misma versión en la API de notificaciones. En esta versión de la API recibirás un JSON con un objeto representando el estado actual del pago, mediante una llamada POST.