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
