Guía Sobre Códigos QR
Descripción General
Los Códigos QR ofrecen un mecanismo ágil para iniciar Pagos entre partes. Una persona puede generar un QR para compartir datos de pago, mientras que un Comercio puede exhibirlo para que el comprador complete una compra en un Punto de Venta (POS).
La plataforma Passport PaaS permite crear Códigos QR conformes a la especificación de la industria EMVCo en Colombia (vigente a la fecha de redacción, última actualización de julio de 2025). Estos QR pueden usarse en canales digitales y fuera de línea, reduciendo errores manuales y mejorando la experiencia de compra.
Los QR Bre-B simplifican la venta al incrustar información esencial (p. ej., Llave Bre-B, monto, propósito) en un formato escaneable, reduciendo fricción y mejorando la seguridad, ahorrando tiempo al Cliente.
Los requisitos para QR son definidos por instituciones como: ACH Colombia, Banco de la República, Credibanco, EMVCo, Mastercard, Redeban, Servibanca, Visa y Visionamos. Passport colabora con estos grupos para aportar claridad a la especificación de pagos Bre-B.
Passport, en alianza con Visionamos, opera un punto de acceso nacional a Bre-B para procesar pagos y emitir Códigos QR de uso en todo el ecosistema.
Ciclo de Vida del Pago
Los QR Bre-B pueden usarse en canales físicos y digitales: afiches, terminales POS, cajeros automáticos (ATM), sitios web y apps móviles.
Ejemplo: Compra en una Cafetería
Ejemplo de Ciclo de Vida de un Pago
La imagen representa una transacción sencilla donde un comprador realiza una compra en un punto de venta. Los pasos son:
- El Comercio crea una Venta en su sistema POS.
- El POS genera un QR Dinámico con la información de la venta usando la API de Passport PaaS y lo muestra al comprador.
- El Comprador escanea el QR con su app bancaria dentro de la Zona Bre-B.
- La app precarga destinatario (Llave Bre-B), monto y propósito de la transacción.
- El Comprador revisa y confirma la transferencia hacia la Llave Bre-B indicada.
- El pago se envía por la red Bre-B desde el banco del Comprador al Banco Sponsor de Passport.
- Passport PaaS recibe la confirmación del Nodo Bre-B e identifica al Comercio correspondiente.
- Se envía un Webhook al POS del Comercio para confirmar el pago.
Requisitos Previos
Para crear Códigos QR en la Plataforma, deben cumplirse varias condiciones. La información para generar el QR se toma de diversas fuentes:
- Cliente: El cliente creado contiene datos como nombre del Comercio y dirección (nombre, ciudad, código postal y país), que son campos obligatorios del QR.
- Llave Bre-B: Una Llave creada para una Cuenta debe incluirse en el QR Estático o Dinámico para enrutar los pagos al Comercio por la red Bre-B.
- Configuración: La Merchant Category Code (MCC) debe estar configurada en el perfil/Configuración del Comercio; es otro campo obligatorio del QR.
- Solicitud API: La mayor parte de la información se provee vía el endpoint Crear Códigos QR, con campos obligatorios u opcionales según el caso de uso.
Pasos Requeridos
Para cumplir los requisitos previos, completa:
| Paso | Descripción |
|---|---|
| 1 | Vincular Merchant con razón social, dirección, ciudad, país y código postal. |
| 2 | Vincular Cuenta asociada al Cliente activo. |
| 3 | Crear Llave Bre-B: al menos una Llave Bre-B vinculada a esa cuenta. |
Al finalizar estos pasos, reúne la información necesaria desde las fuentes relevantes para el perfil del QR. Usa el endpoint Crear Códigos QR para completar los campos restantes al crear un QR Estático o Dinámico.
Creación de Códigos QR
Para crear un QR, el debes considerar los campos principales y la información disponible para cada caso de uso.
La siguiente tabla resume consideraciones para maximizar el impacto del QR. No es la lista de campos obligatorios por endpoint, sino los principales que determinan el contenido del QR según el caso.
| Campo | Dinámico | Estático |
|---|---|---|
| type | QR de uso único, ligado a un monto específico y a la actividad en el ecosistema del desarrollador. | QR reutilizable, pues no contiene información específica de transacción. |
| channel | Dónde y cómo se presenta: p. ej., POS o MPOS (POS móvil). El POS ya generó la información de la transacción y está a la espera del pago. | Usualmente en un afiche o medio impreso. El QR Estático comparte información que no cambia por transacción (p. ej., Llave Bre-B). |
| qr_code_reference | Referencia única para asociar el QR con la acción/seguimiento del desarrollador. | No requerido |
| transaction_purpose | Describe qué representa el QR (p. ej., PURCHASE/SHOPPING). | Similar al Dinámico; también puede fijarse en el QR Estático. |
Estos son los campos más comunes para ajustar la implementación Dinámica o Estática, además de la Llave Bre-B y el Monto, cuando corresponda.
El caso de uso previsto para el QR Dinámico es aquel que está vinculado de forma única a un pago específico - por ejemplo, un comprador en el Punto de Venta (POS). El código QR se genera bajo demanda para esa compra en particular y se configura “dinámicamente” para esa venta.
El QR Estático puede imprimirse en masa y dejarse disponible para que cualquiera lo encuentre; no requiere información específica de la venta para cada persona que lo escanee. Por ejemplo, una organización benéfica podría imprimir Códigos QR Estáticos en un periódico nacional, mientras que la persona que escanee define el monto de la donación directamente en su app bancaria.
Los ejemplos a continuación demuestran como pueden ser implementados:
La PaaS Platform no verifica que los cálculos de IVA o INC sean correctos - no mantenemos un listado completo de impuestos o recargos aplicables a todas las transacciones en Colombia.
Nuestros Bancos Sponsor no asumen responsabilidad por la exactitud de esos cálculos. Corresponde al Desarrolladorgarantizar que los impuestos, tarifas y recargos se calculen adecuadamente como parte de la contabilidad del proceso de venta.