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.

Nota

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

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:

Type hereUn QR Estático contiene información fija de pago y no cambia una vez creado. Suele imprimirse y exhibirse en soportes físicos (sticker, póster, mostrador).

Ideal para entornos con interacción presencial directa, como pequeños comercios o ventas informales:

El comprador escanea el QR con su app bancaria.
El comprador ingresa el monto y envía el pago.
El comercio confirma manualmente (p. ej., revisando su app bancaria).

Fácil de Usar

No requiere integración con POS, lo que lo hace una solución ligera para aceptar Bre-B.

La plataforma soporta múltiples caminos de implementación: con cuentas dedicadas de comercio o flujos gestionados por la plataforma donde mantienes el control del ciclo de pago.

QR Estático: Ejemplo de Solicitud

El siguiente ejemplo aplica a un vendedor ambulante que desea aceptar pagos Bre-B mediante un QR Estático impreso en un sticker adherido a su carrito.

Parámetro	Descripción
key_id	ID único de la Llave Bre-B creada en el prerrequisito.
customer_id	ID único del Comercio (Customer).
type	`STATIC` para indicar que el QR es estático (`DYNAMIC` es otra opción).
channel	MPOS para indicar POS móvil.
additional_info.transaction_purpose	Dentro de `additional_info`, especifica el propósito (ej.: `SHOPPING`).
additional_info.transaction.channel_presentation	Código opcional de tres dígitos que describe el medio para detallar el canal. En este ejemplo “010”: Sticker impreso (0), fuera del domicilio comercial registrado (1), cajero presente (0).

QR Estático: Cuerpo de la Solicitud

curl --location --request POST 'https://api.paas-sandbox.co.passportfintech.com/qrcodes' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer 17d5cc1adb6f6c90d5aa73f74b38f9fa3336d04aee6cf8121a3cf19f190e6213' \ --data '{ "key_id": "1f2046b7-428d-4682-b6f2-3fe438ae5a3e", "customer_id": "291b10c1-b86a-4741-a49f-ff55c46190d8", "type": "STATIC", "channel": "POS", "additional_info":{ "transaction_purpose": "SHOPPING" } }'

Existen campos opcionales adicionales dentro de additional_info para enriquecer el QR. Revisa el endpoint Crear Códigos QR para conocerlos y sus usos.

QR Estático: Ejemplo de Respuesta

Una vez enviada la solicitud, la plataforma PaaS combina la información de las distintas fuentes y genera un QR conforme a la Especificación EASPBV (Colombia) para QR. La respuesta mantiene un formato similar al de otros recursos.

Parámetro	Descripción
id	ID único del QR creado; úsalo para futuras consultas o eliminación.
qr_code data	Cadena formateada del QR; puede presentarse digitalmente o imprimirse.
key	Objeto con `key_value` y `key_type` usados, referenciados por `key_id`.
acquirer_network identifier	Los QR siempre serán emitidos por VISI, emisor autorizado por el Banco de la República para llaves Bre-B.
merchant	Objeto con información del Comercio (nombre, ciudad, CP, país, MCC).
status	Estado de creación (ACTIVE - ACTIVO).
created_at	Marca de tiempo de creación.
key_id	ID único de la Llave usada.
customer_id	ID único del Cliente.
type	STATIC o DYNAMIC (en este ejemplo, STATIC).
channel	Cómo se presenta el QR (p. ej., MPOS).
transaction_purpose	Dentro de `additional_info`; en el ejemplo, `SHOPPING`.
channel_presentation	Dentro de `additional_info`; código de tres dígitos para detallar el canal (ej.: 010 = Sticker impreso (0), fuera del domicilio (1), cajero presente (0)).

QR Estático: Cuerpo de la Respuesta

{ "created_at": "2025-05-12T20:30:17.547227Z", "qr_code_data": "00020101021226550015CO.COM.VISI.LLA0332jimmyjohns1111402545255@test.com49270015CO.COM.VISI.RED0104VISI52045782530317054130000100000.005802CO5919Test Business O9F126006Bogota61059827362120808PURCHASE80290017CO.COM.VISI.CANAL0104MPOS81260016CO.COM.VISI.CIVA01020282290015CO.COM.VISI.IVA0106100.0083300016CO.COM.VISI.BASE0106100.0084260016CO.COM.VISI.CINC01020285280015CO.COM.VISI.INC010510.0090610017CO.COM.VISI.TRXID01364A07229A-7B14-4B63-85D5-79572E130E0763040351", "qr_code_image": "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", "acquirer_network_identifier": "VISI", "key_id": "7756cfcb-0d28-4e89-bbc0-d4ebdc5b6ca1", "id": "7aa184b7-c549-467b-917f-460b4224b459", "entity_customer_id": "0d93dea5-00c4-4a9e-b3fa-cbaf5280818b", "merchant": { "merchant_category_code": "1234", "country": "CO", "merchant_name": "Test Business O9F12", "merchant_city": "Bogota", "merchant_zip_code": "98273" }, "status": "ACTIVE", "type": "STATIC", "key": { "key_type": "EMAIL", "key_value": "jimmyjohns1111402545255@test.com" }, "channel": "MPOS", "additional_info": { "transaction_purpose": "SHOPPING" } }

