Guía de integración de Rappi Payless
Rappi Payless es un método de pago sin tarjeta exclusivo para nuestros recolectores (compradores personales y repartidores).
Permite que los puntos de venta procesen los pedidos de Rappi usando códigos de pago generados en las aplicaciones móviles de nuestros recolectores. Estos códigos de pago son presentados en forma de códigos de barra o códigos QR.
Rappi Payless elimina las tarifas de transacciones relizadas con con tarjeta. Además, simplifica la conciliación e informe, reduce el tiempo de pago y elimina problemas operacionales relacionados con la liberación de fondos a las tarjetas de débito.
Lista de integración
Una vez que Rappi Payless ha sido implementado exitosamente, tu solución debe verificar lo siguiente:
Ingerir y procesar los códigos de pago de Rappi Payless, ya sea en forma de códigos de barras, códigos QR o códigos que hayan sido ingresados manualmente.
Enviar solicitudes de autorización de pagos a Rappi, incluyendo todos los detalles requeridos.
Manejar apropiadamente transacciones exitosas y rechazadas.
Manejar los tiempos de espera de solicitud con reintentos automáticos.
Cambiar al flujo de respaldo cuando la comunicación con Rappi no esté disponible.
Conciliar diariamente tus transacciones autorizadas por Rappi.
Introducción
Este artículo proporciona una descripción general de Rappi Payless. Podrás aprender más acerca de:
- La experiencia de nuestros recolectores con Rappi Payless.
- Los flujos de pago regular y de respaldo.
- Cómo recuperar información para alimentar tu proceso de conciliación.
- Cómo consumir nuestros métodos de sandbox para configurar tu ambiente de prueba y ejecutar pruebas manuales y automatizadas en tu integración.
PENDIENTES
En el futuro, Rappi Payless se integrará con programas de lealtad y habilitará procesos de pago sin escaneo que eliminarán filas de caja para recolectores.
El consumidor realiza un nuevo pedido
 | 1. El consumidor realiza un nuevo pedido Dependiendo de la configuración de la tienda, un algoritmo decide si la orden será completada por un comprador personal o un repartidor. |
 | 2. El recolector revisa la lista de compra De la lista de productos el recolector marca cada producto como “encontrado”, “no encontrado” o “reemplazado”. Los recolectores no pueden proceder al pago con productos pendientes en la lista de compras. |
 | 3. El recolector llega a la caja En este punto la aplicación del recolector está en modo de pago, generando códigos nuevos cada 30 segundos. |
El comprador paga con Payless
 | 4. El cajero escanea todos los productos El punto de venta aplica descuentos y promociones y calcula el total de la cuenta. |
 | 5. El código de pago es escaneado desde el dispositivo del recolector El cajero tiene la opción de escanear un código QR, un código de barras o ingresar manualmente un código de 6 dígitos. Aprende más acerca del código de pago de Rappi Payless aquí. |
 | 6. El punto de venta envía los detalles de la compra a Rappi Esta es una solicitud HTTP a nuestro endpoint de autorización de pago endpoint. Si es exitoso el punto de venta recibirá un token de autorización de transacción como respuesta. |
 | 7. El recolector toma una imagen del recibo El pedido está listo para su entrega. |
