Cómo validar un QR - Transfiya Guide

Especificaciones para validación de QR

ACH cuenta con la capacidad de validar la veracidad del código QR antes de realizar la acreditación del dinero en la entidad participante destino. Sin embargo, las entidades que lo requieran podrán implementar el método de validación según lo establecido en esta documentación.

El servicio de validación aplica unicamente para los códigos QR generados por Transfiya.

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

POST /ach/bk/v1/money-movement/qr

Campos de Entrada

Campo	Tipo	Descripción	Formato	Obligatorio
meta	object			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			SI
movementType	enum	Tipo de operación a realizar. [QR, QRVALIDATE, QRPARSER]	QRVALIDATE	SI
useCaseInformation	object			SI
idQr	string	Campo para la identificación de la transacción. (Tag 90)	CO.COM.ACH.RED3748349738748374	SI
crc	string	Código de redundancia cíclica del QR (Tag 63)	3A5F	NO
hash	string	Cadena de caracteres de seguridad del QR (Tag 91)	7f9c2ba4e88f827d616045507605853ed73b4761f1d1f6c5e9f7f0f4b7a4f1f0	NO

{
  "meta": {
    "requestId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "timestamp": "2026-01-15T17:18:15.761Z",
    "version": "1.0"
  },
  "data": {
    "movementType": "QRVALIDATE",
    "useCaseInformation": {
      "idQr": "CO.COM.ACH.RED3748349738748374",
      "crc": "3A5F",
      "hash": "7f9c2ba4e88f827d616045507605853ed73b4761f1d1f6c5e9f7f0f4b7a4f1f0"
    }
  }
}

Campos de Salida:

Campo	Tipo	Descripción	Formato
meta	object	-	-
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
movementType	enum	Tipo de operación a realizar. [QR, QRVALIDATE, QRPARSER]	QRVALIDATE
qr	object	-	-
Tag number	object	Número del tag EMVCO	26
id	string	Número del tag EMVCO	26
name	string	Nombre del campo	Merchant Account Information
len	string	Tamaño del campo	32
data	object	Contenido del tag	-
SubTag Number	object	Número del subTag EMVCO	26
id	string	Número del subTag EMVCO	01
name	string	Nombre del campo	Global Unique Identifier
len	string	Tamaño del campo	14
data	string	Contenido del tag	CO.COM.ACH.LLA
rawdata	string	Fragmento del TLV para este TAG	CO.COM.ACH.LLA
rawdata	string	Fragmento del TLV para este TAG	0014CO.COM.ACH.LLA02103152466845
error	object
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

Campos de Respuesta

