Creando Códigos QR

Esta especificación está sujeta a cambios, ya que se encuentra en desarrollo. El estándar colombiano EASPBV está evolucionando para soportar las capacidades de la red Bre-B.

Passport colabora activamente con actores clave de la industria para definir un modelo de integración de Códigos QR flexible y robusto para pagos en tiempo real.

Visión General

Para crear un Código QR, se deben cumplir varios pre-requisitos. El código incluye la identidad del comercio y datos contextuales, que se obtienen automáticamente de los recursos previamente creados, lo cual evita que tengas que repetir esa información en la solicitud del QR.

Requisitos Previos

Los datos del Código QR provienen de diversas fuentes:

Cliente: El cliente creado debe contener información como nombre legal, dirección, ciudad, código postal y país. Estos campos son obligatorios.

Llave Bre-B: Debes haber generado una llave vinculada a una cuenta activa. Esta llave se usará en el QR para enrutar los pagos hacia el comercio.

Configuración: Debes haber configurado el MCC (Merchant Category Code) para el comercio. Este campo es obligatorio en el QR.

Solicitud a la API: La mayoría de los datos se envían a través del endpoint , y pueden ser campos obligatorios u opcionales, según el caso de uso.

Tareas Requeridas

Paso	Descripción
1	Crear Cliente con nombre legal, dirección, ciudad, país y código postal.
2	Actualizar la configuración (`PATCH`) del cliente para incluir la información del comercio.
3	Vincular Cuenta bancaria vinculada al cliente.
4	Crear Llave al menos una llave Bre-B para la cuenta.

Una vez completados estos pasos, podrás generar el Código QR utilizando la API correspondiente (Create QR Codes.)

Creación del Código QR

Para generar un Código QR, puedes complementar la información indicada anteriormente completando los campos necesarios según tu caso de uso específico.

A continuación, se presentan diferentes ejemplos que muestran cómo generar diversos tipos de Códigos QR adaptados a los casos de uso más comunes para el procesamiento de pagos. Cada ejemplo destaca los requisitos y funcionalidades particulares asociados a distintos escenarios de pago.

Estático - Impreso

Dinámico - Punto de Ventas (POS)

Dinámico - Cajero Automatico (ATM)

Dinámico - Comercio Electrónico

Código QR Estático

Un QR estático contiene información de pago fija y no cambia una vez generado. Se suele imprimir y colocar en un espacio físico (ej., cartel, mostrador o carrito de venta).

Ideal para comercios con interacción presencial con el cliente y sin necesidad de integración con un sistema de punto de venta.

El comprador escanea el QR con su app bancaria.
Ingresa manualmente el monto y realiza el pago.
El comercio verifica el pago en su app bancaria.

No se requiere integración con un sistema de punto de venta, lo que convierte esta opción en una solución ligera para aceptar pagos a través de Bre-B.

La plataforma PaaS de Passport admite múltiples caminos de implementación: ya sea a través de cuentas de comercio dedicadas o mediante flujos gestionados por la plataforma, donde tú mantienes el control total del ciclo de vida del pago de principio a fin.

Ejemplo de Solicitud de Código QR Estático

Este ejemplo aplica para un vendedor ambulante que desea aceptar pagos Bre-B a través de un Código QR impreso en un adhesivo.

Parámetro	Descripción
ey_id	ID único de la llave Bre-B creada previamente.
customer_id	ID único del comercio (cliente).
type	Debe ser `STATIC` para este caso.
channel	`MPOS` para indicar uso en punto de venta móvil.
additional_info.transaction_purpose	Propósito de la transacción, ej.: `SHOPPING`.
additional_info.transaction.channel_presentation	Código de 3 dígitos opcional para describir cómo se presenta el canal. En este ejemplo: `010` indica que fue un sticker impreso (0), no en la ubicación registrada (1) y con cajero presente (0).

Ejemplo Cuerpo de la Solicitud

JSON
    
xxxxxxxxxx
 
