Skip to main content
Para soportar los modelos de transferencia en Transfiya para Empresas, es necesario permitir la referencia directa a cuentas bancarias en los campos source y target de cada transacción. La estructura de estas referencias debe contener información sobre el tipo de cuenta, el número de cuenta y el banco al cual pertenece.

​
📌 Sintaxis de Referencia

  • bankAccountType: tipo de cuenta (en minúsculas), basado en los valores estándar de Transfiya.
  • bankAccountNumber: número de cuenta bancaria (coincide con labels.bankAccountNumber del signer).
  • routerReference: código de compensación o Bicfi válido del banco receptor.
Este formato unificado garantiza consistencia y compatibilidad con los mecanismos de enrutamiento de Transfiya, facilitando la interoperabilidad entre participantes.

​
🏦 Tipos de Cuenta Soportados

A continuación se listan los tipos de cuenta reconocidos en Transfiya:
NombreValor
Cuenta de ahorrossvgs
Cuenta corrientecacc
Depósito de bajo montodbmo
Depósito ordinariodord
Depósito inclusivo bajo montodbmi
Estos valores deben utilizarse exclusivamente en minúsculas y reflejan el tipo de cuenta real registrada por el firmante en el sistema financiero.

​
🌐 Referencia Bancaria

El identificador del banco (bankReference) debe ser el código de compensación o Bicfi válido, que permita una resolución clara y única del participante receptor.

​
✅ Ejemplo de referencia válida

svgs:44255107106500@1001 Transferencias cuenta a cuenta con y sin signer de tipo cuenta
Cuando el usuario receptor ya está registrado en Transfiya, la transferencia se acepta automáticamente tras la validación de reglas y ejecución del débito. Sin embargo, si el usuario aún no está registrado, el flujo requiere una etapa adicional de onboarding:Transfiya notifica al banco destino que existe una transferencia pendiente.El banco destino debe validar los datos y crear el firmante (usuario).Una vez completado el onboarding, el banco acepta la transferencia manualmente.
Esta diferencia impacta directamente en los tiempos de procesamiento y en la lógica de integración de los participantes, ya que se introduce una validación activa del banco destino antes de continuar con las siguientes fases (acción, crédito y estado).
  • Flujo con Signer Registrado
  • Flujo sin Signer Registrado
  • Flujo con Signer Genérico
Crear una transferencia hacia una cuenta bancaria se realiza de la misma forma que cualquier otra transferencia en Transfiya. La única diferencia es que, en el campo target, no se utiliza un alias, sino una referencia directa a la cuenta bancaria.
Este tipo de transferencia es útil cuando se conoce directamente el número de cuenta, tipo de cuenta y banco destino, sin necesidad de pasar por el directorio de alias.
Se agregan los atributos de nombre, tipo de identificación e identificación al tipo de transferencia de cuenta a cuenta. Estos serán utilizados por la entidad receptora en caso de que decida usar su signer genérico.
  • Request
  • Response
