Cómo leer QR
Especificaciones para la lectura de QR
Las Entidades Participantes pueden habilitar la lectura de código QR a través de ACH En-Línea, por lo cual deberán implementar las siguientes especificaciones.
Dominio: https://bank.apihub.crt.achcolombia.com.co POST /ach/bk/v1/money-movement/instruments Campos de entrada para lectura de QR - Header
| Campo | Tipo | Validación | Descripción | Obligatoriedad |
|---|---|---|---|---|
| Authorization | String | Min 1 – Máx 64 | Bearer token OAuth2. | Sí |
| x-hash | String | Min 64 – Máx 64 | Cadena de comprobación de integridad de la trama exclusiva para endpoints de Transfers e Instruments. Serializar el objeto data y aplicar SHA256. | Sí |
| X-Client-Id | String | Min 1 – Máx 64 | Client Id del Participante | Sí |
| idempotencyKey | String | Min 1 – Máx 64 | Identificador UUID unico generado por la Entidad consumidora | Sí |
Campos de entrada servicio lectura QR - Body
| Campo | Tipo | Descripción | Formato | Obligatoriedad |
|---|---|---|---|---|
| meta | objeto | Objeto de metadatos | N/A | SI |
| requestId | uuid | Código generado por la entidad participante para identificar el paquete | a1b2c3d4-e5f6-7890-abcd-ef1234567890 | SI |
| timestamp | fecha | Fecha y hora de la solicitud de generación del código QR | 2025-12-23T18:16:35.099Z | SI |
| version | cadena | Versión del esquema, enviar el valor “1.0” | 1.0.0 | SI |
| data | objeto | Objeto de datos | N/A | SI |
| movementType | lista | Tipo de operación realizada | Valor fijo: QR-PARSER | SI |
| useCaseInformation | objeto | Objeto de caso de uso | N/A | SI |
| qrCode | cadena | Cadena de texto que contiene el código QR generado en formato EMVCO | Cadena TLV | SI |
Request lectura de QR
{
"meta": {
"requestId": "550e8400-e29b-41d4-a716-446655440000",
"version": "1.0.0",
"timestamp": "2026-04-17T10:00:00.000Z"
},
"data": {
"movementType": "QR-PARSER",
"useCaseInformation": {
"qrCode": "00020101021126470014CO.COM.ACH.LLA0325brebpruebas01@hotmail.com49250014CO.COM.ACH.RED0103ACH50290013..."
}
}
}
Campos de salida lectura de QR
| Campo | Tipo | Descripción | Formato |
|---|---|---|---|
| meta | objeto | Objeto de metadatos | N/A |
| requestId | uuid | Código generado por la entidad participante para identificar el paquete | a1b2c3d4-e5f6-7890-abcd-ef1234567890 |
| timestamp | fecha | Fecha y hora de la respuesta a la solicitud de generación del código QR | 2025-12-23T18:16:35.099Z |
| status | cadena | Estado de la respuesta. SUCCESS, FAILED | SUCCESS |
| statusCode | cadena | Código HTTP de la respuesta | 200 |
| statusDesc | cadena | Descripción del código HTTP | OK |
| data | objeto | Objeto de datos | N/A |
| movementType | lista | Tipo de operación a realizar | QR-PARSER |
| Tag number | objeto | Número del tag EMVCO | 26 |
| id | cadena | Número del tag EMVCO | 26 |
| name | cadena | Nombre del campo | Merchant Account Information |
| len | cadena | Tamaño del campo | 32 |
| data | objeto | Contenido del tag | - |
| SubTag Number | objeto | Número del subTag EMVCO | 26 |
| id | cadena | Número del subTag EMVCO | 01 |
| name | cadena | Nombre del campo | Global Unique Identifier |
| len | cadena | Tamaño del campo | 14 |
| data | cadena | Contenido del tag | CO.COM.ACH.LLA |
| rawdata | cadena | Fragmento del TLV para este TAG | CO.COM.ACH.LLA |
| rawdata | cadena | Fragmento del TLV para este TAG | 0014CO.COM.ACH.LLA02103152466845 |
| error | cadena | Objeto de error | N/A |
| code | cadena | Código de error generado (cero si no hay errores) | 1005 |
| message | cadena | Mensaje de error (vacío si no hay errores) | Fallas técnicas |
Response lectura 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": {
"movementType": "QRPARSER",
"26": {
"id": "26",
"name": "Merchant Account Information",
"len": 32,
"data": {
"00": {
"id": "00",
"name": "Global Unique Identifier",
"len": 14,
"data": "CO.COM.ACH.LLA",
"rawData": "CO.COM.ACH.LLA"
},
"02": {
"id": "02",
"name": "Celular",
"len": 10,
"data": "3152466845",
"rawData": "3152466845"
}
},
"rawData": "0014CO.COM.ACH.LLA02103152466845"
},
"49": {
"id": "49",
"name": "Merchant Account Information",
"len": 25,
"data": {
"00": {
"id": "00",
"name": "Global Unique Identifier",
"len": 14,
"data": "CO.COM.ACH.RED",
"rawData": "CO.COM.ACH.RED"
},
"01": {
"id": "01",
"name": "Merchant PAN",
"len": 3,
"data": "ACH",
"rawData": "ACH"
}
},
"rawData": "0014CO.COM.ACH.RED0103ACH"
},
"53": {
"id": "53",
"name": "Transaction Currency",
"len": 3,
"data": "170",
"rawData": "170"
},
"54": {
"id": "54",
"name": "Transaction Amount",
"len": 4,
"data": "8900",
"rawData": "8900"
},
"58": {
"id": "58",
"name": "Country Code",
"len": 2,
"data": "CO (Colombia)",
"rawData": "CO"
},
"59": {
"id": "59",
"name": "Merchant Name",
"len": 13,
"data": "Julián Suarez",
"rawData": "Julián Suarez"
},
"60": {
"id": "60",
"name": "Merchant City",
"len": 6,
"data": "Bogota",
"rawData": "Bogota"
},
"61": {
"id": "61",
"name": "Postal Code",
"len": 6,
"data": "114056",
"rawData": "114056"
},
"62": {
"id": "62",
"name": "Additional Data Field Template",
"len": 11,
"data": "07010080200",
"rawData": "07010080200"
},
"63": {
"id": "63",
"name": "CRC",
"len": 4,
"data": "2F1E",
"rawData": "2F1E"
},
"80": {
"id": "80",
"name": "Unreserved Templates",
"len": 27,
"data": {
"00": {
"id": "00",
"name": "Global Unique Identifier",
"len": 16,
"data": "CO.COM.ACH.CANAL",
"rawData": "CO.COM.ACH.CANAL"
},
"01": {
"id": "01",
"name": "Point of Service",
"len": 3,
"data": "POS",
"rawData": "POS"
}
},
"rawData": "0016CO.COM.ACH.CANAL0103POS"
},
"81": {
"id": "81",
"name": "Unreserved Templates",
"len": 25,
"data": {
"00": {
"id": "00",
"name": "Global Unique Identifier",
"len": 15,
"data": "CO.COM.ACH.CIVA",
"rawData": "CO.COM.ACH.CIVA"
},
"01": {
"id": "01",
"name": "IVA Code",
"len": 2,
"data": "03",
"rawData": "03"
}
},
"rawData": "0015CO.COM.ACH.CIVA010203"
},
"82": {
"id": "82",
"name": "Unreserved Templates",
"len": 23,
"data": {
"00": {
"id": "00",
"name": "Global Unique Identifier",
"len": 14,
"data": "CO.COM.ACH.IVA",
"rawData": "CO.COM.ACH.IVA"
},
"01": {
"id": "01",
"name": "IVA Code",
"len": 1,
"data": "0",
"rawData": "0"
}
},
"rawData": "0014CO.COM.ACH.IVA01010"
},
"83": {
"id": "83",
"name": "Unreserved Templates",
"len": 24,
"data": {
"00": {
"id": "00",
"name": "Global Unique Identifier",
"len": 15,
"data": "CO.COM.ACH.BASE",
"rawData": "CO.COM.ACH.BASE"
},
"01": {
"id": "01",
"name": "Base Code",
"len": 1,
"data": "0",
"rawData": "0"
}
},
"rawData": "0015CO.COM.ACH.BASE01010"
},
"84": {
"id": "84",
"name": "Unreserved Templates",
"len": 25,
"data": {
"00": {
"id": "00",
"name": "Global Unique Identifier",
"len": 15,
"data": "CO.COM.ACH.CINC",
"rawData": "CO.COM.ACH.CINC"
},
"01": {
"id": "01",
"name": "Code",
"len": 2,
"data": "03",
"rawData": "03"
}
},
"rawData": "0015CO.COM.ACH.CINC010203"
},
"85": {
"id": "85",
"name": "Unreserved Templates",
"len": 23,
"data": {
"00": {
"id": "00",
"name": "Global Unique Identifier",
"len": 14,
"data": "CO.COM.ACH.INC",
"rawData": "CO.COM.ACH.INC"
},
"01": {
"id": "01",
"name": "Code",
"len": 1,
"data": "0",
"rawData": "0"
}
},
"rawData": "0014CO.COM.ACH.INC01010"
},
"90": {
"id": "90",
"name": "Unreserved Templates",
"len": 43,
"data": {
"00": {
"id": "00",
"name": "Global Unique Identifier",
"len": 16,
"data": "CO.COM.ACH.TRXID",
"rawData": "CO.COM.ACH.TRXID"
},
"01": {
"id": "01",
"name": "Transaction ID",
"len": 19,
"data": "1962FB70176DC0B870F58",
"rawData": "1962FB70176DC0B870F58"
}
},
"rawData": "0016CO.COM.ACH.TRXID011962FB70176DC0B870F58"
},
"91": {
"id": "91",
"name": "Unreserved Templates",
"len": 86,
"data": {
"00": {
"id": "00",
"name": "Global Unique Identifier",
"len": 14,
"data": "CO.COM.ACH.SEC",
"rawData": "CO.COM.ACH.SEC"
},
"01": {
"id": "01",
"name": "Security Code",
"len": 64,
"data": "ac77cb8cc46f1e0aee1b8e3212bc9f27bcb8ec16aaf38d2ce42194a92bfc4d12",
"rawData": "ac77cb8cc46f1e0aee1b8e3212bc9f27bcb8ec16aaf38d2ce42194a92bfc4d12"
}
},
"rawData": "0014CO.COM.ACH.SEC0164ac77cb8cc46f1e0aee1b8e3212bc9f27bcb8ec16aaf38d2ce42194a92bfc4d12"
},
"00": {
"id": "00",
"name": "Payload Format Indicator",
"len": 2,
"data": "01",
"rawData": "01"
},
"01": {
"id": "01",
"name": "Point of Initiation Method",
"len": 2,
"data": "11",
"rawData": "11"
}
}
}
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 4
