Como enviar cuenta a cuenta

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:

Nombre	Valor
Cuenta de ahorros	`svgs`
Cuenta corriente	`cacc`
Depósito de bajo monto	`dbmo`
Depósito ordinario	`dord`
Depósito inclusivo bajo monto	`dbmi`

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.

Campos de entrada - Transfer cuenta a cuenta

Nombre	Tipo	Descripción	Longitud	Obligatorio	Condiciones adicionales y reglas
source	string	Handle del signer origen ó estructura del cuenta a cuenta si se usará GENERIC signer como origen	Min 1 - Max 50	SI	N/A
target	string	Datos del receptor	Min 1 - Max 80	SI	La estructura debe ser: tipo de cuenta:número de cuenta@código compensación del banco receptor Ej: svgs:88745145@1007 Los valores : y @ son fijos
amount	number	Monto de la transacción	Min 1 - Max 13	SI	Separador del decimal es punto (.) Soporta 2 decimales
symbol	string	Simbolo del sistema	Min 1 - Max 4	SI	Valor estático “$tin”
labels	Object			SI	Objeto que contiene información
type	string	Tipo de transacción	Min 1 - Max 4	SI	Valo fijo “SEND”
domain	string	Dominio de la transacción	Min 1 - Max 3	SI	Valor fijo “tin”
description	string	Descripción	Min 1 - Max 80	NO	N/A
sourceChannel	string	Canal origen de la transacción	Min 1 - Max 3	SI	Soporta: IM, POS, APP, WEB, ECOMM, ATM, PSE
tx_id	string	Identificación de la transferencia	Min 1 - Max 36	NO	Identificador asignado por la Entidad Originadora
transactionPurpose	string	Propósito de la transferencia	Min 1 - Max 13	SI	Valor fijo “TRANSFER”
source	Object			SI	Objeto que contiene información
name	string	Nombre del originador	Min 1 Max 160	SI	Nombre o razón social
proprietary	string	Tipo de documento del originador	Min 1 - Max 4	SI	Soporta: CC,CE,PA,TI,NUIP,NIT,OTR,PPT,PEP En mayúscula
identification	string	Número de identificación del originador	Min 1 Max 34	SI	Cuando el tipo de documento es NIT, el valor es sin digito de verificación y sin guion.
target	Object			SI	Objeto que contiene información
name	string	Nombre del beneficiario	Min 1 Max 160	SI	Nombre o razón social
proprietary	string	Tipo de documento del beneficiario	Min 1 - Max 4	SI	Soporta: CC,CE,PA,TI,NUIP,NIT,OTR,PPT,PEP En mayúscula
identification	string	Número de identificación del beneficiario	Min 1 Max 34	SI	Cuando el tipo de documento es NIT, el valor es sin digito de verificación y sin guion.
deviceFingerPrint	string			NO	Objeto que contiene información del dispositivo origen Se envia el objeto y el campo si se logra capturar información del dispostivo origen

Request
Response

curl -X POST \
-H "Content-Type: application/json" \
-H "x-api-key: <API_KEY>" \
-H "Authorization: Bearer <TOKEN>" \
-d '{
"source": "widwXWf5JLoU5NsaxLM3Sjs9gRRauC3R4H", // Handle Signer Business, Generic o Person
"target": "svgs:44255107106500@1001",
"amount": "100.00",
"symbol": "$tin",
"labels": {
"type": "SEND",
"domain": "tin",
"description": "Salary for March",
"sourceChannel": "APP",
"tx_id": "20250114890915944TFY123456789012345",
"transactionPurpose": "TRANSFER",
"numberOfTransactions": "1",
"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"

{
"source": "wXxwpxB32saqfmfMxAQD4SVWWhhn6akLC2",
"target": "wfvmRir8XxRtoEuUBDkv3BP4T7BQezwm1f",
"amount": "100.00",
"symbol": "$tin",
"labels": {
"hash": "PENDING",
"type": "SEND",
"domain": "tin",
"flowId": "Lf13jsK83omPv3bOt",
"status": "PENDING",
"tx_ref": "Lf13jsK83omPv3bOt",
"created": "2025-01-14T20:40:57.322-05:00",
"updated": "2025-01-14T20:40:57.322-05:00",
"description": "DEV - SEND trx 01",
"sourceChannel": "APP",
"transactionPurpose": "TRANSFER",
"numberOfTransactions": "1",
"name": "John Wicky Wayne",
"proprietary": "cc",
"identification": "35111223455",
"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": "Jorge Alejandro Fernandez Garcia",
    "proprietary": "CC",
        "identification": "1010101010",
    "bankAccountType": "SVGS",
    "bankAccountNumber": "12345654321",
      "bankId": "891234918",
    }
  },
},
"target": {
  "signer": {
   "handle": "wfvmRir8XxRtoEuUBDkv3BP4T7BQezwm1f",
    "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é 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.

🏦 ¿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.

​📌 Sintaxis de Referencia

​🏦 Tipos de Cuenta Soportados

​🌐 Referencia Bancaria

​✅ Ejemplo de referencia válida

​Campos de entrada - Transfer cuenta a cuenta

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

​🏦 ¿Cómo se acredita la cuenta?

​🧪 Ejemplo del endpoint /credit

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

​🔍 Ejemplo de uso de lookup.dice

📌 Sintaxis de Referencia

🏦 Tipos de Cuenta Soportados

🌐 Referencia Bancaria

✅ Ejemplo de referencia válida

Campos de entrada - Transfer cuenta a cuenta

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

🏦 ¿Cómo se acredita la cuenta?

🧪 Ejemplo del endpoint `/credit`

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

🔍 Ejemplo de uso de `lookup.dice`