El QR se creó correctamente. Puedes usar el id para consultarlo o eliminarlo más adelante. El campo qr_code_data contiene la cadena codificada imprimible (tantas copias como desees). Alternativamente, qr_code_image entrega la imagen en base64 para uso inmediato.

Ventajas del QR Estático

Datos fijos: El mismo Qr generado con todos sus datos una única vez puede reimprimirse y reutilizarse.
El sticker puede colocarse en múltiples lugares para facilitar el escaneo.
Sin integración compleja con POS para generar y recibir pagos.

QR Dinámico: Punto de Venta (POS)

Un Código QR Dinámico se genera para cada venta e incluye todos los datos de pago necesarios. Por ejemplo, el sistema POS crea el QR al momento del checkout y el Comprador lo escanea para completar el pago. Esto agiliza el proceso: no se requiere ingreso manual y el QR ya contiene los datos Bre-B necesarios.

Para usarlo, el POS debe estar integrado con la plataforma Passport PaaS para generar, consultar y eliminar Códigos QR durante la transacción.

Los QR Dinámicos son ideales para entornos de alto tráfico (p. ej., supermercados con múltiples self-checkout). Passport provee herramientas para que los Desarrolladores gestionen estos flujos y ofrece opciones de Cuentas de Comercio, brindando flexibilidad y control sobre el ciclo de pago.

QR Dinámico (POS): Ejemplo de Solicitud

Caso de Uso: un Comercio desea aceptar pagos Bre-B usando un QR Dinámico generado por un POS. El QR incluirá información adicional que el Comprador ingresó en la pantalla del checkout.

Parámetro	Descripción
key_id	Identificador único de la Llave Bre-B creada en los requisitos previos.
customer_id	Identificador único del Comercio (Cliente).
type	Tipo de QR: `DYNAMIC` en este caso.
qr_code_ reference	Identificador único que el emisor incluirá en el pago entrante para que el desarrollador relacione pagos ↔ compras.
channel	Canal de presentación del QR. Usa POS para Punto de Venta fijo (o `MPOS` para POS móvil).
amount.value	Monto a pagar (ej.: `80000.57`).
amount.currency	Moneda (ej.: `COP`).
vat.vat_type	Tipo de cálculo de IVA (`FIXED` o `PERCENTAGE`).
vat.vat_value	Valor o porcentaje para calcular el IVA (según `vat_type`).
vat.vat_base value	Base gravable del IVA.
inc.inc_type	Tipo de cálculo de INC (`FIXED` o `PERCENTAGE`).
inc.inc_value	Valor o porcentaje para calcular el INC (según `inc_type`).
additional_info. transaction_purpose	Propósito de la transacción (ej.: `PURCHASE`/`SHOPPING`).
additional_info. channel_presentation	Código opcional de tres dígitos que detalla el medio/canal. Ej.: 601 = Merchant POS (6), en el domicilio registrado (0), self-checkout (1).
additional_info. invoice_number	Número de factura generado automáticamente para conciliación contable.
additional_info. loyalty_label	Identificador de lealtad ingresado por el comprador (o derivado por teléfono/email).
additional_info. terminal_label	Identificador único del terminal (caja/punto de cobro) donde se procesó la venta.

QR Dinámico (POS): Cuerpo de la Solicitud

curl --location --request POST 'https://api.paas-sandbox.co.passportfintech.com/qrcodes' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer 27fb56c030a12d5cb302229531b4cc59d651996d0c3c0bb5933940ef25b42dbd' \ --data '{ "key_id": "e0363dd5-3e0e-4ade-b89a-d743c4bdad59", "customer_id": "19a0ab02-cbaa-4a7f-8ec3-6cc4224d30e7", "type": "DYNAMIC", "channel": "MPOS", "vat": { "vat_type": "FIXED", "vat_value": "11.00", "vat_base_value": "0.00" }, "inc": { "inc_type": "FIXED", "inc_value": "12.00" }, "tip": { "tip_type": "PERCENTAGE", "tip_percentage": "5.00" }, "amount": { "value": "80000.57", "currency": "COP" }, "qr_code_reference": "PAS1234512354520250929", "additional_info":{ "transaction_purpose": "PURCHASE", "channel_presentation": "601" } }'

QR Dinámico (POS): Ejemplo de Respuesta

Al enviar la solicitud, la plataforma Passport PaaS arma un QR conforme a la Especificación EASPBV (Colombia). La respuesta sigue el formato de otros recursos.

