Skip to main content
El presente documento tiene como proposito orientar a las Entidades Participantes en el proceso necesario para iniciar una transaccion Bre-b a partir de la lectura de un codigo QR. Aqui se describen los pasos, requisitos tecnicos, consideraciones operativas y mejores practicas que garantizan una experiencia de pago eficiente, segura y estandarizada. Esta guia busca asegurar que todas las Entidades involucradas comprendan plenamente el flujo de la transaccion, los elementos obligatorios contenidos en el QR y las validaciones que deben realizarse para completar exitosamente la operacion. Al seguir estas indicaciones, las Entidades Participantes podrán integrar y ejecutar el proceso Bre-b de forma consistente, manteniendo altos niveles de calidad en el servicio ofrecido a sus usuarios.

​
Flujo general del proceso

Swimlanes Be6ac962046db967406b47d4df222c20

​
Paso a paso

  1. Escanear el QR: La Entidad Particiánte origen, a través de la UX deberá presentar la opción para escanear códigos QR a sus usuarios.
  2. Lectura de QR: Una vez realizado el escaneo, la Entidad participante obtiene la cadena TLV y debe enviar esta cadena al servicio expuesto por Transfiya para obtener un objeto JSON estructurado y legible con los datos del QR. El detalle de este proceso podrá ser consultado en el apartado Cómo leer un QR - Transfiya Guide.
  3. Resolución de llave: Con los datos obtenidos en la respuesta al servicio de lectura, la Entidad Participante origen debe identificar el valor de la llave y efectuar el proceso de resolución a través del servicio expuesto por Transfiya, como se detalla en Cómo resolver llaves - Transfiya Guide. A continuación se muestra el dato que la entidad debe extraer del JSON para obtener la llave. 
    {
    "26": {
        "id": "26",
        "name": "Merchant Account Information",
        "len": 30,
        "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": 16,
                "data": "0099545147", // Dato correspondiente al valor de llave
                "rawData": "0099545147"
            }
        },
    El JSON es un fragmento de la respuesta enviada por Transfiya al consumo del servicio de lectura.
    Dentro del campo “26”, se podrá encontrar entre otros:
    Objeto 2 -> “name” (Tipo de llave)
    “data” (Valor de llave). Este es el que se deberá mapear para posteriormente procesar la resolución.
  4. Mapear datos adicionales del QR: El JSON con los datos del QR, contienen información necesaria para poder iniciar la transferencia en Transfiya. En el siguiente cuadro se detallan los campos obligatorios para crear la transacción en Bre-b.
    Tag (JSON)NombreDescripción
    54Transaction AmountEl cual contiene el monto del QR (si su valor es > a 0.00)
    90Unreserved Templates (IdQR)Contiene el ID de QR generado por el SPBVI o la Entidad Participante que generó el QR.
 },
    "54": {
        "id": "54",
        "name": "Transaction Amount",
        "len": 4,
        "data": "1000.00", // Valor a mapear
        "rawData": "1000.00"
    },
	"90": {
        "id": "90",
        "name": "Unreserved Templates",
        "len": 43,
        "data": {
            "00": {
                "id": "00",
                "name": "Globally Unique Identifier",
                "len": 16,
                "data": "CO.COM.ACH.TRXID", //Valor a Mapear y concatenar con "data" del subtag 01
                "rawData": "CO.COM.ACH.TRXID"
            },
            "01": {
                "id": "01",
                "name": "Payment System specific",
                "len": 19,
                "data": "6A1AB61E0E8ADAB4BB9", //Valor a Mapear y concatenar con "data" del subtag 01
                "rawData": "6A1AB61E0E8ADAB4BB9"
            }
        },
Los demás datos contenidos en el JSON, podrán ser usados por las Entidades Participantes para los fines que consideren pertinentes.
El JSON es un fragmento de la respuesta enviada por Transfiya al consumo del servicio de lectura.
A futuro Bre-b podrá solicitar la inclusión de más campos en la mensajería para el procesamiento transaccional.
  1. Iniciar la transacción: Con los datos obtenidos de la resolución de la llave (signer handle), Transaction Amount y el IdQR. La Entidad Participante está lista para iniciar la transacción, para esto deberá invocar el servicio expuesto por Transfiya. Se relaciona una tabla con la homologación de los campos y un ejemplo que sirve como guia.
    TransferQR Tag (JSON)Descripción
    sourceN/ASigner handle del usuario originador de la transacción.
    targetN/ASigner handle obtenido de la resolución de la llave destino.
    symbolN/AValor por defecto
    amount54Valor de la transación. Si en el QR, el tag 54 (amount) tiene un valor diferente a 0.00. Debe enviarse el valor de dicho campo. De lo contrario, se debe enviar el valor que ingresa el usuario dentro de la UX durante la iniciación de la transacción.
    labelsN/AObjeto
    descriptionN/ADescripción de la transacción
    domainN/ADominio de Transfiya.
    typeN/ADescribe al tipo de transacción a procesar. Para este caso es SENDMOL
    sourceChannelN/ACorresponde al canal que se usa para generar a transferencia
    tx_idN/ACorresponde al tx_id asignado por la Entidad origen, debe ser generado y enviado según las especificaciones de Bre-b
    idQr90Corresponde al id QR asignado por la Entidad que genera la transacción. La construcción de este campo debe ser la concatenación del valor del campo “data” (subtag 00) y el valor del campo “data” (subtag 01). Ejemplo: CO.COM.ACH.TRXID6A1AB61E0E8ADAB4BB9
    receivedN/AMarca de tiempo regulatoria
    dispatchedN/AMarca de tiempo regulatoria
    deviceFingerPrintN/AObjeto con la información del dispositivo que genera la tx. Este objeto debe ser capturado con la respectiva librearía o en su defecto, como la Entidad lo haga.

​
Request creación de transferencia

curl -X POST \
-H "Content-Type: application/json" \
-H "x-api-key: <API_KEY>" \
-H "Authorization: Bearer <TOKEN>" \
-d '{
"source": "wXxwpxB32saqfmfMxAQD4SVWWhhn6akLC2",
"target": "wRFmYXS2sP9ho9VCZ3j4FuP1j55ABeFvsF",
"symbol": "$tin",
"amount": "100.00",
"labels": {
"description": "Payment for lunch",
"domain": "tin",
"type": "SENDMOL",
"sourceChannel": "APP",
"tx_id": "20250114890915944TFY123456789012345",
"idQr":"CO.COM.ACH.TRXID6A1AB61E0E8ADAB4BB9",
"received": "2025-01-14T20:40:57.322-05:00",
"dispatched": "2025-01-14T20:40:58.322-05:00",
"deviceFingerPrint": {
  "hash": "26fff5af6441f8e15a71e8d62c361714484b1b308c99e8eb68ca85e2a7e0dc58",
  "ipAddress": "2001:0db8:85a3:0000:0000:8a2e:0370:7334",
  "country": "Colombia",
  "city": "Bogotá",
  "mobileDevice": "990000862471854",
  "SIMCardId": "8991101200003204510",
  "model": "Huawei Mate 20 Pro",
  "operator": "Bharti Airtel Limited"
}
}
}' "<TRANSFIYA URL>/v1/transfer"
  1. Confirmación de la creación de transacción y procesamiento: Una vez la Entidad Participante origen solicite la inciación de transferencia en Transfiya. El sistema ejecuta el procesamiento de manera habitual y que las Entidades ya conocen. El detalle podrá ser consulta y revisado en Sobre Flujo Regulatorio - Transfiya Guide.