El código de barras de Rappi Payless
El código de barras de Rappi Payless (también referido como código de pago), es un número aleatorio de 6 dígitos asociado a un identificador de orden único en nuestra base de datos.
Los códigos de barras son actualizados cada 30 segundos en la vista de pago en las aplicaciones de nuestros recolectores. Estos permanecen activos por otros 30 segundos hasta que el backend de Rappi finalmente los expira. Por lo tanto, el tiempo total de vida de un código de barras es de un minuto (60 segundos).
REINTENTOS AUTOMÁTICOS EN TIEMPOS DE ESPERA
El tiempo total de vida del código de barras es de 60 segundos. Es importante considerar esta información cuando se implementan reintentos automáticos en respuestas a fallos de comunicación o tiempos de espera entre tu punto de venta y el backend de Rappi.
Detección automática del método de pago
Hemos creado una configuración opcional que permite a los comerciantes especificar un prefijo de 2 letras que precederá a cada código de barras que generemos.
El uso habitual para esta configuración es que el punto de venta identifique automáticamente el método de pago como Rappi Payless, sin requerir que el cajero ingrese algún comando desde el teclado.
El código de barras se usa también cuando Rappi Payless falla
Además de ser utilizado en la solicitud de autorización de pago, la secuencia de dígitos del código de barras es también una variable de entrada para la verificación del algoritmo del flujo de respaldo. Esto está detallado en la sección acerca de fallos de comunicación.
Solicitudes de autorización de pago
Una transación exitosa siempre regresará un código de status HTTP 200, e incluirá un token de autorización en el cuerpo de la respuesta. Tanto el código de barras como el token de autorización (o código de autorización) para cada transacción exitosa DEBEN ser almacenados del lado del comerciante para propósitos de conciliación.
Autorizaciones rechazadas
A pesar de que existen pocas razones que hagan que la transacción sea rechazada por Rappi, aquellas aún no se encuentran definidas por códigos y no se espera que el punto de venta exponga dicha información. En cada transacción rechazada, el recolector recibe una notificación push con instrucciones para ajustar la orden antes de cancelar el pago.
Solicitudes de autorización de pago malformadas
Puede que hayan propiedades requeridas faltantes o tipos de propiedades inconsistentes en tu autorización de pago.
El monto solicitado para el pago excede el límite autorizado para un pedido
Este escenario puede ser causado por diferencias de precio no reportadas que elevan la cantidad solicitada más allá del límite autorizado o por productos solicitados por el cliente a través del chat que no fueron incluidos apropiadamente por el recolector en el pedido.
En cada transacción rechazada, los recolectores reciben notificaciones push en sus aplicaciones, informándoles acerca de las inconsistencias en el pedido y solicitandoles hacer los ajustes necesarios antes de reintentar la transacción. Una vez ajustado el pedido, este no debería ser rechazado por segunda ocasión.
Pedidos Inaceptables
Los pedidos que reciban el mensaje de error
unacceptable_orderpueden ser cancelados por el consumidor (y que, debido a problemas momentáneos de conectividad, la aplicación del recolector no haya sincronizado), es posible que ya se haya realizado el pago o que el repartidor esté tratando de comprar los productos con un comercio asociado distinto.Códigos de barra inválidos
La mayoría de las veces, los escenarios de códigos de barras inválidos están asociados con intentos de fraude. Se toma una captura de la pantalla del código y el pago es rechazado ya sea porque ese código de barras expiró o se aplicó otro pago.
Manejo de fallos de comunicación
No es común que un punto de venta se comunique directamente con los endpoints de Rappi Payless. Las solicitudes a menudo son dirigidas a través de los servidores de las tiendas y centros de datos de los comerciantes. Usualmente estas solicitudes son canalizadas a través de VPNs para aislar el tráfico del internet público. Desafortunadamente estos son puntos de falla potenciales que pueden causar que una solicitud nunca llegue a Rappi o que una respuesta nunca sea devuelta al punto de venta.
Las prácticas idóneas en las implementaciones de Rappi Payless obligan a tener un reintento automático en el punto de venta, es decir, cuando un punto de venta no recibe una respuesta a su solicitud de autorización de pago.
Ejemplo: El cajero ingresa un comando en el punto de venta para enviar una solicitud de autorización de pago a Rappi. Si tus solicitudes están configuradas con un límite de tiempo de 5 segundos, puedes tener seis intentos automáticos de autorización seguros dentro del tiempo de vida del código de barras.
El límite de tiempo es configurable a discreción de cada comercio tomando en cuenta la latencia de sus redes privadas.
Recurriendo a las tarjetas de débito
Si inclusive después de varios intentos, el punto de venta sigue siendo incapaz de recibir una respuesta por una solicitud de autorización de pago, el flujo de respaldo DEBE intervenir. Esto es requerido por cualquier implementación de Rappi Payless antes de ser liberado para producción.
En este escenario, los recolectores necesitan notificar a Rappi que necesitan que se liberen fondos a sus tarjetas de débito para poder realizar el pago de un pedido. Toda vez que sus aplicaciones desconocen que ocurre entre el sistema de puntos de venta y nuestro backend, el siguiente proceso valida que Rappi pueda liberar fondos al recolector de manera segura.
 | 1. El punto de venta informa al cajero que algo no está bien. Cuando el punto de venta confirma un fallo en la comunicación, calculará un pin de seis dígitos y mostrará en su pantalla el mensaje “La comunicación con Rappi no está disponible. El equipo de Rappi necesita este código para pagar con tarjeta de débito”. La conectividad no es requerida para calcular el pin. |
 | 2. El recolector ingresa el código pin en la aplicación Desde la vista de de pago en la aplicación, nuestros recolectores tienen una opción denominada “El código no funciona”. Presionando este botón ellos tienen la indicación de ingresar el pin proporcionado por el cajero/punto de venta para liberar fondos a sus tarjetas de débito. |
 | 3. Rappi verifica que sea un pin válido Toda vez que Rappi y el punto de venta usan un algoritmo en común para calcular el pin, esta validación puede suceder incluso cuando no haya conectividad entre las partes. |
 | 4. El recolector paga por la compra con tarjeta de débito La validación del pin activa el flujo regular que libera fondos a las tarjetas de débito de los recolectores. |