{
  "meta": {
    "requestId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "timestamp": "2026-01-15T00:03:39.558Z",
    "status": "SUCCESS",
    "statusCode": "200",
    "statusDesc": "OK"
  },
  "data": {
    "movementType": "QRPARSER",
    "26": {
      "id": "26",
      "name": "Merchant Account Information",
      "len": 32,
      "data": {
        "00": {
          "id": "00",
          "name": "Global Unique Identifier",
          "len": 14,
          "data": "CO.COM.ACH.LLA",
          "rawData": "CO.COM.ACH.LLA"
        },
        "02": {
          "id": "02",
          "name": "Merchant ID",
          "len": 10,
          "data": "3152466845",
          "rawData": "3152466845"
        }
      },
      "rawData": "0014CO.COM.ACH.LLA02103152466845"
    },
    "49": {
      "id": "49",
      "name": "Merchant Account Information",
      "len": 25,
      "data": {
        "00": {
          "id": "00",
          "name": "Global Unique Identifier",
          "len": 14,
          "data": "CO.COM.ACH.RED",
          "rawData": "CO.COM.ACH.RED"
        },
        "01": {
          "id": "01",
          "name": "Merchat PAN",
          "len": 3,
          "data": "ACH",
          "rawData": "ACH"
        }
      },
      "rawData": "0014CO.COM.ACH.RED0103ACH"
    },
    "53": {
      "id": "53",
      "name": "Transaction Currency",
      "len": 3,
      "data": "170",
      "rawData": "170"
    },
    "54": {
      "id": "54",
      "name": "Transaction Amount",
      "len": 4,
      "data": "8900",
      "rawData": "8900"
    },
    "58": {
      "id": "58",
      "name": "Country Code",
      "len": 2,
      "data": "CO (Colombia)",
      "rawData": "CO"
    },
    "59": {
      "id": "59",
      "name": "Merchant Name",
      "len": 13,
      "data": "Julián Suarez",
      "rawData": "Julián Suarez"
    },
    "60": {
      "id": "60",
      "name": "Merchant City",
      "len": 6,
      "data": "Bogota",
      "rawData": "Bogota"
    },
    "61": {
      "id": "61",
      "name": "Postal Code",
      "len": 6,
      "data": "114056",
      "rawData": "114056"
    },
    "62": {
      "id": "62",
      "name": "Additional Data Field Template",
      "len": 11,
      "data": "07010080200",
      "rawData": "07010080200"
    },
    "63": {
      "id": "63",
      "name": "CRC",
      "len": 4,
      "data": "2F1E",
      "rawData": "2F1E"
    },
    "80": {
      "id": "80",
      "name": "Unreserved Templates",
      "len": 27,
      "data": {
        "00": {
          "id": "00",
          "name": "Global Unique Identifier",
          "len": 16,
          "data": "CO.COM.ACH.CANAL",
          "rawData": "CO.COM.ACH.CANAL"
        },
        "01": {
          "id": "01",
          "len": 3,
          "data": "POS",
          "rawData": "POS"
        }
      },
      "rawData": "0016CO.COM.ACH.CANAL0103POS"
    },
    "81": {
      "id": "81",
      "name": "Unreserved Templates",
      "len": 25,
      "data": {
        "00": {
          "id": "00",
          "name": "Global Unique Identifier",
          "len": 15,
          "data": "CO.COM.ACH.CIVA",
          "rawData": "CO.COM.ACH.CIVA"
        },
        "01": {
          "id": "01",
          "len": 2,
          "data": "03",
          "rawData": "03"
        }
      },
      "rawData": "0015CO.COM.ACH.CIVA010203"
    },
    "82": {
      "id": "82",
      "name": "Unreserved Templates",
      "len": 23,
      "data": {
        "00": {
          "id": "00",
          "name": "Global Unique Identifier",
          "len": 14,
          "data": "CO.COM.ACH.IVA",
          "rawData": "CO.COM.ACH.IVA"
        },
        "01": {
          "id": "01",
          "len": 1,
          "data": "0",
          "rawData": "0"
        }
      },
      "rawData": "0014CO.COM.ACH.IVA01010"
    },
    "83": {
      "id": "83",
      "name": "Unreserved Templates",
      "len": 24,
      "data": {
        "00": {
          "id": "00",
          "name": "Global Unique Identifier",
          "len": 15,
          "data": "CO.COM.ACH.BASE",
          "rawData": "CO.COM.ACH.BASE"
        },
        "01": {
          "id": "01",
          "len": 1,
          "data": "0",
          "rawData": "0"
        }
      },
      "rawData": "0015CO.COM.ACH.BASE01010"
    },
    "84": {
      "id": "84",
      "name": "Unreserved Templates",
      "len": 25,
      "data": {
        "00": {
          "id": "00",
          "name": "Global Unique Identifier",
          "len": 15,
          "data": "CO.COM.ACH.CINC",
          "rawData": "CO.COM.ACH.CINC"
        },
        "01": {
          "id": "01",
          "len": 2,
          "data": "03",
          "rawData": "03"
        }
      },
      "rawData": "0015CO.COM.ACH.CINC010203"
    },
    "85": {
      "id": "85",
      "name": "Unreserved Templates",
      "len": 23,
      "data": {
        "00": {
          "id": "00",
          "name": "Global Unique Identifier",
          "len": 14,
          "data": "CO.COM.ACH.INC",
          "rawData": "CO.COM.ACH.INC"
        },
        "01": {
          "id": "01",
          "len": 1,
          "data": "0",
          "rawData": "0"
        }
      },
      "rawData": "0014CO.COM.ACH.INC01010"
    },
    "90": {
      "id": "90",
      "name": "Unreserved Templates",
      "len": 43,
      "data": {
        "00": {
          "id": "00",
          "name": "Global Unique Identifier",
          "len": 16,
          "data": "CO.COM.ACH.TRXID",
          "rawData": "CO.COM.ACH.TRXID"
        },
        "01": {
          "id": "01",
          "len": 19,
          "data": "62FB70176DC0B870F58",
          "rawData": "62FB70176DC0B870F58"
        }
      },
      "rawData": "0016CO.COM.ACH.TRXID011962FB70176DC0B870F58"
    },
    "91": {
      "id": "91",
      "name": "Unreserved Templates",
      "len": 86,
      "data": {
        "00": {
          "id": "00",
          "name": "Global Unique Identifier",
          "len": 14,
          "data": "CO.COM.ACH.SEC",
          "rawData": "CO.COM.ACH.SEC"
        },
        "01": {
          "id": "01",
          "len": 64,
          "data": "ac77cb8cc46f1e0aee1b8e3212bc9f27bcb8ec16aaf38d2ce42194a92bfc4d12",
          "rawData": "ac77cb8cc46f1e0aee1b8e3212bc9f27bcb8ec16aaf38d2ce42194a92bfc4d12"
        }
      },
      "rawData": "0014CO.COM.ACH.SEC0164ac77cb8cc46f1e0aee1b8e3212bc9f27bcb8ec16aaf38d2ce42194a92bfc4d12"
    },
    "00": {
      "id": "00",
      "name": "Payload Format Indicator",
      "len": 2,
      "data": "01",
      "rawData": "01"
    },
    "01": {
      "id": "01",
      "name": "Point of Initiation Method",
      "len": 2,
      "data": "11",
      "rawData": "11"
    }
  }
}

{
  "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"
  }
}

{
  "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"
  }
}

⌘I