2026-09-12 — Devoluciones al cliente por pago móvil
Para el panel admin.
Summary
Hasta ahora devolverle dinero a un cliente era un trámite fuera del sistema. Desde esta versión cada orden tiene su propio formulario de devolución: se elige entre devolver todo lo que el cliente pagó o un monto parcial, y el dinero sale por pago móvil usando la misma vía SyPago con la que se le paga a los repartidores.
La plataforma no guarda los datos bancarios del cliente, así que el formulario los pide: cédula, teléfono y banco. Quedan congelados en el registro de la devolución, junto con el monto en Bs y la tasa usada.
Changes
Endpoints
| Método | Ruta | Rol | Para qué sirve |
|---|---|---|---|
GET |
/api/v1/admin/orders/{orderId}/refund |
Admin | Cuánto se puede devolver y la devolución ya hecha, si la hay |
POST |
/api/v1/admin/orders/{orderId}/refund |
Admin | Registrar y enviar la devolución |
Ver Admin orders para los cuerpos y errores.
Una devolución por orden
El tope es lo que el cliente efectivamente pagó. Una vez registrada la devolución,
la orden queda cerrada para devoluciones: un segundo POST responde 422 con
RefundNotAllowed. No hay forma de emitir dos transferencias por la misma orden.
El monto se pide en USD y viaja en Bs
El admin escribe USD, como en el resto del sistema. Se convierte con la tasa BCV y se guardan las dos cifras más la tasa, así que un movimiento posterior del BCV no reescribe lo que se envió.
El estado sigue a la transferencia
| Estado | Qué significa |
|---|---|
PENDING |
Registrada, todavía sin enviar |
DISPERSING |
Enviada sin acuse: el dinero puede estar en camino, nunca se reenvía |
SENT |
SyPago la aceptó; falta la confirmación de entrega |
CONFIRMED |
El beneficiario recibió el dinero |
FAILED |
SyPago la rechazó; el motivo queda en last_error |
La confirmación llega por el webhook de SyPago, el mismo que ya resuelve los pagos a repartidores. Abrir la pantalla también consulta al proveedor cuando la transferencia sigue en vuelo, así que basta con entrar para destrabar una que quedó sin respuesta.
Efecto sobre el pago de la orden
Una devolución total confirmada deja el pago en REFUNDED. Una parcial no
cambia el estado del pago: el cliente sí pagó, y solo una parte volvió.