Skip to main content

​
Definición de producto

El código QR (Quick Response) es una herramienta visual bidimensional con estructura cuadrada, diseñada para almacenar información codificada de forma eficiente. Su lectura es rápida y su capacidad supera la de los códigos de barras tradicionales. Puede ser estático, con contenido fijo, o dinámico, adaptándose a cada transacción mediante generación en tiempo real. En Colombia, esta tecnología se habilita como parte del sistema Bre-B de pagos inmediatos, en cumplimiento del artículo 104 de la Ley 2294 de 2023 y bajo la regulación del Banco de la República para transfrencias y/o pagos inmediatos a personas y comercios. El objetivo es facilitar pagos digitales mediante billeteras electrónicas y acceso móvil, utilizando el estándar internacional EMVCo. Esto permite que los usuarios realicen pagos sin contacto físico con la tarjeta, mejorando la seguridad y ampliando los puntos de aceptación en todo el país.

​
Tipos de QR:

Estático Es un código de respuesta rápida que contiene información fija, como los datos del comercio o una llave destino (comercio o persona). Se genera una sola vez y no se actualiza con cada transacción. Por lo general, se imprime o se exhibe en un lugar visible (como una vitrina o factura), y el usuario debe ingresar manualmente el monto a pagar.
Para las Entidades Participantes, este tipo de QR representa una solución sencilla y de bajo costo para habilitar pagos, aunque con menor automatización y control sobre la transacción. Dinámico Este código se genera en tiempo real y contiene información específica de cada transacción, como el valor exacto, la llave destino (comercio o persona), la referencia de pago, entre otros. Al escanearlo, el usuario no necesita digitar ningún dato adicional: el pago se procesa automáticamente.
Desde el punto de vista de las Entidades Participantes, el QR dinámico permite una experiencia de pago más segura, rápida y trazable, ideal para integraciones con sistemas de facturación, puntos de venta y billeteras digitales.

​
Flujo para la generación y lectura con código QR:

A continuación se relaciona el flujo para generación y lectura con código QR Flujo QR PN

​
Capacidades a ofrecer

  • Exposición de API: Transfiya ofrecerá una API para facilitar la integración de generación y lectura de QR.
  • Disponer canal para garantizar una comunicación segura y eficiente.
  • Transfiya entrega la cadena de datos para la generación de QR conforme al estándar EMVco.
  • Dentro del proceso de lectura, se ofrecerá la decodificación de imagen para interpretar el contenido del QR, obteniendo entre otros la llave, el ID de QR, tipo de QR y el hash de seguridad. El cual será entregado por Transfiya en formato JSON. para que la Entidad Participante origen orqueste el flujo transaccional.

​
Especificaciones para generación de QR

Las Entidades Participantes pueden habilitar la generacion de código QR a través de Transfiya, para esto deberán tener en cuenta para la implementación, los siguientes campos cumplliendo el estándar EMVco y los lineamientos de Banco de la República : 
POST /ach/eeff/v1/money-movements

​
Entrada:

CampoTipoDescripciónLongitudObligatorio
pointOfInitiationMethodListaCampo de tipo de QR - Valores válidos (ESTATICO y DINAMICO) - SIN tildes, sin importar mayusculas y minusculasMin 1 - Máx 8SI
merchantAccountInformationObjeto--SI
aliasTypeListaTipo de llave - Valores válidos (IDENTIFICACION, CELULAR, EMAIL, TEXT, MERCHANTID)Min 1 - Máx 20NO
aliasValueTextoValor de llaveMin 1 - Máx 92NO
merchantCodeTextoCódigo de comercioMin 1 - Máx 20NO
merchantNameTextoNombre del comercioMin 1 - Máx 20SI
merchantCityTextoCiudad del comercioMin 1 - Máx 20SI
postalCodeTextoCódigo postal adquirenteMin 1 - Máx 6SI
merchantCategoryCodeTextoMCC - (para PN: 0000 y para PJ: Valores del estándar ISO 18245) - No se validara la existencia del dato ISOMin 1 - Máx 4SI
additionalMerchantInformationObjeto--SI
terminalTextoTerminal alfanumérica asociada al comercio Ej: 12345Min 1 - Máx 20SI
transactionPorposeListaValores válidos - (COMPRAS, ANULACIONES, TRANSFERENCIAS, RETIRO, RECAUDO, RECARGAS, DEPOSITO) - SIN tildes, sin importar mayusculas y minusculasMin 1 - Máx 25SI
transactionObjeto--SI
amountDecimalValor de la transacción, aplican las reglas para los valores de tipo decimalMin 1 - Máx 13SI
customDataObjeto--SI
valorIvaDecimalValor del impuesto Iva, aplican las reglas para los valores de tipo decimalMin 1 - Máx 13NO
baseIvaDecimalValor base IVA, aplican las reglas para los valores de tipo decimalMin 1 - Máx 13NO
valorIncDecimalValor del impuesto del INC (Impuessto Nacional al Consumo), aplican las reglas para los valores de tipo decimalMin 1 - Máx 13NO
idQrTextoIdentificador único de QR - Debe ser un UUID de máximo 18 caracteresMin 1 - Máx 18SI
channelListaCanal origen. Valore válidos (IM, POS, APP, ECOMM, MPOS, ATM, CB, OFC) - SIN tildes, sin importar mayusculas y minusculasMin 1 - Máx 30SI

