> ## Documentation Index
> Fetch the complete documentation index at: https://transfiya.me/llms.txt
> Use this file to discover all available pages before exploring further.
# Como enviar cuenta a cuenta
> Guia sobre transferencias cuenta a cuenta usando Transfiya
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).
```mermaid theme={null}
sequenceDiagram
autonumber
participant sb as Banco Origen
participant ty as Transfiya
participant tb as Banco Destino
sb ->>+ ty: Crear transferencia
ty ->> ty: Validar reglas de negocio
ty -->>- sb: Transferencia creada
alt Débito (asíncrono)
ty ->>+ sb: Llamar a débito
sb ->> sb: Procesar débito
sb ->> -ty: Continuar transferencia
end
ty ->> ty: Resolver firmante destino
ty ->> ty: Aceptar transferencia
alt Acción (síncrona)
ty ->>+ sb: Llamar a acción
sb ->> sb: Procesar acción
sb -->>- ty: Respuesta de acción
end
alt Crédito (asíncrono)
ty ->>+ tb: Llamar a crédito
tb ->> tb: Procesar crédito
tb ->> tb: Firma con Signer Registrado
tb ->> -ty: Continuar transferencia
end
ty ->>+ sb: Consultar estado
sb -->>- ty: Respuesta de estado
ty ->>+ tb: Consultar estado
tb -->>- ty: Respuesta de estado
```
```mermaid theme={null}
sequenceDiagram
autonumber
participant sb as Banco Origen
participant ty as Transfiya
participant tb as Banco Destino
sb ->>+ ty: Crear transferencia
ty ->> ty: Validar reglas de negocio
ty -->>- sb: Transferencia creada
alt Débito (asíncrono)
ty ->>+ sb: Llamar a débito
sb ->> sb: Procesar débito
sb ->> -ty: Continuar transferencia
end
ty ->> ty: Resolver firmante destino
alt Onboarding (asíncrono)
ty ->>+ tb: Consultar estado (PENDING)
tb -->> ty: Confirmar recepción
tb ->> tb: Validar cuenta
tb ->>+ ty: Crear firmante
ty -->>- tb: Respuesta de creación
tb ->> -ty: Aceptar transferencia
end
alt Acción (síncrona)
ty ->>+ sb: Llamar a acción
sb ->> sb: Procesar acción
sb -->>- ty: Respuesta de acción
end
alt Crédito (asíncrono)
ty ->>+ tb: Llamar a crédito
tb ->> tb: Procesar crédito
tb ->> -ty: Continuar transferencia
end
ty ->>+ sb: Consultar estado
sb -->>- ty: Respuesta de estado
ty ->>+ tb: Consultar estado
tb -->>- ty: Respuesta de estado
```
```mermaid theme={null}
sequenceDiagram
autonumber
participant sb as Banco Origen
participant ty as Transfiya
participant tb as Banco Destino
sb ->>+ ty: Crear transferencia
ty ->> ty: Validar reglas de negocio
ty -->>- sb: Transferencia creada
alt Débito (asíncrono)
ty ->>+ sb: Llamar a débito
sb ->> sb: Procesar débito
sb ->> -ty: Continuar transferencia
end
ty ->> ty: Resolver signer genérico
ty ->> ty: Aceptar transferencia
alt Acción (síncrona)
ty ->>+ sb: Llamar a acción
sb ->> sb: Procesar acción
sb -->>- ty: Respuesta de acción
end
alt Crédito (asíncrono)
ty ->>+ tb: Llamar a crédito
tb ->> tb: Procesar crédito
tb ->> tb: Firma con Signer Genérico
tb ->> -ty: Continuar transferencia
end
ty ->>+ sb: Consultar estado
sb -->>- ty: Respuesta de estado
ty ->>+ tb: Consultar estado
tb -->>- ty: Respuesta de estado
```
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 | 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
El número de cuenta no deberá superar los 34 caracteres de longitud y en caso de que aplique, contemplar los 0 (ceros) a la izquierda. |
| 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 (9 caracteres máximo). |
| 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 (9 caracteres máximo).. |
| 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 |
```json theme={null}
curl -X POST \
-H "Content-Type: application/json" \
-H "x-api-key: " \
-H "Authorization: Bearer " \
-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"
}
}
}' "/v1/transfer"
```
```json theme={null}
{
"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`
```bash theme={null}
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`
```bash theme={null}
curl --location '{{url}}/v1/signer/lookup.dice' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ' \
--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.