> ## Documentation Index
> Fetch the complete documentation index at: https://docs.killb.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Cuentas

> Comprendiendo cuentas bancarias, billeteras cripto y cuentas pre-fondeadas

## ¿Qué es una Cuenta?

Una **Cuenta** en KillB representa un destino u origen de fondos en una transacción ramp. Las cuentas pueden ser cuentas bancarias, billeteras cripto o cuentas custodiales.

<Info>
  Los usuarios pueden tener múltiples cuentas de diferentes tipos. Cada cuenta está vinculada a un usuario específico.
</Info>

## Tipos de Cuenta

<Tabs>
  <Tab title="Cuentas Bancarias">
    Cuentas bancarias fiat tradicionales para recibir moneda local

    **Tipos:**

    * **PSE** - Cuentas bancarias colombianas
    * **SPEI** - Cuentas bancarias mexicanas (CLABE)
    * **ACH** - Cuentas bancarias de EE.UU.
    * **WIRE** - Transferencias wire internacionales
    * **TRANSFIYA** - Billeteras móviles colombianas

    **Casos de Uso:**

    * Destinos de off-ramp (cripto → fiat)
    * Recepción de moneda local
    * Retiros bancarios
  </Tab>

  <Tab title="Billeteras Cripto">
    Direcciones de billetera blockchain para recibir criptomoneda

    **Soportado:**

    * USDC en múltiples redes
    * USDT en múltiples redes
    * Polygon, Solana, Ethereum, Arbitrum, Tron, BSC

    **Casos de Uso:**

    * Destinos de on-ramp (fiat → cripto)
    * Recepción de stablecoins
    * Retiros cripto
  </Tab>

  <Tab title="Cuentas Custodiales">
    Cuentas gestionadas por KillB para programas de ahorros

    **Características:**

    * Denominadas en USD
    * Aseguradas por FDIC (a través de bancos asociados)
    * No se necesita gestión de billetera
    * Depósitos ACH/Wire

    **Casos de Uso:**

    * Cuentas de ahorro
    * Obtención de rendimiento
    * Custodia simplificada
  </Tab>
</Tabs>

## Estado de la Cuenta

| Estado     | Descripción                     | ¿Puede Transaccionar? |
| ---------- | ------------------------------- | --------------------- |
| `ACTIVE`   | Cuenta verificada y lista       | ✅ Sí                  |
| `PENDING`  | Esperando verificación          | ❌ No                  |
| `REJECTED` | Verificación fallida            | ❌ No                  |
| `INACTIVE` | Deshabilitada por usuario/admin | ❌ No                  |

## Creando Cuentas

### Cuenta PSE (Colombia)

Cuenta bancaria colombiana para recibir COP:

```json theme={null}
{
  "type": "PSE",
  "userId": "user-id-aqui",
  "externalId": "account-123",
  "data": {
    "firstName": "Juan",
    "lastName": "García",
    "email": "juan@example.com",
    "phone": "+573001234567",
    "accountNumber": "1234567890",
    "bankCode": "0001",
    "type": "savings",
    "countryCode": "CO",
    "document": {
      "type": "NUIP",
      "number": "1234567890",
      "issuedCountryCode": "CO"
    }
  }
}
```

### Cuenta SPEI (México)

Cuenta bancaria mexicana usando CLABE:

```json theme={null}
{
  "type": "SPEI",
  "userId": "user-id-aqui",
  "externalId": "account-456",
  "data": {
    "firstName": "María",
    "lastName": "López",
    "email": "maria@example.com",
    "phone": "+525512345678",
    "clabe": "012345678901234567",
    "clabeType": "CLABE",
    "countryCode": "MX",
    "document": {
      "type": "RFC",
      "number": "LOMM900515ABC",
      "issuedCountryCode": "MX"
    }
  }
}
```

<Tip>
  SPEI soporta tres tipos de CLABE: `CLABE` estándar de 18 dígitos, `DEBIT_CARD` de 16 dígitos o `PHONE_NUMBER` de 10 dígitos
</Tip>

### Cuenta de Billetera

Billetera cripto para recibir USDC/USDT:

```json theme={null}
{
  "type": "WALLET",
  "userId": "user-id-aqui",
  "externalId": "wallet-789",
  "data": {
    "firstName": "Juan",
    "lastName": "Pérez",
    "email": "juan@example.com",
    "phone": "+573001234567",
    "currency": "USDC",
    "network": "POLYGON",
    "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "countryCode": "CO",
    "document": {
      "type": "PASSPORT",
      "number": "AB123456",
      "issuedCountryCode": "CO"
    }
  }
}
```

### Cuenta ACH (EE.UU.)