Parámetro	Descripción
qr_code_id	IIdentificador único del Código QR. Úsalo para recuperarlo o eliminarlo más adelante.
qr_code data	Cadena formateada del QR que puede presentarse en un canal digital o convertirse e imprimirse.
qr_code_image	Imagen del QR en base64.
key	Objeto que representa `key_value` y `key_type` utilizados para crear el QR (también referenciados por `key_id`).
acquirer_network identifier	Emisor del QR. Para Bre-B, siempre VISI, autorizado por el Banco de la República.
merchant	Objeto con la información del Comercio (nombre, ciudad, código postal, país y código de categoría/MCC).
status	Estado del Código QR para confirmar que fue creado correctamente (p. ej., `ACTIVE`).
created_at	Marca de tiempo que indica cuándo se creó el QR
key_id	ID único de la Llave Bre-B creada en los prerrequisitos.
customer_id	ID único del Customer creado en los prerrequisitos.
type	Tipo de Código QR (en este caso, `DYNAMIC`).
channel	Canal en el que se presenta el QR (p. ej., `POS` para Punto de Venta).
amount.value	Monto del pago (ej.: `80000.57`).
amount.currency	Moneda (ej.: `COP`).
qr_code_ reference	Referencia única que el emisor incluirá en el pago entrante para que el desarrollador relacione pagos con compras.
vat.vat_type	Indicador de cómo se calculará el IVA (`FIXED` o `PERCENTAGE`).
vat.vat_value	Valor o porcentaje para calcular el IVA según el `vat_type`.
vat.vat_base value	Base gravable del IVA.
inc.inc_type	Indicador de cómo se calculará el INC (`FIXED` o `PERCENTAGE`).
inc.inc_value	Valor o porcentaje para calcular el INC según el `inc_type`.
additional_info. transaction_purpose	Propósito de la transacción (en este ejemplo, `SHOPPING`).
additional_info. channel_presentation	Código opcional de tres dígitos que detalla el medio/canal. Ejemplo: 401 = Merchant POS (4), en el domicilio registrado (0), cajero no presente (1).
additional_info. invoice_number	Número de factura generado automáticamente para conciliar el pago en el sistema contable.
additional_info. loyalty_label	Número/ID de lealtad que el comprador ingresó en el POS (o extraído tras identificarse por teléfono o email).
additional_info. terminal_label	Identificador único del terminal que procesó la venta, para rastrear el punto de cobro específico.

QR Dinámico (POS): Cuerpo de la Respuesta