curl --location 'https://bre-b-sandbox.api.visionamos.passportfintech.com/v1/paas/entities/customers/qrcodes' \--header 'Content-Type: application/json' \--header 'Authorization: TU_TOKEN_DE_ACCESO' \--data-raw '{    "type": "STATIC",    "key_id": "1234-1234-1234-1234-1234",    "customer_id": "4321-4321-4321-4321",    "channel": "MPOS",    "additional_info": {        "transaction_purpose": "SHOPPING",        "channel_presentation": "010"    }}'
Copy

Puedes agregar más campos opcionales en additional_info para enriquecer el contenido del Código QR. Consulta el endpoint Crear Códigos QR para más detalles.

Ejemplo de Respuesta - Código QR Estático

Una vez enviada la solicitud, la plataforma PaaS combina los datos y genera un Código QR que cumple con la especificación colombiana EASPBV.

Parámetro	Descripción
id	ID único del Código QR generado por la solicitud POST. Se puede usar para futuras consultas o eliminación.
qr_code data	Cadena formateada del Código QR que contiene los datos codificados. Puede mostrarse en un canal digital o imprimirse.
key	Objeto que representa el `key_value` y el `key_type` utilizados para crear el Código QR. También hace referencia al `key_id`.
acquirer_network identifier	Los Códigos QR siempre serán emitidos por VISI, entidad autorizada por el Banco de la República para emitir llaves Bre-B.
merchant	Objeto con la información del comercio: nombre, ciudad, código postal, país y código de categoría (MCC).
status	Indica que el Código QR fue creado exitosamente. Por ejemplo: `ACTIVE`.
created_at	Marca de tiempo que indica cuándo se generó el Código QR.
key_id	ID único de la llave Bre-B utilizada, creada previamente como parte de los requisitos previos.
customer_id	ID único del Cliente (comercio) creado previamente.
type	Define si el Código QR es `STATIC` o `DYNAMIC`. En este ejemplo, se eligió `STATIC`.
channel	Indica cómo el comercio presenta el Código QR al comprador. En este ejemplo, se eligió `MPOS` para punto de venta móvil.
transaction_purpose	Devuelto dentro de `additional_info`. Código opcional de tres dígitos que representa cómo se presenta el canal.
channel_presentation	Devuelto dentro de `additional_info`. Código opcional de tres dígitos que representa cómo se presenta el canal. En este ejemplo: fue un Sticker Impreso (0), no se usó en la ubicación registrada del comercio (1), y el cajero estaba presente (0) → Se envía `010`.

Ejemplo Cuerpo de Respuesta - Código QR Estático

JSON
    
xxxxxxxxxx
 
{    "id": "1234-1234-1234-1234-1234",    "qr_code_data": "00020101021226270004BREB011035142636270201M52040123530317054130000123123.125802CO5904Paas6006Bogota62470108123123130302120512123412341234070110804sale6304744F",    "key": {        "key_type": "M",        "key_value": "3503501234"    },    "acquirer_network_identifier": "VISI",    "merchant": {        "merchant_category_code": "0123",        "country": "CO",        "merchant_name": "Passport Software SaS",        "merchant_city": "Bogota",        "merchant_zip_code": "49312"    },    "status": "ACTIVE",    "created_at": "2025-04-07T10:10:10.123",    "type": "STATIC",    "key_id": "1234-1234-1234-1234-1234",    "customer_id": "4321-4321-4321-4321",    "channel": "MPOS",    "additional_info": {        "transaction_purpose": "SHOPPING",        "channel_presentation": "010"    }}
Copy

El Código QR se ha creado exitosamente y puedes utilizar el id retornado como referencia para futuras consultas o eliminaciones. El campo qr_code_data contiene la cadena codificada que puede imprimirse tantas veces como el comercio lo desee.

Beneficios del Código QR Estático

Los datos están fijos: se pueden imprimir y reutilizar múltiples veces.
El adhesivo puede colocarse en distintas partes del puesto o carrito.
No se requiere integración con sistemas de punto de venta para aceptar pagos.

La plataforma PaaS no valida los cálculos de IVA o INC ni incluye listas de impuestos aplicables. Es responsabilidad del desarrollador garantizar que todos los cargos, tasas y retenciones estén correctamente calculados como parte del flujo contable de pagos.

Última actualización el