Estados del QR

Un código QR generado a través de la API de Vendis tiene un ciclo de vida bien definido representado por un conjunto de estados. Comprender estos estados es fundamental para automatizar las decisiones de negocio en tu sistema (por ejemplo, liberar un pedido, despachar un producto o cerrar una factura).

---

Diccionario de Estados

El campo status devuelto tanto por la consulta manual del estado del QR como por la notificación del Webhook puede tomar uno de los siguientes valores de tipo string (ENUM):

Estado	Significado	Acción recomendada en tu sistema
PENDING	Pendiente de pago. El QR ha sido creado correctamente en el banco y está listo para ser escaneado por el cliente.	Mostrar el QR en pantalla y mantener la orden o carrito de compras en estado "Pendiente".
PAID	Pagado. El cliente escaneó el QR y completó la transferencia de fondos con éxito en su banco.	Liberar el servicio/producto inmediatamente. Registrar los datos de pago adjuntos (payment_amount, payment_bank, etc.) en tu base de datos y marcar la transacción como completada.
CANCELED	Cancelado. El QR ha sido anulado de forma manual o automática (por ejemplo, al expirar el tiempo de validez configurado en qr_expiration).	Deshabilitar el QR en tu interfaz para que el usuario no intente pagarlo. Si desea pagar de nuevo, debes generar un nuevo QR.
FAILED	Fallido. Ocurrió un error técnico al intentar registrar o procesar el QR con las entidades financieras delegadas.	Informar al usuario que hubo un problema técnico temporal y permitirle reintentar la operación (generando un nuevo código QR).

---

Ciclo de Vida y Transiciones

A continuación se muestra cómo transiciona un código QR desde su creación:

Notas Importantes para el Integrador:

1. Inmutabilidad de PAID y CANCELED: Una vez que un QR entra en los estados PAID o CANCELED, su estado es definitivo y ya no cambiará.
2. QRs de Único Uso vs. Multiuso:
   • Si creaste el QR con la bandera "is_multi_use": false, en cuanto se registre el primer pago exitoso, el QR pasará al estado PAID y no aceptará más dinero.
   • Si se configuró "is_multi_use": true, el QR puede recibir múltiples pagos individuales y cada pago disparará una notificación de webhook independiente.