Cómo generar un QR

Especificaciones para generar QR

Las Entidades Participantes pueden habilitar la generación de códigos QR a través de ACH En-Línea. Para su implementación, deberán tener en cuenta los siguientes campos, cumpliendo con el estándar EMVCo y los lineamientos del Banco de la República.

Es posible generar códigos QR estáticos o dinámicos, tanto para personas naturales como para empresas, utilizando los siguientes campos de entrada.

Campos de entrada generación QR

Campo	Tipo	Descripción	Formato	Obligatoriedad
meta	object	Objeto de metadatos	N/A	Sí
requestId	uuid	Código generado por la entidad participante para identificar la solicitud	a1b2c3d4-e5f6-7890-abcd-ef1234567890	Sí
timestamp	time	Fecha y hora de la solicitud de generación del código QR	2025-12-23T18:16:35.099Z	Sí
version	string	Versión del esquema. Enviar siempre el valor “1.0”	1.0	Sí
data	object	Objeto de datos de la operación	N/A	Sí
movementType	enum	Tipo de operación. Valores válidos: QR, QRVALIDATE, QRPARSER	QR	Sí
amountInformation	object	Objeto de monto	N/A	Sí
amount	decimal	Valor de la transacción con dos decimales	100.00 / 100.85 / 100.05 / 200.50	Sí
currency	string	Código de moneda. Enviar siempre “COP”	COP	Sí
target	object	Objeto de destino	N/A	Sí
personType	enum	Tipo de persona destino. Valores válidos: NATURAL, LEGAL	NATURAL	Sí
merchantCode	string	Código del comercio destino. Para persona jurídica según estándar ISO 18245	Min 1 - Máx 20	No
fullName	string	Nombre completo del destino cuando es persona natural	Min 1 - Máx 25	No
businnesName	string	Nombre del comercio o razón social cuando personType = LEGAL	Min 1 - Máx 25	No
firstName	string	Primer nombre	Min 1 - Max 40	No
secondName	string	Segundo nombre	Min 1 - Max 40	No
firstLastName	string	Primer apellido	Min 1 - Max 40	No
secondLastName	string	Segundo apellido	Min 1 - Max 40	No
location	object	Objeto de ubicación	N/A	Sí
city	string	Código de ciudad asociada a la persona, comercio o negocio (Código Divipola - DANE)	Min 1 - Máx 20	Sí
postalCode	string	Código postal de la persona, comercio o negocio	Min 1 - Máx 10	Sí
alias	object	Objeto de llave destino	N/A	Sí
aliasType	enum	Tipo de llave del destino. Valores válidos: PHONE, ALPHANUM, EMAIL, NRIC, MERCHANTCODE	PHONE	No
aliasValue	string	Valor de la llave de identificación, según formato regulado Bre-b	Min 1 - Máx 92	No
purposeInformation	object	Objeto de propósito de transacción	N/A	Sí
transactionPurpose	enum	Motivo de la transacción. Valores válidos: COMPRAS, ANULACIONES, TRANSFERENCIAS, RETIRO, RECAUDO, RECARGAS, DEPOSITO	TRANSFERENCIAS	Sí
reference	string	Documento relacionado del pago	Min 1 - Max 25	No
useCaseInformation	object	Objeto de caso de uso	N/A	Sí
qrType	enum	Tipo de QR. Valores válidos: STATIC, DYNAMIC	DYNAMIC	Sí
categoryCode	string	Categoría del comercio destino. Si personType = LEGAL, debe ser diferente de 0000 y acorde con ISO 18245.	Min 1 - Máx 4	Sí
terminal	string	Terminal asociada al comercio destino	Min 1 - Máx 25	Sí
vat	decimal	Valor del IVA con dos decimales (obligatorio si personType = LEGAL)	Min 1 - Máx 13	COND
vatBase	decimal	Base del IVA con dos decimales (obligatorio si personType = LEGAL)	Min 1 - Máx 13	COND
tax	decimal	Valor del impuesto INC con dos decimales (obligatorio si personType = LEGAL)	Min 1 - Máx 13	COND
channel	enum	Canal de origen. Valores válidos: IM, POS, APP, ECOMM, MPOS, ATM, CB, OFC	POS	Sí

Tabla de canales

Código	Descripción
IM	POS Manual
POS	POS / PINPAD
APP	Banca Móvil
ECOMM	Internet
MPOS	POS / PINPAD
ATM	Cajero Automático
CB	Corresponsal Bancario
OFC	Oficina

Reglas para valores decimales

Valor con dos (2) cifras decimales únicamente.
Separador decimal con carácter punto (.).
Valores mayores o igual a cero.
No puede ser NULL.

Request generación de QR

Request generación QR P2P

{
  "meta": {
    "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "timestamp": "2025-12-23T18:16:35.099Z",
    "version": "1.0"
  },
  "data": {
    "movementType": "QR",
    "amountInformation": {
      "amount": "0.00",
      "currency": "COP"
    },
    "target": {
      "personType": "NATURAL",
      "alias": {
        "aliasType": "PHONE",
        "aliasValue": "3002627700"
      }
    },
    "useCaseInformation": {
      "qrType": "STATIC",
      "categoryCode": "0000",
      "channel": "POS"
    }
  }
}