{ "tip": { "tip_type": "PERCENTAGE", "tip_percentage": "5.00" }, "status": "ACTIVE", "channel": "MPOS", "customer_id": "19a0ab02-cbaa-4a7f-8ec3-6cc4224d30e7", "created_at": "2025-05-28T14:20:51.457775Z", "qr_code_id": "52e7fcbc-4527-4e24-a604-a9501ea9bbe9", "inc": { "inc_value": "12.00", "inc_type": "FIXED" }, "additional_info": { "transaction_purpose": "PURCHASE", "channel_presentation": "601" }, "amount": { "value": "80000.57", "currency": "COP" }, "qr_code_reference": "PAS1234512354520250929", "key_id": "e0363dd5-3e0e-4ade-b89a-d743c4bdad59", "acquirer_network_identifier": "VISI", "vat": { "vat_type": "FIXED", "vat_value": "11.00", "vat_base_value": "0.00" }, "key": { "key_type": "ALPHA", "key_value": "@A2IEN44GW553GCN" }, "qr_code_image": "iVBORw0KGgoAAAANSUhEUgAAAwIAAAMCAQAAAADyx0wVAAAJc0lEQVR4nO2dT46jSgzGPz8iZVlIc4AcBW7W6iPNDeAofYCWYNkSyG9RVbaLHmkWbwZeoo9Fq0kgPwXJ8X9bFH/3mP/5ywCABBJIIIEEEkgggQQSSCCBBBKuIUg5bvW/fi+nI3YBsIuMq4hIDwDYBVhvkHEVwSwiwFr+lOtERMZTvwMJJJAQCIOqqi6AqqrW174EQKeY5a5A2oBh2UWk71Sk30XfH6pAUsXcAyIPVZ3QafiUV3pKJJDwBIQixMMCYFiqNA4LoJpfK5eo6gad0pbf0An+7pbvLR+wdAqg0/xDMb3CUyKBhOcliIgIkFRlRKeYH6oAdsHcF1mVManKmDa7qVOd0pcAaYOMvyH8+YMEEkjw43Z8Yfj5YxNgz2+o/YfynwCzAIr1rjL33SZIn7dsaM/SbcfPe4mnRAIJz0Ootnf2p4v9DKDL7nV2lgfdqomd/eQuON/FFE8biivtFjxtbxJIuIowiwe1kf1kGdEpho8bgPWuMq53BdZbeFfG9Vb+e/u4q7zlN3YpFvy534EEEkhAtb1jgWj6kvLaCmB+bFCse5XQtOU/+bW5R3kjX4cvAVJbbvoKT4kEEp6HEGzvEvyuJnaT1Spx73KkYorrlKo9bvfmgHgx2Wl7k0DC2QQcRDenp6Yc1K5u8xTc6+14GuU3lfy0/yhQpkkg4VyCJZ+1hseSapHpVLPSHi3zkNlUryvRsnxvjaWhFp5Qpkkg4VxCkOlgThf5tWj3gmKAW2Qbuapk6YpgFxUNk2m74xWeEgkkPA/B6shqFmpCkct6agoXQBTi/IY71Z7pAkKmizJNAgmnEhAEtlR0IxjWRYizi7xZFKxT191FqQNBpqNmf4WnRAIJz0OoMp226hOjyHQwticAxdEGik72I8fDGh1fq1Qo0ySQcDYh9nAUB1o1dmilWEKWpXYCULVzF0NrWiW5nlKmSSDhbEIjgwsQpREITnVjdjd/AESJL+1c7MsigYRLCIjya02TgP1pgt8lKAbrtfTIWKqRNstPU6ZJIOECgtWRuTgjRMayZw3LVrllboUnQb2XO0r5KGWaBBIuIJR677n/RKnjxn7D3HeQQXfJp8PPe3a5BSjF4fVdQIZpy58iwC4YFqgEwis8JRJIeB6C1YZ2IQvlVWFNEyaC21yta1PHdURCzV6DepoEEq4ghFyWF37mIzrQ3TEDXU121ZDMNg88jDyiTJNAwiWE9QadVglGc9a1ebxgPdWpWNcQ6fc4LfQte+C7ZB/7/aEq48nfgQQSSMCv8tMe4tpq9clSL56ANjTeGOpI3mvJGBkJJFxCaHo4LKmsNgDUDfAyk6i6zeHdOqzIg+SsDSWBhKsIMZeF5H2Vsbb7EPaqmS7PbVs3h/VqsYeDBBIuIlgxqPdluYQCtZYkThEsdraVpQzenGUaOxeTUaZJIOF0QjM3tCrhqLa/l3of2rQAr00BcCwdp0yTQMKpBERJXqzzeYGlptHa4760A3DBjqOM0NaAv8JTIoGE5yE0u3XU7WzzkxcgusheNBqscDSlKkGLU6ZJIOFsQutPw+xsa8ZYAG+drhFwIJriKfZ1KPunSSDhSoIvzhFF2m6KtQcGBYD0KQC6DXmtTlogSJ/APAIYlh8bhqWHDB93BdLnrVy89id/BxJIICEcwZ/OR4rRstA56X6y3+s2+mQfBQC0vUkg4SpCWEQbks9+lClGlnxWT2Y3LZpha237KZRpEki4gjDLDXkZ1vzYkPdgSb+LjKvtywLKJQCguuxSbsMumB82o2xtd2W+0FMigYSnIcjbApQo9iqC+fElPolI3x8bMCy71EvuKiL3ot4tglbW5KUNmPtdZDz1O5BAAgkA4ijBfGTfuVaQlIGitSwl3OflJsVG9xUcAG1vEki4ihAGhcYiTxNOmwfqYbRmFNnWZqVVY26bMk0CCacTbCaCfo9xJ9e/LqbNtN8JMXAeS8Ip0ySQcA3hWx2Zr6oMPdBVQsNKWlur09SAxyA5ZZoEEi4gNKP5Fx8UGhVzncpvDvRyGPINeH4rDhSlTJNAwumEdh6ZN1HHruk47KTG0mo8zEaAL/XzfITwQJkmgYTTCe0ejoPWdRM76u5Qc1I+oNkzb3Uo1NMkkHABoZ1zohbd2qxfw/zkqrvjdvmlWTidD1PvlGkSSLiKoNN611wBNuhXHR663gCkcqrvPYBsbK8ipY6sj2PBm6pxk/PXeUokkPAMhHZ9pdagmMZEVdiZYxq79FmHvo4u6G7ODSWBhKsIzXLaQxN1igVmPkDQM11uo3ta2z1w2t4kkHABIcwCPoS98hET0q67v88os1+Gcht7LUkg4RpCI6s15dxExqxNuq0oO84u8nbMxaaaUaZJIOF0wi8GGcQ67sOcIs95eX6rJq98HpldR5kmgYTTCd/mhobRJSnmqFyVu6FelbVqmO/t2/Boe5NAwvmEY18WUCcRxXH9MB871dB40MSwnswFOC6gp0yTQMKphLaOzH1nO62+s59WYW+LvrXZc8tcFgkkXEQIO+VrWbeZ04gR8No1XfR0XIlXFbOPTYih8Vd4SiSQ8DyEoKfDi1kaUxMy8zYPX2JrbdKuu4PZTdubBBLOJzQzEVKtJXET29qpG6fahL1V1l4mPoG5LBJIuIQQZiLEyHY7jigsonWlnhrtXBLS3p1J25sEEi4hNDP7szpu258BBMvcPOZgntsw/8NyLco0CSRcQGj3cBxKyJp9WVqHndSo2mE31hbTYtxVSwIJFxHa/dO2VcPGHEwAQjFKMNTboJip96qs6U+TQMK1BNu5AQBzD8ibD+kHgOFD8lHOVynvDh8iGJYy+V+kBwB0dXPHSz0lEkj43xNCX1bU2G6Km2I2FzleUqPd+Ga3g/40CSRcRygaWOKmK9U88WSXHArLG7HWGzCLiIxZRd8gY42RifS7lEtsAMoLPSUSSHgiwlCjW/ouIi6cMvqltgzLS0DnvlN97+Ni+XLJYp1cL/SUSCDhCQjNzH7PSi9W5e1DTH7RpmU56zh8sPlk2t4kkHAtQaf0JT5ZEFhvtRjl436cQlbWYa4i8rZ0iuFDxH8jZPwl4c8fJJBAQjgOeromnz3i5eWe36aVhUyXjy3yalLqaRJIOJ/Q5KdrWaiGOYH+2oIg2J6GLmUp9VegeNasOSGBhGsIcXZRcKXbms/Dvsp2FIq3XftQBeaySCDhKoLo76/5T8f8Ck+JBBJIIIEEEkgggQQSSCCBBBLa419DhUlan3DsRwAAAABJRU5ErkJggg==", "type": "DYNAMIC", "merchant": { "country": "CO", "merchant_name": "Passport zqEkYq", "merchant_city": "Bogota", "merchant_zip_code": "98273", "merchant_category_code": "1234" }, "qr_code_data": "00020101021226390015CO.COM.VISI.LLA0416@A2IEN44GW553GCN49270015CO.COM.VISI.RED0104VISI52045782530317054130000640000.0055020357045.005802CO5915Passport zqEkYq6006Bogota61059827362190808PURCHASE110360180290017CO.COM.VISI.CANAL0104MPOS81260016CO.COM.VISI.CIVA01020282280015CO.COM.VISI.IVA010511.0083280016CO.COM.VISI.BASE01040.0084260016CO.COM.VISI.CINC01020285280015CO.COM.VISI.INC010512.0090610017CO.COM.VISI.TRXID0136800F9050-CE3E-4759-90AE-085FAB68107D630485F9" }

