Cómo actualizar 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
PATCH /ach/bk/v1/money-movement/qr/{idQR}

El ID a actualizar en el path corresponde al tag 90 (Id QR).

Estados soportados

Estado	Tipo de QR	Descripción
ACTIVE	Estático / Dinámico	Todo QR inicia en este estado. Indica que está disponible para pago.
INACTIVE	Solo Estático	Estado final. El QR ya no está disponible para recibir pagos.
CANCELED	Solo Dinámico	Estado final. El comercio lo canceló antes de cualquier transacción.
PAID	Solo Dinámico	Estado final. Se recibió la notificación de pago exitosa. El QR no puede volverse a usar.
EXPIRED	Solo Dinámico	Estado final. Se superó el tiempo de vigencia del QR. No puede utilizarse.

Transacciones permitidas - QR Estático

Estado Actual	Evento / Causa	Estado siguiente
ACTIVO	Solicitud de inhabilitación	CANCELADO
ACTIVO	Notificación exitosa de pago	PAGADO

Transacciones permitidas - QR Dinámico

Estado Actual	Evento / Causa	Estado siguiente
ACTIVO	Comercio cancela	CANCELADO
ACTIVO	Notificación exitosa de pago	PAGADO
ACTIVO	Expira vigencia	EXPIRADO

Campos de entrada servicio actualización QR

Campo	Tipo	Descripción	Formato	Obligatoriedad
meta	object	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	datetime	Fecha y hora de la solicitud de generación del código QR	2025-12-23T18:16:35.099Z	SI
version	string	Versión del esquema, enviar el valor “1.0”	1.0	SI
data	object	Objeto de datos	N/A	SI
movementType	enum	Tipo de operación a realizar. [QR, QRVALIDATE, QRPARSER]	QR	SI
status	enum	Estado de código QR. [INACTIVE, CANCELED, PAID]	PAID	SI
requestor	lista	Para movementType QR este dato es opcional	lista	NO
creationDateTime	fecha	Para movementType QR este dato es opcional	Ver Tabla	NO
custom	object	Objeto de personalización	N/A	NO
error	object	Objeto de error	N/A	NO
code	string	Código del error presentado por la entidad (0 si no hay error)	Min 1 Max 255	SI
description	string	Texto descriptivo del error (Success si no hay error)	Min 1 Max 255	SI

Request actualización QR

{
  "meta": {
    "requestId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "timestamp": "2026-01-16T01:48:22.252Z",
    "version": "1.0"
  },
  "data": {
    "movementType": "QR",
    "status": "INACTIVO"
  }
}

Campos de salida actualización QR

Campo	Tipo	Descripción	Formato
meta	object	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 generación del código QR	2025-12-23T18:16:35.099Z
status	enum	Estado de la respuesta. SUCCESS, ERROR	SUCCESS
statusCode	string	Código HTTP de la respuesta	200
statusDesc	string	Descripción del código HTTP	OK
data	object	Objeto de datos	N/A
id	string	Identificador único del QR en el sistema	123e4567-e89b-12d3-a456-426614174000
qrStatus	string	Estado actual del QR	ACTIVO
lastModifiedDateTime	datetime	Fecha y hora en la que se modificación el estado del QR	2026-01-16T01:51:46.706Z
error	object	Objeto de error	N/A
code	integer	Código de error generado (cero si no hay errores)	1005
message	string	Mensaje de error (vacío si no hay errores)	Fallas técnicas

Response actualización QR

Response exitoso

{
  "meta": {
    "requestId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "timestamp": "2026-01-16T01:51:46.706Z",
    "status": "SUCCESS",
    "statusCode": "200",
    "statusDesc": "string"
  },
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "qrStatus": "INACTIVO",
    "lastModifiedDateTime": "2026-01-16T01:51:46.706Z"
  }
}

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 Cómo consultar QR Siguiente