curl -X POST \
-H "Content-Type: application/json" \
-H "x-api-key: <API_KEY>" \
-H "Authorization: Bearer <TOKEN>" \
-d '{
"source": "wXxwpxB32saqfmfMxAQD4SVWWhhn6akLC2",
"target": "svgs:44255107106500@1001",
"amount": "100.00",
"symbol": "$tin",
"labels": {
"type": "SEND",
"domain": "tin",
"description": "Salary for March",
"sourceChannel": "APP",
"tx_id": "20250114890915944TFY123456789012345",
"source":{
  "name": "Johnny Wayney",
  "proprietary": "cc",
  "identification": "35111223456"
},  
"target":{
  "name": "John Wicky Wayne",
  "proprietary": "cc",
  "identification": "35111223455"
},  
"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"

​
🧩 ¿Qué hacer si la cuenta destino no está registrada?

En los flujos de transferencia cuenta a cuenta, es posible que la cuenta destino no tenga un signer activo en el sistema. En ese caso, Transfiya invoca automáticamente el endpoint /credit de la entidad receptora, utilizando un signer genérico. Este mecanismo permite acreditar fondos incluso cuando el usuario aún no ha sido registrado formalmente.
Para que esta funcionalidad funcione correctamente, la entidad receptora debe haber creado previamente un signer genérico . Puedes revisar cómo hacerlo en la sección de Signers Genéricos.

​
🏦 ¿Cómo se acredita la cuenta?

Transfiya envía al endpoint /credit toda la información necesaria que la entidad receptora necesita para realizar la acreditación de fondos. Esta información viene dentro del campo target.signer.labels e incluye:
  • name: Nombre del titular
  • proprietary: Tipo de documento (ej. CC, NIT)
  • identification: Número de identificación
  • bankAccountType: Tipo de cuenta (svgs, cacc, etc.)
  • bankAccountNumber: Número de cuenta
  • bankId: Identificador del banco (BICFI)
Solo deben implementar este proceso aquellas entidades que no hayan implementado el onboarding automático para transferencias cuenta a cuenta y hayan configurado previamente un signer genérico.

​
🧪 Ejemplo del endpoint /credit

POST https://ban.co/transfiya/credit
{
    "source": "wXxwpxB32saqfmfMxAQD4SVWWhhn6akLC2",
    "target": "wRFmYXS2sP9ho9VCZ3j4FuP1j55ABeFvsF",
    "amount": "100.00",
    "symbol": "$tin",
    "labels": {
        "hash": "82de7c0b8b34c7ca6c52547161b2629b1c1e6bdef402999ad60266e6760e4d24",
        "type": "SEND",
        "domain": "tin",
        "flowId": "Lf13jsK83omPv3bOt",
        "status": "COMPLETED",
        "tx_ref": "Lf13jsK83omPv3bOt",
        "tx_id": "20250114890915944TFY123456789012345",
        "created": "2025-01-14T20:40:57.322-05:00",
        "updated": "2025-01-14T20:41:00.841-05:00",
        "description": "Payment for lunch",
        "sourceChannel": "APP",
        "deviceFingerPrint": {
        "city": "Bogotá",
        "hash": "26fff5af6441f8e15a71e8d62c361714484b1b308c99e8eb68ca85e2a7e0dc58",
        "model": "Huawei Mate 20 Pro",
        "country": "Colombia",
        "operator": "Bharti Airtel Limited",
        "SIMCardId": "8991101200003204510",
        "ipAddress": "2001:0db8:85a3:0000:0000:8a2e:0370:7334",
        "mobileDevice": "990000862471854"
        }
    },
    "snapshot": {
        "source": {
        "signer": {
            "handle": "wXxwpxB32saqfmfMxAQD4SVWWhhn6akLC2",
            "labels": {
            "name": "Maria Fernanda Gomez",
            "proprietary": "CC",
                "identification": "2020202020",
            "bankAccountType": "SVGS",
            "bankAccountNumber": "95445654254",
            "bankId": "895554821",
            "targetSpbviCode": "TFY"
            }
        },
        },
        "symbol": {
        "signer": {
            "handle": "wMxKCAzsQBiUURDU3xD3xuSbVo1S9jmf3d",
            "labels": {
            "created": "2018-10-19T20:23:22.041Z",
            "createdBy": "ZhrQA3vcm17h2RRO4LrJ"
            }
        }
        },
        "target": {
        "signer": {
            "handle": "wRFmYXS2sP9ho9VCZ3j4FuP1j55ABeFvsF",
            "labels": {
            "name": "Jorge Alejandro Fernandez Garcia",
            "proprietary": "CC",
            "identification": "1010101010",
            "bankAccountType": "SVGS",
            "bankAccountNumber": "12345654321",
            "bankId": "891234918",
            }
        },
        }
    },
    "error": {
        "code": 0,
        "message": "Success"
    },
    "action_id": "35de4d3d-3aba-4fb3-b110-d004ce2aabb2",
    "id": "35de4d3d-3aba-4fb3-b110-d004ce2aabb2"
    }
✅ ¿Qué hace la entidad receptora? La entidad receptora debe procesar la acreditación utilizando únicamente los datos recibidos en target.signer.labels. Esto le permite evitar procesos de onboarding y acreditar directamente a la cuenta bancaria especificada por la entidad originadora.
Este flujo permite interoperabilidad con cuentas no registradas, mejorando la experiencia del usuario sin sacrificar seguridad ni trazabilidad.

​
🕵️ ¿Qué hacer si no tengo la información de la cuenta del receptor?

En algunos casos, la entidad originadora puede no tener acceso directo al tipo y número de cuenta del cliente receptor. Para estos escenarios, Transfiya permite realizar una búsqueda utilizando alias registrados, ya sea para personas o empresas, mediante el Directorio Federado. Para ello, existen dos servicios disponibles:
  • lookup.dice: para búsquedas reguladas bajo el modelo SPI.
  • signer.lookup: para búsquedas no reguladas.
Estos métodos permiten al participante origen consultar el alias y recuperar toda la información necesaria del firmante receptor para poder inicializar correctamente una transacción de tipo cuenta a cuenta.

​
🔍 Ejemplo de uso de lookup.dice

curl --location '{{url}}/v1/signer/lookup.dice' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>' \
--data-raw '{
  "aliasValue": "@testing",
  "received": "2025-04-10T15:49:15.015-05:00",
  "dispatched": "2025-04-10T15:49:15.015-05:00"
}'
📦 ¿Qué devuelve la consulta? La respuesta del directorio incluye datos esenciales como: • Nombre completo del titular • Tipo de cuenta (svgs, cacc, etc.) • Número de cuenta • Tipo y número de documento • Banco asociado Con esta información, la entidad originadora puede construir la referencia de cuenta y ejecutar la transferencia como si ya conociera esos datos desde el inicio.
Esta funcionalidad es especialmente útil en transferencias empresariales o institucionales donde las relaciones entre participantes están basadas en alias conocidos públicamente.