Cuentas bancarias Colombia

Registra, consulta y elimina cuentas bancarias colombianas vinculadas al usuario.

Todos los endpoints requieren autenticación con Authorization: Bearer [TOKEN] y x-api-key.

Resumen de endpoints

Endpoint	Método	Descripción
`/banks/`	GET	Listar bancos disponibles por país (query: country)
`/base/country`	GET	Listar países
`/states/`	GET	Listar estados por país (query: country)
`/base/document_type/`	GET	Listar tipos de documento
`/create_third_party_banks/`	POST	Crear cuenta bancaria
`/list_third_party_banks/`	GET	Listar cuentas del usuario (query: country)
`/thirdpartybank`	PUT	Actualizar cuenta (pk y campos a editar: alias, account_number, etc.)
`/usd/user/account`	GET / POST	Listar o crear cuentas USD

🔒

Las cuentas Third Party (CO, US clásicas) son inmutables: no hay endpoints para modificar ni eliminar. Las cuentas en USD (identificadas por ID alfanumérico) sí permiten actualizar el alias y desactivar (ocultar).

Países y tipos de cuenta

El sistema soporta Colombia (CO) y Estados Unidos (US). Cada país tiene tipos de cuenta y validaciones propias.

Tipos de cuenta por país

País	account_type	Descripción
CO, US	`0`	Ahorros
CO, US	`1`	Corriente

Cuentas USA: campos obligatorios

Para country_registered: "US" son obligatorios: wire, routing_number, address y nickname.

Listar bancos disponibles

Autorización

Se requieren el header x-api-key y Authorization: Bearer <token>.

Endpoint

GET/banks/

Headers Requeridos

Content-Type: application/jsonAccept: application/jsonx-api-key: [API_KEY]Authorization: Bearer [ACCESS_TOKEN]

Respuesta

response.json

[
{ "id": 0, "name":  "Bancolombia"},
{ "id": 1, "name":  "Banco de Bogota"},
{ "id": 2, "name":  "Davivienda"},
{ "id": 3, "name":  "BBVA Colombia"}
]

💡

Usa el `id` del banco en `bank_name` al crear la cuenta. Query: `country` (CO, US). El sistema soporta 35+ bancos en Colombia y 50+ en USA.

Listar tipos de documento

Autorización

Se requieren el header x-api-key y Authorization: Bearer <token>.

Endpoint

GET/base/document_type/

Headers Requeridos

Content-Type: application/jsonAccept: application/jsonx-api-key: [API_KEY]Authorization: Bearer [ACCESS_TOKEN]

Respuesta

response.json

[
{ "id": 0, "name":  "CC"},
{ "id": 1, "name":  "CE"},
{ "id": 2, "name":  "NIT"},
{ "id": 3, "name":  "TI"},
{ "id": 4, "name":  "PPT"}
]

El `id` se usa en `account_holder_document_type`. Los tipos válidos dependen del país.

Crear cuenta bancaria

Autorización

Se requieren el header x-api-key y Authorization: Bearer <token>.

Endpoint

POST/create_third_party_banks/

Headers Requeridos

Content-Type: application/jsonAccept: application/jsonx-api-key: [API_KEY]Authorization: Bearer [ACCESS_TOKEN]

Request Body

Campo	Tipo	Requerido	Descripción
account_holder_name	string	✓	Nombre completo del titular
account_type	int	✓	0 = Ahorros, 1 = Corriente (CO/US)
account_holder_document_type	int	✓	ID del tipo de documento
account_holder_document	string	✓	Número de documento
account_number	string	✓	Número de cuenta
bank_name	int	✓	ID del banco
country_registered	string	✓	CO o US
nickname	string	✕	Alias (obligatorio en US)
wire	string	✕	Nombre banco SWIFT (obligatorio en US)
routing_number	string	✕	Routing/ABA (obligatorio en US)
address	string	✕	Dirección del banco (obligatorio en US)

request.json{
"account_holder_name": "Sofia Martin",
"account_type": 0,
"account_holder_document_type": 0,
"account_holder_document": "12345678",
"account_number": "58200011161",
"bank_name": 0,
"country_registered": "CO",
"nickname": "Cuenta Principal"
}

Respuesta

response.json

{
"code_transaction": "OK",
"data": {
  "id": 85,
  "account_holder_name": "Sofia Martin",
  "account_number": "58200011161",
  "bank_name": 0,
  "country_registered": "CO",
  "nickname": 
"Cuenta Principal"}
}

Errores Posibles

Código	Error	Descripción
400	Bad Request	Banco, tipo de cuenta o documento no válido para el país
400	Bad Request	La cuenta ya está registrada en el sistema
400	Bad Request	Para US: faltan wire, routing_number, address o nickname

