Cuentas bancarias

Endpoints para listar bancos, tipos de documento, crear y listar cuentas bancarias de terceros asociadas al usuario. Estas cuentas se usan en Retiros y en Exchange (FX) para dispersión.

Resumen de endpoints

Países y tipos de cuenta

El sistema soporta Colombia (CO), Estados Unidos (US), México (MX) y Brasil (BR). Cada país tiene tipos de cuenta y validaciones propias.

Tipos de cuenta por país

Cuentas USA: campos obligatorios

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

Listar bancos disponibles

Obtiene la lista de bancos disponibles para retiros/transferencias según el país.

Endpoint

GET /bank_list_third_party_withdraw/

Headers

Authorization: Bearer [ACCESS_TOKEN]
x-api-key: [API_KEY]
Accept: application/json

Respuesta (200)

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

Listar tipos de documento

Obtiene los tipos de documento de identidad válidos para el titular de la cuenta.

Endpoint

GET /base/document_type/

Headers

Authorization: Bearer [ACCESS_TOKEN]
x-api-key: [API_KEY]
Accept: application/json

Respuesta (200)

[
  { "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

Registra una cuenta bancaria de terceros asociada al usuario. La cuenta se usa luego en retiros o en movimientos Exchange (dispersión).

Endpoint

POST /create_third_party_banks/

Headers

Authorization: Bearer [ACCESS_TOKEN]
x-api-key: [API_KEY]
Content-Type: application/json

Request (campos comunes y por país)

{
  "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"
}

{
  "account_holder_name": "John Doe",
  "account_type": 0,
  "account_holder_document_type": 0,
  "account_holder_document": "123456789",
  "account_number": "1234567890",
  "bank_name": 103,
  "country_registered": "US",
  "routing_number": "021000021",
  "wire": "JPMorgan Chase Bank",
  "address": "270 Park Avenue, New York, NY 10017",
  "nickname": "Main Account"
}

curl -X POST "https://api.colurs.co/create_third_party_banks/" \
  -H "Authorization: Bearer [TOKEN]" \
  -H "x-api-key: [API_KEY]" \
  -H "Content-Type: application/json" \
  -d '{
    "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"
  }'

Validaciones

• Banco por país: bank_name debe ser un banco válido para country_registered.
• Tipo de cuenta por país: account_type debe ser uno de los permitidos para ese país.
• Formato de cuenta: Para CLABE (MX) y PIX (BR) se valida el formato con regex (ej.: CLABE 18 dígitos, PIX CPF 11 dígitos).
• Tipo de documento por país: El tipo de documento debe ser válido para el país.
• Cuenta duplicada: No se permite registrar la misma cuenta (mismo número, documento, titular, tipo, país) dos veces.
• USA: Para country_registered: "US" son obligatorios wire, routing_number, address y nickname.

Respuesta exitosa (200)

{
  "code_transaction": "OK",
  "data": {
    "id": 85,
    "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",
    "wire": null,
    "routing_number": null,
    "address": null,
    "nickname": "Cuenta Principal"
  }
}

Errores posibles

Listar cuentas bancarias del usuario

Lista las cuentas bancarias registradas por el usuario, con filtro opcional por país.

Endpoint

GET /list_third_party_banks/?country=CO

Parámetros query

Headers

Authorization: Bearer [ACCESS_TOKEN]
x-api-key: [API_KEY]
Accept: application/json

Respuesta (200)

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

Estados de cuenta

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

Actualizar cuenta USD (cambiar nombre o desactivar)

Permite cambiar el alias (name) de la cuenta o desactivarla. No se puede desactivar y cambiar nombre en el mismo request.

Endpoint

PUT /api/v1/thirdpartybank/thirdpartybank

Headers

Authorization: Bearer [ACCESS_TOKEN]
x-api-key: [API_KEY]
Content-Type: application/json

Request

Reglas: En un mismo request solo se envía o bien name o bien status=DEACTIVATED, no ambos. El name debe ser único entre las cuentas del usuario.

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

{
"bank_account_id": "account_abc123",
"status": "DEACTIVATED"
}

curl -X PUT "https://api.colurs.co/api/v1/thirdpartybank/thirdpartybank" \
  -H "Authorization: Bearer [TOKEN]" \
  -H "x-api-key: [API_KEY]" \
  -H "Content-Type: application/json" \
  -d '{"bank_account_id": "account_abc123", "name": "Mi Cuenta Principal USD"}'

Respuesta exitosa (200)

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

Al desactivar (status: DEACTIVATED), el sistema actualiza el estado local y elimina la cuenta en el proveedor; la cuenta deja de aparecer en el listado.

Errores posibles

Listar cuentas USD

Devuelve las cuentas en USD del usuario. Las cuentas desactivadas no se incluyen.

Endpoint

GET /api/v1/usd/accounts

Headers

Authorization: Bearer [ACCESS_TOKEN]
x-api-key: [API_KEY]
Accept: application/json

Respuesta (200)

{
  "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 de cada cuenta como bank_account_id en el PUT para actualizar o desactivar.

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.