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.
Dominio: https://bank.apihub.crt.achcolombia.com.co POST /ach/bk/v1/money-movement/instruments
Campos de entrada para generación - 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 generación QR - Body
| Campo | Tipo | Descripción | Formato | Obligatoriedad |
|---|---|---|---|---|
| meta | objeto | 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 | fecha | Fecha y hora de la solicitud de generación del código QR | 2025-12-23T18:16:35.099Z | Sí |
| version | cadena | Versión del esquema. Enviar siempre el valor “1.0.0” | 1.0.0 | Sí |
| data | objeto | Objeto de datos de la operación | N/A | Sí |
| movementType | lista | Tipo de operación. Valores válidos: QR-STATIC, QR-DYNAMIC, QR-PARSER | N/A | Sí |
| amountInformation | objeto | Objeto de monto | N/A | Sí |
| amount | decimal | Valor que tendrá el QR con dos decimales (Si el QR no tiene valor el campo no debe ser enviado) | 100.00 / 100.85 / 100.05 / 200.50 | Sí |
| currency | cadena | Código de moneda. Enviar siempre “COP” | COP | Sí |
| target | objeto | Objeto de destino | N/A | Sí |
| personType | lista | Tipo de persona destino. Valores válidos: NATURAL, LEGAL | NATURAL | Sí |
| merchantCode | cadena | Código del comercio destino. Para persona jurídica según estándar ISO 18245 | Min 1 - Máx 20 | COND Si PersonType es LEGAL y aliasType/aliasValue está vacío |
| fullName | cadena | Nombre completo del destino cuando es persona jurídica | Min 1 - Máx 160 | No |
| firstName | cadena | Primer nombre del destinatario | Min 1 - Máx 40 | COND Obligatorio cuando personType = NATURAL |
| secondName | cadena | Segundo nombre del destinatario | Min 1 - Máx 40 | COND Opcional cuando personType = NATURAL |
| firstLastName | cadena | Primer apellido del destinatario | Min 1 - Máx 40 | COND Obligatorio cuando personType = NATURAL |
| secondLastName | cadena | Segundo nombre del destinatario | Min 1 - Máx 40 | COND Opcional cuando personType = NATURAL |
| location | objeto | Objeto de ubicación | N/A | Sí |
| city | cadena | Código de ciudad asociada a la persona, comercio o negocio (Código Divipola - DANE) | Min 1 - Máx 20 | Sí |
| postalCode | cadena | Código postal de la persona, comercio o negocio | Min 1 - Máx 10 | Sí |
| alias | objeto | Objeto de llave destino | N/A | Sí |
| aliasType | lista | Tipo de llave del destino. Valores válidos: PHONE, ALPHANUM, EMAIL, NRIC, MERCHANTCODE | lista | COND. Obligatorio si no se envia el campo merchantCode y personType=LEGAL |
| aliasValue | cadena | Valor de la llave de identificación, según formato regulado Bre-b | Min 1 - Máx 92 | COND. Obligatorio si no se envia el campo merchantCode y personType=LEGAL |
| purposeInformation | objeto | Objeto de propósito de transacción | N/A | Sí |
| transactionPurpose | lista | Motivo de la transacción. Valores válidos: COMPRAS, ANULACIONES, TRANSFERENCIAS, RETIRO, RECAUDO, RECARGAS, DEPOSITO | Valor debe corresponder al de la lista | Sí |
| reference | cadena | Referencia del QR | Min 1-Max 25 | No |
| useCaseInformation | objeto | Objeto de caso de uso | N/A | Sí |
| qrType | lista | Tipo de QR. Valores válidos: STATIC, DYNAMIC | Min 1 - Máx 8 | Sí |
| categoryCode | cadena | 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 | cadena | Terminal asociada al comercio destino | Min 1 - Máx 25 | COND. Obligatorio si personType = LEGAL |
| vat | decimal | Valor del IVA con dos decimales | Min 1 - Máx 13 | Si |
| vatBase | decimal | Base del IVA con dos decimales | Min 1 - Máx 13 | Si |
| tax | decimal | Valor del impuesto INC con dos decimales | Min 1 - Máx 13 | Si |
| channel | lista | Canal de origen. Valores válidos: IM, POS, APP, ECOMM, MPOS, ATM, CB, OFC | Min 1 - Máx 30 | Sí |
| expirationTime | entero | Tiempo de expiración en segundos del QR Dinámico | Min 300 Max 5400 | COND. Obligatorio si el campo movementType= QR-DYNAMIC |
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": "550e8400-e29b-41d4-a716-446655440000",
"version": "1.0.0",
"timestamp": "2026-04-17T10:00:00.000Z"
},
"data": {
"movementType": "QR-STATIC",
"amountInformation": {
"currency": "COP"
},
"target": {
"personType": "NATURAL",
"firstName": "Juan",
"firstLastName": "Perez",
"location": {
"city": "11001",
"postalCode": "110111"
},
"alias": {
"aliasType": "PHONE",
"aliasValue": "3001234567"
}
},
"purposeInformation": {
"transactionPurpose": "COMPRAS"
},
"useCaseInformation": {
"qrType": "STATIC",
"categoryCode": "0000",
"vat": 285.25,
"vatBase": 1141.3,
"tax": 57.07
}
}
Request generación QR P2M
{
"meta": {
"requestId": "550e8400-e29b-41d4-a716-446655440000",
"version": "1.0.0",
"timestamp": "2026-04-17T10:00:00.000Z"
},
"data": {
"movementType": "QR-DYNAMIC",
"amountInformation": {
"amount": 1500.75,
"currency": "COP"
},
"target": {
"personType": "LEGAL",
"fullName": "COMERCIALIZADORA ACME SAS",
"merchantCode": "00123456",
"location": {
"city": "11001",
"postalCode": "110111"
}
},
"purposeInformation": {
"transactionPurpose": "COMPRAS",
"reference": "FAC-000123"
},
"useCaseInformation": {
"qrType": "DYNAMIC",
"categoryCode": "5411",
"terminal": "TERM01",
"channel": "POS",
"vat": 285.25,
"vatBase": 1141.3,
"tax": 57.07,
"expirationTime": 3600
}
}
}
Campos de salida generación de QR
| Campo | Tipo | Descripción | Formato |
|---|---|---|---|
| meta | objeto | 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 | 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. Valores: SUCCESS, FAILED | Corresponde a un valor válido |
| statusCode | cadena | Código HTTP de la respuesta | 200 |
| statusDesc | cadena | Descripción del código HTTP | OK |
| data | objeto | Objeto de datos de respuesta | N/A |
| id | cadena | Identificador único del QR en el sistema | a1b2c3d4-e5f6-7890-abcd-ef1234567890 |
| qrCode | cadena | Cadena de texto en formato EMVCo (TLV) que contiene el código QR generado | Cadena TLV |
| creationDateTime | fecha | Fecha y hora en la que se generó el QR | 2025-12-23T18:16:35.099Z |
| qrStatus | cadena | Estado actual del QR: ACTIVE, CANCELED, PAID, EXPIRED | Corresponde a un valor válido |
| movementType | lista | Tipo de operación. Valores: QR-STATIC, QR-DYNAMIC, QR-PARSER | Corresponde a un valor válido |
| duration | entero | Vigencia del QR. Indica el tiempo durante el cual el QR es válido | Expresado en segundos |
| expirationDateTime | fecha | Fecha y hora de expiración del QR | 2025-12-23T18:16:35.099Z |
| imageB64 | cadena | Imagen del QR en base 64 | Binario de la imagen |
| error | object | Objeto de error | N/A |
| code | integer | Código del error (no se envia 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": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": "2026-10-09T21:18:30.416Z",
"status": "SUCCESS",
"statusCode": "201",
"statusDesc": "QR generado correctamente"
},
"data": {
"id": "f8ce8c1e-c426-11f1-9956-0a8201b70000",
"qrCode": "00020101021126320014CO.COM.ACH.LLA...",
"creationDateTime": "2026-10-09T16:18:30.262Z",
"qrStatus": "ACTIVE",
"movementType": "QR-STATIC",
"duration": 3600,
"expirationDateTime": "2026-10-09T17:18:30.262Z",
"imageB64": "iVBORw0KGgoAAAANSUhEUgAAASwAAAEsCAYAAAB5fY51AAAAAklEQVR4AewaftIA..."
}
}
Response error 4XX
{
"meta": {
"requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"timestamp": "2026-04-17T10:30:00.000",
"status": "FAILED",
"statusCode": "400",
"statusDesc": "Bad Request"
},
"errors": [
{
"code": "1013",
"detail": "Datos obligatorios no encontrados."
}
]
}
Response error 5XX
{
"meta": {
"requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"timestamp": "2026-04-17T10:30:00.000",
"status": "FAILED",
"statusCode": "500",
"statusDesc": "Internal Server Error"
},
"errors": [
{
"code": "1005",
"detail": "Fallas técnicas."
}
]
}
Orderarticle 3