💾

Guarda el `id` (data.id) para usarlo en retiros (third_party_bank_id) o en Exchange (bank_account_id).

Validaciones: bank_name válido para el país; account_type 0 o 1; tipo de documento válido; no duplicar cuenta. USA requiere wire, routing_number, address y nickname.

Listar cuentas bancarias del usuario

Autorización

Se requieren el header x-api-key y Authorization: Bearer <token>.

Endpoint

GET/list_third_party_banks/

Headers Requeridos

Content-Type: application/jsonAccept: application/jsonx-api-key: [API_KEY]Authorization: Bearer [ACCESS_TOKEN]

Respuesta

response.json

{
"count": 1,
"next": null,
"previous": null,
"results": [
  {
    "pk": 85,
    "account_holder_name": "Sofia Martin",
    "account_type": 1,
    "account_number": "58200011161",
    "bank_name": 0,
    "state": "Creada",
    "country_registered": 
  "CO"}
]
}

Query opcional: `country` (CO, US). Estados: Creada, En proceso de inscripción, Inscrita, Tiene un problema.

Cuentas USD (ID alfanumérico)

Las cuentas en dólares (USD) que se identifican por ID alfanumérico permiten retiros y depósitos en USD. A diferencia de las cuentas Third Party (ID numérico), en estas cuentas sí puedes cambiar el nombre/alias y desactivar la cuenta (ocultarla).

Diferencias con Third Party Banks

	Third Party (CO, US)	Cuentas USD (ID alfanumérico)
ID	Numérico (ej. `85`)	Alfanumérico (ej. `account_abc123`)
Alias	Campo `nickname` (solo al crear)	Campo `name` (modificable con PUT)
Modificar / Desactivar	No disponible	Sí: PUT para cambiar `name` o `status: DEACTIVATED`

Actualizar cuenta USD (cambiar nombre o desactivar)

Autorización

Se requieren el header x-api-key y Authorization: Bearer <token>.

Endpoint

PUT/thirdpartybank

Headers Requeridos

Content-Type: application/jsonAccept: application/jsonx-api-key: [API_KEY]Authorization: Bearer [ACCESS_TOKEN]

Request Body

Campo	Tipo	Requerido	Descripción
bank_account_id	string	✓	ID de la cuenta USD (alfanumérico)
name	string	✕	Nuevo alias (solo uno: name o status)
status	string	✕	Solo DEACTIVATED para desactivar/ocultar

request.json{
"bank_account_id": "account_abc123",
"name": "Mi Cuenta Principal USD"
}

Respuesta

response.json

{
"code_transaction": "OK",
"result": 
"The bank account have been updated"}

Errores Posibles

Código	Error	Descripción
400	Bad Request	No enviar name y status=DEACTIVATED juntos
400	Bad Request	Nombre ya usado por otra cuenta
404	Not Found	Cuenta USD no encontrada

En un mismo request envía solo `name` o solo `status: DEACTIVATED`. La desactivación es permanente; la cuenta deja de aparecer en el listado.

Listar cuentas USD

Autorización

Se requieren el header x-api-key y Authorization: Bearer <token>.

Endpoint

GET/usd/user/account

Headers Requeridos

Content-Type: application/jsonAccept: application/jsonx-api-key: [API_KEY]Authorization: Bearer [ACCESS_TOKEN]

Respuesta

response.json

{
"data": {
  "payment_types": [
    {
      "id": 1,
      "payment_method": "BANK_TRANSFER",
      "account_id": "account_abc123",
      "name": "Mi Cuenta Principal USD",
      "routing": "021000021",
      "account_number": "1234567890",
      "status": "DEPOSIT_ONLY",
      "type": "CHECKING",
      "created_at": 
    "2026-02-03T10:00:00Z"}
  ]
},
"message": 
"ok"}

📌

Usa el `account_id` como `bank_account_id` en PUT para actualizar o desactivar. Las cuentas desactivadas no se incluyen. Solo se puede modificar el nombre; no routing ni número de cuenta.

Uso de las cuentas

Una vez creada, la cuenta se usa en:

Retiros bancarios: POST /create/third_party_withdraw/ con el campo third_party_bank_id (Colombia COP) o en flujos USD.
Exchange (FX): POST /v2/exchange/initiate/ con el campo bank_account_id para la dispersión automática al completar el movimiento.

El sistema valida que la cuenta pertenezca al usuario autenticado antes de ejecutar el retiro o el movimiento.

📄

Para el flujo completo de retiros por país, consulta Retiros Bancarios. Para movimientos transfronterizos con dispersión, consulta Exchange (FX).

Cómo gestionar cuentas bancarias Cuentas bancarias EEUU