Cuenta bancaria de EE.UU. para USD:

```json theme={null}
{
  "type": "ACH",
  "userId": "user-id-aqui",
  "externalId": "ach-001",
  "data": {
    "firstName": "Jane",
    "lastName": "Smith",
    "email": "jane@example.com",
    "phone": "+12125551234",
    "bankName": "Chase Bank",
    "routingNumber": "021000021",
    "accountNumber": "123456789",
    "type": "checking",
    "countryCode": "US",
    "document": {
      "type": "SSN",
      "number": "123-45-6789",
      "issuedCountryCode": "US"
    }
  }
}
```

## Validación de Cuenta

KillB valida cuentas antes de permitir transacciones:

### Validación de Cuenta Bancaria

* El código del banco existe en bancos soportados
* El formato del número de cuenta es correcto
* El número de routing es válido (para ACH/Wire)
* CLABE es formato válido de 18 dígitos (para SPEI)
* El nombre del titular de la cuenta coincide con el usuario

### Validación de Billetera

* La dirección es válida para la red especificada
* El checksum de la dirección es correcto (para chains EVM)
* La red es soportada para la moneda
* La dirección no es un contrato inteligente (a menos que se permita)

## Consultando Cuentas

### Obtener Todas las Cuentas del Usuario

```bash theme={null}
GET /api/v2/accounts/userId/{userId}
```

### Buscar Cuentas

```bash theme={null}
GET /api/v2/accounts?type=WALLET&userId=user-id
```

**Opciones de Filtro:**

* `ids` - IDs de cuenta específicos
* `userId` - Filtrar por usuario
* `type` - Tipo de cuenta
* `accountNumber` - Número de cuenta bancaria
* `address` - Dirección de billetera

## Actualizando Cuentas

Actualizar información de cuenta (campos limitados):

```bash theme={null}
PATCH /api/v2/accounts/{accountId}
```

**Campos Actualizables:**

* Información de documento
* Número CLABE (SPEI)
* Dirección de billetera
* Número de cuenta
* Código del banco

<Warning>
  Algunas actualizaciones pueden requerir re-verificación y establecer temporalmente el estado de la cuenta como PENDING.
</Warning>

## Eliminando Cuentas

```bash theme={null}
DELETE /api/v2/accounts/{accountId}
```

<Note>
  Las cuentas usadas en ramps pendientes o en procesamiento no pueden ser eliminadas hasta que esas transacciones se completen.
</Note>

## Mejores Prácticas

<AccordionGroup>
  <Accordion title="Verificar Antes de Crear" icon="check-double">
    * Valida códigos bancarios usando el endpoint `/api/v2/banks`
    * Verifica el formato de la dirección de billetera en el cliente
    * Confirma que el usuario posee la cuenta
    * Prueba con una transacción pequeña primero
  </Accordion>

  <Accordion title="Usar IDs Externos" icon="hashtag">
    * Proporciona un `externalId` único para cada cuenta
    * Usa tu identificador de cuenta interno
    * Permite búsqueda fácil de cuenta
    * Previene cuentas duplicadas
  </Accordion>

  <Accordion title="Manejar Múltiples Cuentas" icon="layer-group">
    * Permite que los usuarios guarden múltiples cuentas
    * Deja que los usuarios establezcan cuentas predeterminadas/preferidas
    * Soporta cambio de cuenta
    * Muestra el estado de verificación de la cuenta
  </Accordion>

  <Accordion title="Seguridad" icon="lock">
    * Nunca almacenes detalles bancarios sensibles
    * Usa IDs de cuenta de KillB en tu base de datos
    * Implementa verificaciones de propiedad de cuenta
    * Valida el acceso a la cuenta en cada uso
  </Accordion>
</AccordionGroup>

## Próximos Pasos

<CardGroup cols={2}>
  <Card title="Guía de Gestión de Cuentas" icon="folder-open" href="/es/guides/accounts/overview">
    Guía completa para gestionar cuentas
  </Card>

  <Card title="Configuración de Cuentas Bancarias" icon="building-columns" href="/es/guides/accounts/bank-accounts">
    Configura cuentas bancarias para diferentes países
  </Card>

  <Card title="Billeteras Cripto" icon="wallet" href="/es/guides/accounts/crypto-wallets">
    Configura cuentas de billetera de criptomoneda
  </Card>

  <Card title="Cuentas Pre-Fondeadas" icon="bolt" href="/es/concepts/pre-funded-accounts">
    Aprende sobre ejecución instantánea con liquidez pre-depositada
  </Card>

  <Card title="Referencia API" icon="code" href="/api-reference/endpoint/accounts-create">
    Ve la documentación de la API de Cuentas
  </Card>
</CardGroup>