DEBE SER UNA EXCEPCIÓN
La alternativa de pagos con tarjeta es indispensable, pero debe ser una excepción. Nuestro principal indicador clave de rendimiento (en inglés *key performance indicator* o KPI) en Rappi Payless es tener el 99.9% de las transacciones procesadas por nuestro motor de autorización. Esto significa que el flujo de respaldo solo debería activarse en una de cada 1000 órdenes procesadas.
Calculado el pin
Permitir que los recolectores cambien el método de pago a tarjeta de débito sin una validación apropiada sería contrario al propósito de la implementación de de Rappi Payless, y evitaría que tanto Rappi como los comerciantes asociados disfrutaran de los beneficios de esta tecnología.
Por lo tanto, calcular y validar el pin cuando no hay conectividad entre el cliente y el servidor requiere que las partes usen un algoritmo en común y variables de entrada que estén disponibles para ambas.
El algoritmo toma dos variables de entrada: current_date con formato YYMMDD y barcode. El pin es el resultado de multiplicar la fecha actual por el código de barras, extrayendo los últimos 6 dígitos del resultado. El pin es una variable string y no una variable integer, toda vez que sus primeros dígitos pueden ser ceros.
Configuración y uso de sandbox
Nuestras operaciones de sandbox fueron creadas para acelerar el desarrollo y las pruebas de nuestros socios y se ha demostrado que reduce drásticamente el tiempo de espera de integración. Este es un proceso de cinco pasos. Cualquier store_id puede ser usado en los métodos listados en la documentación de nuestro sandbox.
1. Carga y mantén el catálogo de productos que utilizarás durante tu desarrollo y control de calidad.
(a) Cargar el catálogo de productos carga un archivo de Excel para el procesamiento.
(b) Verificar la carga del catálogo de productos verifica el estado de la creación/actualización de tu catálogo.
¡IMPORTANTE!
Las cargas subsecuentes sobreescriben productos existentes.
En este punto estás listo para comenzar a ejecutar ciclos de pruebas. Cada ciclo de prueba está compuesto de órdenes múltiples y cuatro pasos. Cada orden en el ciclo de prueba simula un escenario diferente. No es requerido que consumas todas las órdenes de cada conjunto generado, pero es importante validar que todos los escenarios se manejen adecuadamente.
Esta operación genera un conjunto de órdenes de prueba para distintos escenarios:
valid | La transacción será autorizada si los productos correctos son escaneados. |
invalid_state | La transacción será rechazada. El estado de la orden en nuestra base de datos no es in_payment. Simula cuando un recolector intenta pagar por una orden…… antes de que la lista de compra esté completa (lo cual no debería ser posible); … que ya ha sido pagada (en otra tienda o punto de venta); .… que ya ha sido cancelada (pero la sincronización con la aplicación del recolector pudo haber fallado). |
different_retailer | La transacción será rechazada. Simula que el recolector intenta pagar con un código de barras generado por un comerciante distinto. |
invalid_high_price | La transacción será rechazada. Simula diferencias de precio que no fueron ajustadas por el recolector antes de llegar con el cajero. |
invalid_storekeeper | Este caso está marcado como obsoleto. |
invalid_low_price | Este caso está marcado como obsoleto. |
Esta es la misma operación usada por nuestras aplicaciones de recolección para representar los códigos de barras en la vista de pago. El parámetro de la ruta del código de pago no es solo parte de la solicitud de autorización de pago, sino que también es usado cuando se necesitan recuperar los detalles de un pedido.
3. Recuperar detalles de órdenes
Cuando generas órdenes de prueba la respuesta solo devolverá un array de order_ids. Debes consumir este endpoint para saber cuál debe ser escaneado en el punto de venta para realizar pruebas.
4. Escanear los productos en tu punto de venta (o simular este paso en tus pruebas automatizadas).
Después de tener todos los productos escaneados, es posible que quieras tener un código de pago reciente antes de enviar una solicitud de autorización de pago.
Envíe la solicitud de autorización de pago y maneje la respuesta según corresponda.
Esperamos que este documento sea capaz de proporcionar una clara descripción general de Rappi Payless y su guía de integración. Si tienes preguntas adicionales, por favor envía un correo electrónico a cpg-open-apis@rappi.com o contacta directamente a tu gerente técnico de cuentas asignado.