Flujo de Pago con Código QR
Introducción
Un método común para facilitar pagos entrantes son aquellos realizados mediante Código QR dentro del ecosistema Bre-B en Colombia.
El flujo esperado incluye que el sistema POS (punto de venta) se conecte con la plataforma Passport PaaS, el Nodo Bre-B y las entidades financieras participantes. A lo largo de esta página, se asume que el POS es el sistema backend que se conecta a la plataforma Passport, aunque pueden existir varias variantes: los flujos se mantienen iguales.
Dirigido a:
- Equipos técnicos que implementan integraciones API.
- Equipos de producto que evalúan la experiencia del usuario.
- Interesados de negocio que analizan estrategias de pagos en tiempo real.
Resumen del Flujo
La siguiente imagen resume los pasos desde la solicitud de generación del QR hasta la confirmación del pago vía Webhook al comercio.
Diagrama de Flujo Transaccional
Pasos del Pago con Código QR
| Passo | Acción | Desde | A |
|---|---|---|---|
| 1 | Solicitud de Código QR | POS | Plataforma PaaS |
| 2 | Generación del Código QR | Plataforma PaaS | Nodo Bre-B |
| 3 | Presentación del QR al Cliente | POS | Comprador |
| 4 | Inicio del Pago | Comprador | Banco del Cliente |
| 5 | Enrutamiento del Pago | Banco del Cliente | Nodo Bre-B -> Banco Sponsor |
| 6 | Notification de Abono | Banco Sponsor | Plataforma PaaS |
| 7 | Webhook de Confirmación | Plataforma PaaS | POS |
Descripción del Flujo
La Plataforma PaaS no se conecta automáticamente al sistema POS; es responsabilidad de la fintech o proveedor establecer esta integración.
Paso 1: Solicitud de Creación del Código QR
El sistema POS del comercio solicita a la PaaS Platform generar un Código QR Dinámico para una nueva sesión de pago.
La creación del QR debe (o puede) incluir un qr_code_reference que permita rastrear la transacción a lo largo de todo el ciclo de vida del pago. Esto vincula el QR con la venta pendiente en el POS (o con un depósito pendiente en una app fintech) y puede recibirse dentro de la Notificación de Pago Entrante.
Paso 2: Generación del Código QR
La PaaS Platform genera el Código QR, que incluye una Llave Bre-B única y metadatos asociados al pago. Esto se alinea con la última especificación de Códigos QR en Colombia, definida por EMV Co y un cuerpo voluntario conformado por ACH Colombia, Credibanco, Redeban, Visionamos, Mastercard y Visa.
Paso 3: Presentación del QR al Cliente
El QR generado se muestra en el POS para que el comprador lo escanee usando la Zona Bre-B de su aplicación bancaria. Cada Entidad Financiera en Colombia está obligada a soportar el escaneo de Códigos QR vía la Zona Bre-B, lo que garantiza una funcionalidad consistente entre entidades participantes en la red.
Paso 4: Inicio del Pago
La aplicación de la Entidad Financiera extrae la información del QR y prepara la iniciación del pago. El proceso de iniciación debe seguir pasos definidos y cada entidad es certificada para cumplirlos adecuadamente.
Estos pasos incluyen, entre otros, extraer el qr_code_reference establecido en el Paso 1 por el POS. Esta información se incorpora en el mensaje de pago cuando la entidad financiera inicia el débito desde la cuenta del comprador.
Paso 5: Enrutamiento del Pago
La Entidad Financiera del comprador enruta el pago a través del Nodo Bre-B al que está conectada; este lo envía al Banco de la República y luego al Nodo que lo forwardea al Banco Patrocinador del Comercio.
Paso 6: Notificación de Crédito
El Banco Patrocinador revisa el pago entrante frente a políticas AML, verifica que la Cuenta y el destinatario existan, y abona la Cuenta del Comercio. La PaaS Platform monitorea tanto la conexión con el Nodo Bre-B como la Cuenta Bancaria del Comercio, de modo que, cuando se recibe la notificación de pago entrante, también queda al tanto.
Paso 7: Confirmación vía Webhook
La PaaS Platform envía un Webhook al POS del Comercio confirmando que el pago fue recibido, permitiendo completar la transacción.
El Webhook de Pago Entrante contiene el qr_code_reference creado en el Paso 1 por el POS, extraído en el Paso 4 y transmitido por la red Bre-B en los Pasos 5 y 6.
Esto asegura que el pago entrante pueda identificarse correctamente y mapearse contra la venta pendiente en el POS (o el depósito pendiente en una plataforma fintech).
El Banco de la República ha mandatado que todas las Entidades Financieras soporten actividades con Códigos QR (creación, escaneo, enrutamiento de pagos); sin embargo, se han observado implementaciones inconsistentes de la especificación en las primeras fases del servicio Bre-B. Recomendación: cuando sea posible, dispón de un proceso de respaldo para identificar pagos entrantes en caso de que el banco del comprador no opere de forma compliant. La página Receiving a Bre-B Payment contiene ideas para mitigar este escenario.
Validación del Código QR
Passport ofrece, en Products > QR Codes, un historial de todos los Códigos QR generados. Para cada uno, puedes:
- Visualizar la imagen convertida desde base64.
- Usar cualquier lector de QR para validar la información codificada.
- Para más detalles, consulta el documento de Código QR.
Ejemplo de Código QR presentado en el tablero de control