Notas para Desarrolladores

Una respuesta 201 Created (o 200 OK según tu implementación) confirma que el QR se creó correctamente.
Usa qr_code_id para gestionar el ciclo de vida del QR (consultar/eliminar).
Convierte qr_code_data o qr_code_image (base64) en imagen con librerías estándar en React, Angular, iOS (Swift) o Android (Kotlin).
Los QR Dinámicos son flexibles y específicos por transacción: ideales para retail, restaurantes y supermercados.

Beneficios del QR Dinámico

Datos flexibles: cada QR puede combinar llave, canal, propósito y presentación distintos, además de campos opcionales (IVA, INC, propina, referencias).
Programable por transacción: se genera único para cada venta mediante la integración con el POS.
Escalable: soporta alto volumen y se adapta a supermercados, restaurantes, centros deportivos, comercios minoristas y vendedores sofisticados.

QR Dinámico: Comercio Electrónico (Online Shopping)

Un Código QR Dinámico contiene información de pago variable y se crea bajo demanda para ajustarse a la transacción o venta específica que se está completando en ese momento.

En este ejemplo, una plataforma de ecommerce puede crear un Código QR para que la persona compradora lo escanee desde la pantalla de su computador, pague la compra y complete el proceso de checkout.

El QR Dinámico es adecuado para este entorno porque se espera que el operador del sitio procese múltiples pedidos simultáneamente en cualquier momento del día y desee operación 24/7 de sus sistemas de pago, brindando a sus compradores el medio más conveniente para pagar bienes.

Passport proporciona la infraestructura para que los Desarrolladores participen en el flujo de fondos, o bien utilicen Cuentas de Comercio dedicadas con visibilidad de las transacciones, pudiendo elegir el método de implementación mientras mantienen el control para confirmar el ciclo de vida del pago.

QR Dinámico Comercio Electrónico (Online Shopping): Ejemplo de Solicitud

El siguiente ejemplo puede usarse en un sitio de ecommerce que quiera ofrecer a sus compradores la opción de pagar en línea. El operador del sitio se conecta a la PaaS Platform para crear Códigos QR Dinámicos para que cada comprador los escanee en el checkout y se vinculen a su pedido.

Parámetro	Descripción
key_id	Identificador único de la Llave Bre-B creada en un paso previo.
customer_id	Identificador único del comercio (Customer).
type	Tipo de Código QR; en este caso, `DYNAMIC`.
channel	Indica cómo se presenta el QR. En este ejemplo, el desarrollador elegirá `ECOMM` para un sitio de ecommerce.
amount.value	Monto a pagar (p. ej., `200000.00`).
amount.currency	Moneda de la Transacción (`COP`)
qr_code_reference	Identificador único que el emisor incluirá en el pago entrante para que el desarrollador rastreé e identifique pagos con compras.
vat.vat_type	Indicador de cómo se calculará el IVA (`FIXED` o `PERCENTAGE`).
vat.vat_value	Valor o porcentaje para calcular el IVA según `vat_type`.
vat.vat_base_value	Base para el cálculo del IVA.
inc.inc_type	Indicador de cómo se calculará el INC (`FIXED` o `PERCENTAGE`).
inc.inc_value	Valor o porcentaje para calcular el INC según `inc_type`.
additional_info.transaction_purpose	Propósito de la transacción; en este ejemplo se usará SHOPPING/PURCHASE.
additional_info.channel_presentation	Código opcional de tres dígitos que describe el medio/canal con más detalle. En este ejemplo: 521 = Pantalla – Sitio web (5), comercio remoto (2), checkout autoatendido (1).
additional_info.invoice_number	Identificador único creado por el sitio para vincular el checkout al Código QR.
additional_info.customer_label	Identificador único del comprador (desde el CRM del ecommerce) para vincularlo al Código QR.

