Recepción de un Pago Bre-B
Descripción General
Este documento describe el ciclo de vida para habilitar que un posible comprador envíe al Comercio un Pago usando un Código QR dentro del ecosistema Bre-B en Colombia. Se recomienda iniciar cada pago presentando un Código QR como una forma fácil para convertir la información necesaria e iniciar la transferencia.
Dirigido a:
- Equipos técnicos que implementan integraciones con API.
- Equipos de producto que evalúan la experiencia de usuario.
- Responsables de negocio que analizan estrategias de pagos en tiempo real.
Flujo General
La imagen siguiente resume los pasos desde la solicitud de generación del Código QR hasta la confirmación por Webhook al comercio. Los pasos clave en esta página son las notificaciones entrantes y la información que recibirá la PaaS Platform cuando llegue un pago para un comercio al Banco Patrocinador.
Diagrama de Flujo de Transacción
Pasos del Pago con Código QR
| Paso | Acción | Origen | Destino |
|---|---|---|---|
| 1 | Solicitud de QR | PoS/Backend | Plataforma PaaS |
| 2 | Generación de QR | Plataforma PaaS | Nodo Bre-B |
| 3 | Presentación de QR al Cliente | PoS | Cliente/Buyer |
| 4 | Inicio del Pago | Cliente/Buyer | Banco del Cliente |
| 5 | Enrutamiento del Pago | Banco del Cliente | Nodo Bre-B → Banco Sponsor |
| 6 | Notificación de Pago Entrante | Banco Sponsor | Plataforma PaaS |
| 7 | Webhook Enviado al PoS | Plataforma PaaS | PoS |
Descripción del Flujo
La página Flujo de Pago con Código QR explica el proceso del Código QR del diagrama, por lo que las descripciones siguientes se enfocan desde el Paso 4 en adelante. Los pasos previos dan contexto de cómo el pago entrante encaja en un ciclo de vida mayor.
Paso 4: Inicio del Pago
La Entidad Financiera originante extrae la información relevante del pago y la presenta a su cliente en el canal digital correspondiente: una app bancaria móvil (quizá escaneó el QR) o un sitio web (donde el cliente ingresó manualmente la Llave Bre-B y el monto). La Entidad Financiera resolverá la Llave Bre-B —similar a los endpoints que expone la PaaS Platform— para convertir el alias legible en la información de ruteo que usa la red y asegurar que el pago llegue al receptor deseado.
Paso 5: Enrutamiento del pago
Una vez que el cliente aprueba al receptor y confirma el envío, la Entidad Financiera originante enruta el mensaje de pago a través de la red Bre-B:
Entidad Financiera → Nodo Originante → Banco de la República → Nodo Receptor → Entidad Financiera Receptora.
Los mensajes de la red gestionan qué Entidad Financiera está conectada a qué Nodo Bre-B y aseguran la dirección correcta del envío.
Paso 6: Notificación de pago entrante
La Entidad Financiera receptora acepta la solicitud de pago entrante suponiendo que el pago supera las verificaciones AML y controles financieros (si la Cuenta existe, si fue cerrada, si el receptor está en una lista de vigilancia).
- En esta etapa, el pago está en estado
ACCEPTED, ya que el Banco Patrocinador acepta el pago tras completar monitoreo antifraude inicial y pasos AML. - Los mensajes de Pago Entrante son traducidos por la PaaS Platform y preparados para compartirse con el Desarrollador correspondiente que es dueño de la Cuenta Bancaria receptora.
Dado que el servicio Bre-B está en fases tempranas, hay información base conocida y otra que se incorporará en los próximos meses (a octubre de 2025).
Por ejemplo, un pago entrante siempre incluirá información del receptor (Nombre, Tipo y Número de Identificación), la Cuenta Bancaria (Tipo de Cuenta y Número de Cuenta) y el Participante (Número de identificación de la Entidad Financiera). Esto es lo que muchas Entidades Financieras certificaron y aprobaron.
El qr_code_reference mencionado en QR Code Payment Lifecycle se incluirá en la información del pago; no es obligatorio en el lanzamiento (aunque algunas entidades lo implementan), pero será obligatorio dentro de 3 meses tras el lanzamiento.
Asimismo, dentro de 3 meses del lanzamiento, la Llave Bre-B que usó el emisor para iniciar el pago debería estar presente en el cuerpo del pago; esto ayuda a combatir fraude y habilita oportunidades para Proveedores de Pago y Marcas.
Paso 7: Confirmación por Webhook
La PaaS Platform envía un webhook al Comercio notificando el pago entrante. Hay dos webhooks:
- uno cuando el pago llega al Banco Patrocinador, y
- otro cuando el dinero liquida en el Banco de la República.
Una vez que el Banco de la República transfiere fondos entre Entidades Financieras, el pago queda SETTLED y se envía un webhook (típicamente 7 segundos después de la notificación de pago entrante).
Identificación del pago
Mientras el ecosistema Bre-B crece, no está claro si todas las Entidades Financieras han implementado los campos obligatorios (ya que en la mayoría es autocertificación) ni si implementaron también los opcionales. Passport propone tres mecanismos para identificar un pago entrante y conciliarlo con una venta, depósito o transferencia pendiente dentro del ecosistema del Desarrollador.
Opción 1: qr_code_reference
Si se usó un Código QR para iniciar el pago entrante (como en los ejemplos de POS en la página Flujo de Pago con Código QR, la Entidad Financiera emisora está mandatada a proporcionarlo a la Entidad Financiera receptora.
Si se incluye, aparecerá en la Notificación de Pago Entrante y puede usarse para conciliar con una venta pendiente o un depósito esperado.
El campo qr_code_reference se prueba durante la certificación con entidades iniciales; sin embargo, no todas pasan por ese proceso, por lo que no está garantizado que esté presente en todos los pagos entrantes.
Opción 2: Identificadores de Llave
Si la experiencia del cliente lo permite, puede crearse una Llave única para cada pago entrante. En lugar de generar un QR único para iniciar el ciclo de pago, podría crearse una Llave Bre-B única por comprador. Esto es útil cuando el comprador recibe una Llave única a la cual enviar fondos.
Si el Desarrollador solo tiene una Cuenta de Comercio en el Banco Patrocinador, aunque no hay límites para crear Llaves, siempre se resolverán al Nombre del Comercio como Propietario.
Por ejemplo, si Passport Software SaS crea la llave alfanumérica @testuserpurchase1234, en la app bancaria del emisor igualmente aparecerá Passport Software SaS como destinatario.
Lamentablemente, la inclusión de la Llave usada por el emisor es opcional durante los primeros meses del servicio Bre-B; se espera que sea obligatoria 3 meses después del lanzamiento oficial (inicios de enero de 2026 al momento de redacción).
Opción 3: Metadatos del Pago
Como última opción, ciertos modelos de negocio pueden usar la información básica incluida en la notificación de pago entrante, por ejemplo:
- Nombre completo del Propietario
- Tipo y Número de Identificación del Propietario
- Número y Tipo de Cuenta Bancaria
- Número de Identificación de la Entidad Financiera
- Monto del Pago y marca de tiempo
Si el Desarrollador tiene usuarios registrados, su servicio puede ya tener parte de esa información y usarla para cruzarcontra pagos entrantes esperados.
Ejemplo: si una plataforma espera un pago de Test User, con Identificación 123456789, por $100.000 COP el 8-Sep-2025 a las 14:30:15, y llega un pago de Test User el 8-Sep a las 14:30:35, probablemente coincida.
Este es el método más básico para identificar pagos entrantes; sin embargo, supone que el Desarrollador cuenta con información utilizable. En escenarios de tiendas físicas, puede que no sea el caso y haya que volver a monto y fecha del pago entrante.