Request generación QR P2M

{
  "meta": {
    "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "timestamp": "2025-12-23T18:16:35.099Z",
    "version": "1.0"
  },
  "data": {
    "movementType": "QR",
    "amountInformation": {
      "amount": "0.00",
      "currency": "COP"
    },
    "target": {
      "personType": "LEGAL",
      "fullName": "Papelería Mis Papeles",
      "firstName": "",
      "secondName": "",
      "firstLastName": "",
      "secondLastName": "",
      "location": {
        "city": "11001",
        "postalCode": "110221"
      },
      "alias": {
        "aliasType": "MERCHANTCODE",
        "aliasValue": "0022445577"
      }
    },
    "purposeInformation": {
      "transactionPurpose": "TRANSFERENCIAS",
      "reference": ""
    },
    "useCaseInformation": {
      "qrType": "STATIC",
      "categoryCode": "4567",
      "terminal": "TERM-001",
      "vat": "0.00",
      "vatBase": "0.00",
      "tax": "0.00",
      "channel": "POS"
    }
  }
}

Campos de salida generación de QR

Campo	Tipo	Descripción	Formato
meta	object	Objeto de metadatos de respuesta	N/A
requestId	uuid	Código generado por la entidad participante para identificar el paquete	a1b2c3d4-e5f6-7890-abcd-ef1234567890
timestamp	datetime	Fecha y hora de la respuesta a la solicitud de generación del código QR	2025-12-23T18:16:35.099Z
status	enum	Estado de la respuesta. Valores: SUCCESS, ERROR	SUCCESS
statusCode	string	Código HTTP de la respuesta	200
statusDesc	string	Descripción del código HTTP	OK
data	object	Objeto de datos de respuesta	N/A
id	uuid	Identificador único del QR en el sistema	a1b2c3d4-e5f6-7890-abcd-ef1234567890
qrCode	string	Cadena de texto en formato EMVCo (TLV) que contiene el código QR generado	Cadena TLV
creationDateTime	datetime	Fecha y hora en la que se generó el QR	2025-12-23T18:16:35.099Z
qrStatus	enum	Estado actual del QR: HABILITADO, INHABILITADO, CANCELADO, PAGADO, EXPIRADO	HABILITADO
movementType	enum	Tipo de operación. Valores: QR, QRVALIDATE, QRPARSER	QR
duration	integer	Vigencia del QR. Indica el tiempo durante el cual el QR es válido	5
expirationDateTime	datetime	Fecha y hora de expiración del QR (ISO 8601, UTC-0 con “Z”)	2025-12-23T18:16:35.099Z
imageB64	string	Imagen del QR en base 64	Binario de la imagen
error	object	Objeto de error	N/A
code	integer	Código del error (cero si no hay errores)	1005
message	string	Mensaje de error (vacío si no hay errores)	Fallas técnicas

Response generación de QR

Response exitoso

{
  "meta": {
    "requestId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "timestamp": "2026-01-15T00:03:39.558Z",
    "status": "SUCCESS",
    "statusCode": "200",
    "statusDesc": "OK"
  },
  "data": {
    "id": "fcc765f9-8e2b-4251-86e0-5fead7f3f0fe",
    "qrCode": "00020101021126320014CO.COM.ACH.LLA0510000169664749250014CO.COM.ACH.RED0103ACH5303170540410005802CO5913Julian Suarez6006Bogota610611405662110701008020080270016CO.COM.ACH.CANAL0103POS81250015CO.COM.ACH.CIVA01020382230014CO.COM.ACH.IVA0101083240015CO.COM.ACH.BASE0101084250015CO.COM.ACH.CINC01020385230014CO.COM.ACH.INC0101090590016CO.COM.ACH.TRXID0135CO.COM.ACH.RED34E81961EB12640F5B2D191860014CO.COM.ACH.SEC01648f66c1e3a2e6b0ee5358cd566f935eec8d30efb218f33aa17b316542fe2ab1b06304ACEA",
    "creationDate": "2026-01-16T20:05:18.494Z",
    "qrStatus": "ACTIVE",
    "movementType": "QR",
    "duration": "0",
    "expirationDate": "2026-01-16T20:05:18.494Z",
    "imageB64": "iVBORw0KGgoAAAANSUhEUgAAAUQAAAFECAYAAABf6kfGAAAAAklEQVR4AewaftIAABl5SURBVO3BQW7A1pLAQFLwaMCbTq1QMEyU7oKvs"
  }
}

Response error 4XX

{
  "meta": {
    "requestId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "timestamp": "2026-01-15T00:03:39.558Z",
    "status": "ERROR",
    "statusCode": "400",
    "statusDesc": "Bad Request"
  },
  "error": {
    "code": "1013",
    "message": "El contenido enviado no es válido o está mal cifrado"
  }
}

Response error 5XX

{
  "meta": {
    "requestId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "timestamp": "2026-01-15T00:03:39.558Z",
    "status": "ERROR",
    "statusCode": "500",
    "statusDesc": "Internal Server Error"
  },
  "error": {
    "code": "1005",
    "message": "Fallas Técnicas"
  }
}

Orderarticle 3

Token de Autenticación Anterior Cómo leer QR Siguiente