QR Dinámico Comercio Electrónico (Online Shopping): Cuerpo de la Solicitud

curl --location --request POST 'https://api.paas-sandbox.co.passportfintech.com/qrcodes' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer 27fb56c030a12d5cb302229531b4cc59d651996d0c3c0bb5933940ef25b42dbd' \ --data '{ "key_id": "0fb7e5fa-e26f-4195-a94e-ec054e767ac8", "customer_id": "19a0ab02-cbaa-4a7f-8ec3-6cc4224d30e7", "type": "DYNAMIC", "channel": "ECOMM", "vat": { "vat_type": "FIXED", "vat_value": "100.00", "vat_base_value": "100.00" }, "inc": { "inc_type": "FIXED", "inc_value": "10.00" }, "amount": { "value": "200000.00", "currency": "COP" }, "qr_code_reference": "PAS202509291038dn2137d", "additional_info":{ "transaction_purpose": "PURCHASE", "loyalty_label": "124567938", "channel_presentation": "521" } }'

QR Dinámico Comercio Electrónico (Online Shopping): Ejemplo de respuesta

Una vez enviada la solicitud, la PaaS Platform combina información de distintas fuentes para crear un Código QR conforme a la Especificación EASPBV (Colombia) para Códigos QR. La respuesta se entrega en un formato similar al de otros recursos.

Parámetro	Descripción
qr_code_id	ID único del Código QR creado (útil para consultar o eliminar después).
qr_code data	Cadena formateada para el QR que puede presentarse en un canal digital o imprimirse.
key	Objeto con `key_value` y `key_type` usado para crear el QR (referenciado por `key_id`).
acquirer_network_identifier	Emisor del QR; para Bre-B será VISI, autorizado por el Banco de la República.
merchant	Información del comercio (nombre, ciudad, código postal, país y MCC).
status	Estado del QR para confirmar su creación exitosa (p. ej., `ACTIVE`).
created_at	Marca de tiempo de creación del QR.
key_id	ID único de la Llave Bre-B (prerrequisito).
customer_id	D único del Cliente (prerrequisito).
type	Tipo de QR; en este ejemplo, `DYNAMIC`.
channel	Cómo se presenta el QR; para ecommerce, `ECOMM`.
amount.value	Monto a pagar (p. ej., `200000.00`).
amount.currency	`COP`
qr_code_reference	Referencia única que el emisor incluirá en el pago entrante para rastrear pagos y compras.
vat.vat_type	Indicador de cómo se calculará el IVA (`FIXED` o `PERCENTAGE`).
vat.vat_value	Valor o porcentaje para calcular el IVA según `vat_type`.
vat.vat_base value	Base para el cálculo del IVA.
inc.inc_type	Indicador de cómo se calculará el INC (`FIXED` o `PERCENTAGE`).
inc.inc_value	Valor o porcentaje para calcular el INC según `inc_type`.
additional_info.transaction_purpose	Propósito de la transacción; en este ejemplo se usará SHOPPING/PURCHASE.
additional_info.channel_presentation	Código de tres dígitos que describe el medio/canal (ej.: 521).
additional_info.store_label	Identificador opcional de ubicación (si aplica).
additional_info.terminal_label	Identificador opcional del “terminal” (si aplica).

QR Dinámico Comercio Electrónico (Online Shopping): Cuerpo de la Respuesta

{ "inc": { "inc_type": "FIXED", "inc_value": "10.00" }, "amount": { "value": "200000", "currency": "COP" }, "additional_info": { "transaction_purpose": "PURCHASE", "loyalty_label": "124567938", "channel_presentation": "521" }, "qr_code_reference": "PAS202509291038dn2137d", "status": "ACTIVE", "type": "DYNAMIC", "qr_code_data": "00020101021226330015CO.COM.VISI.LLA0210353250300149270015CO.COM.VISI.RED0104VISI52045782530317054130000200000.005802CO5915Passport zqEkYq6006Bogota61059827362320808PURCHASE0409124567938110352180300017CO.COM.VISI.CANAL0105ECOMM81260016CO.COM.VISI.CIVA01020282290015CO.COM.VISI.IVA0106100.0083300016CO.COM.VISI.BASE0106100.0084260016CO.COM.VISI.CINC01020285280015CO.COM.VISI.INC010510.0090610017CO.COM.VISI.TRXID0136240E0CBF-294B-4C30-9684-9313605D714C63042088", "acquirer_network_identifier": "VISI", "qr_code_image": "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", "qr_code_id": "45735c23-72fa-4952-b0ba-9a3d6bd01450", "account_key_id": "0fb7e5fa-e26f-4195-a94e-ec054e767ac8", "created_at": "2025-05-28T14:20:22.542258Z", "channel": "ECOMM", "key": { "key_value": "3532503001", "key_type": "MOBILE" }, "vat": { "vat_base_value": "100.00", "vat_type": "FIXED", "vat_value": "100.00" }, "merchant": { "country": "CO", "merchant_name": "Passport zqEkYq", "merchant_city": "Bogota", "merchant_zip_code": "98273", "merchant_category_code": "1234" }, "entity_customer_id": "19a0ab02-cbaa-4a7f-8ec3-6cc4224d30e7" }

