Integración con API de Zenkipay

Flujo de Pago

Para los comercios que no se encuentran en una plataforma de comercio electrónico, es necesario integrarse mediante el API REST de Zenkipay. Antes de entrar al detalle de la integración, revisemos el flujo típico de un pago:

1. El comprador ha agregado los artículos o servicios que desea comprar en su carrito de compra y selecciona la opción 'proceder al pago', 'finalizar compra' o 'checkout' en el portal del comercio.
2. El comercio solicita los datos del comprador y la dirección de entrega(en el caso de que no tenga una cuenta en el portal del comercio o no hayan registrados previamente) y muestra las opciones de pago disponibles para el comprador.
3. El comprador selecciona la opción de pagar con crypto mediante Zenkipay y hace clic en el botón 'pagar'.
4. Dentro de la página del comercio se abre la ventana de pago de Zenkipay donde el comprador efectúa el pago con su cartera de criptomonedas.
5. El comercio y el comprador reciben una notificación de Zenkipay, indicando que el pago se procesó correctamente.

Integración del comercio con Zenkipay 

De acuerdo al flujo anterior, los ajustes que debes realizar en el portal del comercio son los siguientes:

1. Agregar el botón de pago en la pantalla de checkout (Front-end) e implementar el llamado (submit) al back-end del comercio.
2. Desarrollar un servicio en el back-end del comercio que registre la información de la orden llamando al API de Zenkipay.
3. Retornar la información que te regresa el API al registrar la orden, y pasarla como parámetros para abrir la ventana de pago (modal) de Zenkipay en pantalla (Front-End).
4. Implementa un mecanismo para recibir la notificación de pago exitoso (Back-end). Para esto tienes 2 opciones:
   1. Webhook [Recomendado]: Con este mecanismo deberás exponer un servicio REST público para que te notifiquemos cuando el pago se procesó correctamente.
   2. Consulta de estado de la orden vía API: En este mecanismo deberás verificar periódicamente el estado de una orden y confirmar si se procesó correctamente.
5. Opcionalmente, invocar los siguientes servicios del API del lado del comercio:
   1. Consultar información del comercio
   2. Registro de envíos para rastreo
   3. Actualización del estado de envío
   4. Registro de rembolsos para una orden

1. Agregar botón de pago

Consulta nuestra guía de Buenas prácticas de UX/UI donde podrás descargar las imágenes de los botones disponibles y recomendaciones para incorporarlos en el sitio del comercio. Para tu comodidad, hemos desarrollado librerías para algunas tecnologías de front end:

• Angular
• Vue.js
• React

Si tu tecnología no se encuentra en el listado anterior, puedes realizar tu integración con Javascript.

2. Registrar información de la orden

Cuando el comprador se encuentra en el pago de la orden e indica que desea realizar su pago con Zenkipay, el portal del comercio debe informar a Zenkipay la información de la orden para poder abrir la ventana de pago. 

Autenticar cliente del API

Zenkipay API está diseñada sobre REST, por lo tanto, encontraremos que las URL están orientadas a recursos. Además, se utilizan códigos de respuesta HTTP para indicar los errores de la API. Es necesario tener una cuenta en Zenkipay, de lo contrario será necesario que registres el comercio en nuestra página principal. Para realizar peticiones al API de Zenkipay se requiere de lo siguiente:

• Obtener tus credenciales de acceso para el API de Zenkipay.
• Realizar la autenticación HTTP mediante el esquema Bearer Token en todos los llamados al API de Zenkipay.

Registrar la Orden

La información de la orden se debe registrar utilizando el API de Zenkipay, esta deberá ir en el cuerpo de la petición HTTP en formato JSON.

3. Abrir la modal de pago

El llamado al endpoint anterior devolvera la información de la orden junto con los campos zenkiOrderId (Identificador único de la orden generado por Zenkipay) y paymentSignature (Firma de la información de la orden de pago para mostrar la modal) los cuales se utilizarán para abrir la modal de pago.

4. Recibir notificación de pago exitoso

Finalmente, si el pago se realizó exitosamente se te informará mediante un webhook o en caso de no configurarlo deberás consultarlo periódicamente llamando al endpoint de consulta de una orden.

5. Invocar endpoints adicionales

El API de Zenkipay cuenta con servicios adicionales para automatizar algunas de las tareas que los operadores del comercio realizan en nuestro portal de comercios. Puedes consultar el detalle de los endpoints a continuación:

1. Consultar información del comercio: Se utiliza para obtener la configuración actual del comercio.
2. Registro de envíos para rastreo: Se utiliza para registrar uno o más números de rastreo de envío por el número de orden.
3. Actualización del estado de envío: Se utiliza para actualizar el estado de la entrega de una orden.
4. Registro de rembolsos para una orden: Se utiliza para registrar uno o más rembolsos por número de orden.

Configuración de Pruebas y Productiva

Durante el proceso de enrolamiento se te proporcionarán credenciales del API (client_id y client_secret) para realizar tus pruebas. Al finalizar tu prueba se te proporcionarán nuevamente para tu entorno productivo.