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
Token de Autenticación Anterior