​
Reglas para los valores de tipo decimal

Ejemplos de valores permitidos:
A: 1000
B: 1000.85
C: 1000.05
D: 1000.5

Reglas para el dato:\
  • Valor con dos (2) cifras decimales máximo\
  • Puede no tener cifras decimales\
  • Separador decimal el carácter punto (.) cuando aplique\
  • Valores mayores o igual a cero\
  • No puede ser NULL
{
  "meta": {
    "requestId": "e7b9c1d0-f8a1-4b2c-9d0e-5a6b7c8d9e0f",
    "version": "1.0.0",
    "timestamp": "2025-11-12T21:09:00Z"
  },
  "data": {
    "movementType": "QR",
    "amount": 1000.85,
    "currency": "COP",
    "pointOfInitiationMethod": "ESTATICO",
    "merchantAccountInformation": {
      "aliasType": "CELULAR",
      "aliasValue": "3101234567",
      "merchantCode": "",
      "merchantName": "Librería Central",
      "merchantCity": "BOGOTA",
      "postalCode": "110111",
      "merchantCategoryCode": "5192"
    },
    "additionalMerchantInformation": {
      "terminal": "POS001",
      "transactionPorpose": "COMPRAS"
    },
    "customData": {
      "ivaValue": 1000,
      "ivaBase": 1000.05,
      "incValue": 1000.5,
      "qrId": "b7f9a3c4-2e10-47",
      "channel": "POS"
    }
  }
}

​
Salida:

CampoTipoDescripciónLongitudObligatoriedad
idTextoIdentificador del QR en el sistemaMin 1 - Máx 36SI
qrCodeTextoCadena de texto con el codigo generado en formato TLVMin 30 - Máx 450SI
fechaGeneracionTextoFecha en la que se genero en QRN/ASI
StatusTextoEstado del QRMin 1 – Max 30SI
{
  "meta": {
    "requestId": "e7b9c1d0-f8a1-4b2c-9d0e-5a6b7c8d9e0f",
    "timestamp": "2025-11-12T21:10:45Z",
    "status": "SUCCESS",
    "statusCode": "200",
    "statusDesc": "QR generado exitosamente"
  },
  "data": {
    "movementType": "QR",
    "id": "6e2c8b72-9a45-4db3-bf34-3f1e78cb4a3a",
    "qrCode": "00020101021226600014COLOMBIA12345678900210LIBRERIACENTRAL5204000053031705405500005802CO5910BOGOTA6009COLOMBIA6304ABCD",
    "fechaGeneracion": "2025-11-12T21:10:00Z",
    "status": "PENDING"
  }
}

​
Archivo descargable (.yaml): \


Especificaciones para lectura de QR Las Entidades Participantes pueden habilitar la lectura de código QR a través de Transfiya, por lo cual deberán implementar las siguientes especificaciones:

​
Entrada:

CampoTipoDescripciónLongitudObligatorio
qrCodeTextoCadena de texto con el codigo a consultar, en formato EMVCOMin 30 - Máx 450SI

​
Salida:

El sistema Transfiya retornará un JSON con los campos contenidos en la cadena TLV. Esta información es necesaria para que la Entidad Participante Origen ejecute el proceso de resolución de llave y la creación de la transacción.
CampoTipoDescripcionEjemplo
Tag numberobjetoNumero del tag EMVCO26
IdNumberNumero del tag EMVCO26
nameCadenaNombre del campoMerchant Account Information
lenNumberTamaño del campo32
dataobjetoContenido del tag
SubTag NumberObjetoNumero del subTag EMVCO0
IdNumberNumero del subTag EMVCO0
nameNumberNombre del campoGlobal Unique Identifier
lenCadenaTamaño del campo14
dataNumberContenido del tagCO.COM.ACH.LLA
rawdataCadenaFragmento del TLV para este TAGCO.COM.ACH.LLA
rawdataCadenaFragmento del TLV para este TAG0014CO.COM.ACH.LLA02103152466845