Notas para Desarrolladores

Como en el ejemplo de QR Estático, el HTTP 200 OK indica que el QR se creó correctamente; el desarrollador puede usar el qr_code_id retornado para consultarlo o eliminarlo cuando sea necesario.
El campo qr_code_data contiene la cadena codificada que puede mostrarse en el sitio de ecommerce con el formato deseado. Existen librerías para JavaScript, React y Angular que convierten el texto en una imagen que la persona puede escanear con su app bancaria.
Para mayor facilidad, el campo qr_code_image también devuelve la imagen en base64.

QR Dinámico: Cajero Automático (ATM)

Un Código QR Dinámico contiene información de pago variable y se genera bajo demanda para la transacción específica que se está realizando.

En este ejemplo, el operador de un ATM permite que una Persona retire efectivo usando un Código QR para iniciar un pago Bre-B antes de dispensar el retiro. Así, toda la información requerida por el ATM se presenta al usuario y se simplifica la experiencia (no hay que ingresar manualmente referencias o datos de ubicación).

Este esquema requiere integración entre el sistema de ATM y la plataforma PaaS para crear, consultar y eliminar QR de manera dinámica para cada retiro o depósito, y administrarlos durante el ciclo de efectivo.

El QR Dinámico se adapta bien a operadores con múltiples ubicaciones y alto volumen de transacciones simultáneas.

Passport provee la infraestructura para que los Desarrolladores participen en el flujo de fondos o utilicen Cuentas de Comercio dedicadas, manteniendo visibilidad y control para confirmar el ciclo del Pago.

QR Dinámico (ATM): Ejemplo de Solicitud

Caso de Uso: un Operador de ATM desea vincular un pago Bre-B mediante un QR Dinámico, asegurando que la transferencia llegue antes de dispensar efectivo.

Parámetro	Descripción
key_id	Identificador único de la Llave Bre-B creada en los requisitos previos.
customer_id	Identificador único del Comercio (Cliente).
type	Tipo de QR: `DYNAMIC` en este caso.
channel	Canal de presentación del QR. Usa ATM para Cajero Automático.
amount.value	Monto a pagar (ej.: `80000.57`).
amount.currency	Moneda (ej.: `COP`).
qr_code_reference	Referencia única que el emisor incluirá en el pago entrante para relacionar pagos ↔ retiros.
vat.vat_type	Tipo de cálculo de IVA (`FIXED` o `PERCENTAGE`).
vat.vat_value	Valor o porcentaje para calcular el IVA (según `vat_type`).
vat.vat_base_value	Base gravable del IVA.
inc.inc_type	Tipo de cálculo de INC (`FIXED` o `PERCENTAGE`).
inc.inc_value	Valor o porcentaje para calcular el INC (según `inc_type`).
additional_info. transaction_purpose	Propósito de la transacción (p. ej., `WITHDRAWAL`).
additional_info. channel_presentation	Código opcional de tres dígitos que detalla el medio/canal. 712 = Pantalla/otro (7), fuera del domicilio comercial (1), autoatendido (2).
additional_info. store_label	Identificador de la tienda/ubicación (si el ATM está en un comercio o gasolinera).
additional_info. terminal_label	Identificador del terminal para rastrear la máquina específica.

QR Dinámico (ATM): Cuerpo de la Solicitud

curl --location --request POST 'https://api.paas-sandbox.co.passportfintech.com/qrcodes' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer 27fb56c030a12d5cb302229531b4cc59d651996d0c3c0bb5933940ef25b42dbd' \ --data '{ "key_id": "e0363dd5-3e0e-4ade-b89a-d743c4bdad59", "customer_id": "19a0ab02-cbaa-4a7f-8ec3-6cc4224d30e7", "type": "DYNAMIC", "channel": "ATM", "vat": { "vat_type": "FIXED", "vat_value": "0.00", "vat_base_value": "0.00" }, "inc": { "inc_type": "FIXED", "inc_value": "0.00" }, "qr_code_reference": "PAS2025092912345adsf", "amount": { "value": "40000.00", "currency": "COP" }, "additional_info":{ "transaction_purpose": "WITHDRAWAL", "channel_presentation": "712" } }'

QR Dinámico (ATM): Ejemplo de Respuesta

Una vez enviada la solicitud, la plataforma PaaS combina información de varias fuentes y genera un QR conforme a la Especificación EASPBV (Colombia). La respuesta mantiene un formato similar al de otros recursos.

