Cómo actualizar estado QR

Especificaciones para actualizar QR

Las Entidades Participantes pueden actualizar el estado del QR Estático una vez haya sido usado y se requiera dar de baja o en caso de que se requiera cancelar.


Dominio: https://bank.apihub.crt.achcolombia.com.co


POST v1/money-movements/instruments/{id}/status

El ID a actualizar en el path corresponde al entregado en la generación del QR.

Estados soportados

Estado Descripción Actualizado por
ACTIVE Todo QR inicia en este estado. Indica que está disponible para pago. ACH En-línea
CANCELLED Estado final. El comercio lo canceló antes de cualquier transacción. Entidad Participante
PAID Estado final. Se recibió la notificación de pago exitosa. El QR no puede volverse a usar. ACH En-línea
EXPIRED Estado final. Se superó el tiempo de vigencia del QR. No puede utilizarse. ACH En-línea

Máquina de estados - QR Estático

ESTADO ACTUAL ACTIVE CANCELLED PAID EXPIRED
ACTIVE   OK ERROR ERROR
CANCELLED ERROR ERROR ERROR ERROR
PAID ERROR ERROR ERROR ERROR
EXPIRED ERROR ERROR ERROR ERROR

Máquina de estados - QR Dinámico

ESTADO ACTUAL ACTIVE CANCELLED PAID EXPIRED
ACTIVE ERROR OK OK OK
CANCELLED ERROR ERROR ERROR ERROR
PAID ERROR ERROR ERROR ERROR
EXPIRED ERROR ERROR ERROR ERROR

Campos de entrada para actualización 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 actualización QR

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 actualización del código QR 2025-12-23T18:16:35.099Z SI
version cadena Versión del esquema, enviar el valor “1.0.0” 1.0.0 SI
data objeto Objeto de datos N/A SI
movementType lista Tipo de operación a realizar. [QR-STATIC, QR-DYNAMIC] lista SI
status lista Estado de código QR. [CANCELLED, PAID] lista SI

Request actualización QR

{
  "meta": {
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "version": "1.0.0",
    "timestamp": "2026-04-17T10:00:00.000"
  },
  "data": {
    "movementType": "QR-STATIC",
    "status": "CANCELLED"
  }
}

Campos de salida actualización 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 datetime Fecha y hora de la respuesta a la solicitud de actualización del código QR 2025-12-23T18:16:35.099Z
status cadena Estado de la respuesta. SUCCESS, DAIED cadena
statusCode cadena Código HTTP de la respuesta cadena
statusDesc cadena Descripción del código HTTP cadena
data objeto Objeto de datos N/A
id cadena Identificador único del QR en el sistema cadena
qrStatus cadena Estado actual del QR cadena
lastModifiedDateTime fecha Fecha y hora en la que se modifico el estado del QR 2026-01-16T01:51:46.706Z
error objeto Objeto de error N/A
code cadena Código de error generado (vacío si no hay errores) cadena
message cadena Mensaje de error (vacío si no hay errores) cadena

Response actualización QR

Response exitoso

{
  "meta": {
    "requestId": "b5d7e210-a1c3-4f9e-8a2b-0987654321fe",
    "timestamp": "2026-10-13T13:49:57.619Z",
    "status": "SUCCESS",
    "statusCode": "200",
    "statusDesc": "Actualizacion de estado procesada correctamente"
  },
  "data": {
    "id": "8f2a4b10-cd56-11f1-90ab-0a8201b70000",
    "qrStatus": "CANCELLED",
    "lastModifiedDateTime": "2026-09-29T00:10:50.236Z"
  }
}

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 5
Cómo leer QR Anterior