Parámetro	Descripción
id	Identificador único del QR para consultar o eliminar.
qr_code_data	Cadena formateada con el contenido EMV del QR (útil para renderizado/impresión).
key	Objeto con `key_value` y `key_type` utilizados (referenciados por `key_id`).
acquirer_network identifier	Emisor del QR; para Bre-B, VISI (autorizado por Banco de la República).
merchant	Información del comercio (nombre, ciudad, CP, país, MCC).
status	Estado del QR (p. ej., `ACTIVE`).
created_at	Marca de tiempo que indica cuándo se creó el QR
key_id	ID único de la Llave Bre-B creada en los prerrequisitos.
customer_id	ID único del Customer creado en los prerrequisitos.
type	Tipo de Código QR (en este caso, `DYNAMIC`).
channel	Canal en el que se presenta el QR (p. ej., `ATM` para Cajero Automatico).
amount.value	Monto del pago (ej.: `80000.57`).
amount.currency	Moneda (ej.: `COP`).
qr_code_reference	Referencia única para seguimiento.
vat.vat_type	Indicador de cómo se calculará el IVA (`FIXED` o `PERCENTAGE`).
vat.vat_value	Valor o porcentaje para calcular el IVA según el `vat_type`.
vat.vat_base_value	Base gravable del IVA.
inc.inc_type	Indicador de cómo se calculará el INC (`FIXED` o `PERCENTAGE`).
inc.inc_value	Valor o porcentaje para calcular el INC según el `inc_type`.
additional_info.transaction_purpose	Propósito de la transacción (en este ejemplo, `WITHDRAWL`).
additional_info.channel_presentation	Código opcional de tres dígitos que detalla el medio/canal.
additional_info.store_label	Número/ID de lealtad que el comprador ingresó en el ATM (o extraído tras identificarse por teléfono o email).
additional_info.terminal_label	Identificador único del terminal que procesó la venta, para rastrear el punto de cobro específico.

QR Dinámico (ATM): Cuerpo de la Respuesta

{ "inc": { "inc_type": "FIXED", "inc_value": "0.00" }, "amount": { "value": "40000", "currency": "COP" }, "additional_info": { "transaction_purpose": "WITHDRAWAL", "channel_presentation": "712" }, "status": "ACTIVE", "type": "DYNAMIC", "qr_code_data": "00020101021226390015CO.COM.VISI.LLA0416@A2IEN44GW553GCN49270015CO.COM.VISI.RED0104VISI52045782530317054130000040000.005802CO5915Passport zqEkYq6006Bogota61059827362210810WITHDRAWAL110371280280017CO.COM.VISI.CANAL0103ATM81260016CO.COM.VISI.CIVA01020282270015CO.COM.VISI.IVA01040.0083280016CO.COM.VISI.BASE01040.0084260016CO.COM.VISI.CINC01020285270015CO.COM.VISI.INC01040.0090610017CO.COM.VISI.TRXID013608B7F5FB-22AE-4CE6-BE36-CDE8C674D16263044D66", "acquirer_network_identifier": "VISI", "qr_code_image": "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", "qr_code_id": "5576c7f0-0761-49dc-b2ae-cf64e6106d07", "key_id": "e0363dd5-3e0e-4ade-b89a-d743c4bdad59", "created_at": "2025-05-28T14:20:46.531062Z", "channel": "ATM", "key": { "key_value": "@A2IEN44GW553GCN", "key_type": "ALPHA" }, "vat": { "vat_base_value": "0.00", "vat_type": "FIXED", "vat_value": "0.00" }, "merchant": { "country": "CO", "merchant_name": "Passport zqEkYq", "merchant_city": "Bogota", "merchant_zip_code": "98273", "merchant_category_code": "1234" }, "qr_code_reference": "PAS2025092912345adsf", "customer_id": "19a0ab02-cbaa-4a7f-8ec3-6cc4224d30e7" }

Igual que en el caso de QR Estático, el HTTP 201 Created confirma que el QR se creó correctamente y puedes usar el idpara gestionarlo (consultar/eliminar).

qr_code_data contiene la cadena codificada que el ATM puede mostrar en pantalla. Hay librerías para JavaScript/React/Angular, Android (Kotlin) y iOS (Swift) que convierten el texto en imagen. El endpoint también puede devolver la imagen en base64 en qr_code_image (si tu implementación usa qr_image_data, unifica el nombre de campo para mantener consistencia).

Beneficios del QR Dinámico (ATM)

Datos flexibles: cada generación puede combinar distinta llave, canal, transaction_purpose y channel_presentation, además de campos opcionales vía REST.
Programable por transacción: se genera de forma única por cada retiro, integrado con la infraestructura del operador de ATM.
Escalable y controlado: soporta alto volumen y permite controlar cada retiro en cualquier máquina del país, con trazabilidad por store_label y terminal_label.

Atención

La Plataforma de PaaS 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 Desarrollador garantizar que los impuestos, tarifas y recargos se calculen adecuadamente como parte de la contabilidad del proceso de venta.

Última actualización el