> ## 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.

# Visión General de Cuentas

> Comprendiendo y gestionando cuentas de pago

## ¿Qué son las Cuentas?

Las cuentas representan destinos u orígenes de fondos en transacciones ramp. Los usuarios pueden tener múltiples cuentas de diferentes tipos para soportar varios métodos de pago y casos de uso.

<Info>
  Cada cuenta está vinculada a un usuario específico y debe ser verificada antes de usar en transacciones.
</Info>

## Tipos de Cuenta

<CardGroup cols={2}>
  <Card title="Cuentas Bancarias" icon="building-columns" href="/es/guides/accounts/bank-accounts">
    **PSE, SPEI, ACH, Wire**

    Cuentas bancarias fiat tradicionales para recibir moneda local.

    Usar para: Off-ramps (cripto → fiat)
  </Card>

  <Card title="Billeteras Cripto" icon="wallet" href="/es/guides/accounts/crypto-wallets">
    **USDC/USDT en múltiples redes**

    Direcciones de billetera blockchain para recibir criptomoneda.

    Usar para: On-ramps (fiat → cripto)
  </Card>
</CardGroup>

## Inicio Rápido

<Steps>
  <Step title="Crear Usuario">
    Los usuarios deben existir antes de agregar cuentas

    ```bash theme={null}
    POST /api/v2/users
    ```
  </Step>

  <Step title="Elegir Tipo de Cuenta">
    Cuenta bancaria para off-ramps, billetera para on-ramps
  </Step>

  <Step title="Crear Cuenta">
    Enviar detalles de la cuenta

    ```bash theme={null}
    POST /api/v2/accounts
    ```
  </Step>

  <Step title="Esperar Verificación">
    El estado de la cuenta cambia a ACTIVE después de verificación
  </Step>

  <Step title="Usar en Ramps">
    Referenciar ID de cuenta al crear ramps
  </Step>
</Steps>

## Creando Cuentas

### Ejemplo de Cuenta Bancaria

```json theme={null}
{
  "type": "PSE",
  "userId": "4d23aa52-1b40-4584-a8ea-58aba6099c5c",
  "externalId": "bank-account-1",
  "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"
    }
  }
}
```

### Ejemplo de Cuenta de Billetera

```json theme={null}
{
  "type": "WALLET",
  "userId": "4d23aa52-1b40-4584-a8ea-58aba6099c5c",
  "externalId": "wallet-1",
  "data": {
    "firstName": "Juan",
    "lastName": "García",
    "email": "juan@example.com",
    "phone": "+573001234567",
    "currency": "USDC",
    "network": "POLYGON",
    "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "countryCode": "CO",
    "document": {
      "type": "NUIP",
      "number": "1234567890",
      "issuedCountryCode": "CO"
    }
  }
}
```

## Consultando Cuentas

### Obtener Todas las Cuentas del Usuario

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

```javascript theme={null}
const getUserAccounts = async (userId) => {
  const response = await fetch(
    `https://sandbox.killb.app/api/v2/accounts/userId/${userId}`,
    {
      headers: { 'Authorization': `Bearer ${token}` }
    }
  );
  
  return await response.json();
};
```

### Buscar Cuentas

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

**Filtros:**

* `ids` - IDs de cuenta específicos (separados por coma)
* `userId` - Filtrar por usuario
* `type` - Tipo de cuenta
* `accountNumber` - Número de cuenta bancaria
* `address` - Dirección de billetera
* `limit`, `page` - Paginación

## Actualizando Cuentas

Campos limitados pueden actualizarse después de la creación:

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

<CodeGroup>
  ```json Actualizar Cuenta PSE theme={null}
  {
    "type": "PSE",
    "data": {
      "accountNumber": "9876543210",
      "bankCode": "0002",
      "type": "checking"
    }
  }
  ```

  ```json Actualizar Billetera theme={null}
  {
    "type": "WALLET",
    "data": {
      "address": "0xNUEVA_DIRECCION_AQUI",
      "network": "SOLANA"
    }
  }
  ```
</CodeGroup>

<Note>
  Actualizar ciertos campos puede requerir re-verificación y establecer el estado de la cuenta de vuelta a PENDING.
</Note>

## Eliminando Cuentas

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

<Warning>
  Las cuentas usadas en ramps pendientes o en procesamiento no pueden eliminarse.
</Warning>

## Mejores Prácticas

<AccordionGroup>
  <Accordion title="Validar Antes de Crear" icon="check-double">
    ```javascript theme={null}
    // Verificar si código del banco existe
    const banks = await getBanks('CO');
    const validBank = banks.find(b => b.code === bankCode);

    // Validar formato de dirección de billetera
    const isValidAddress = /^0x[a-fA-F0-9]{40}$/.test(address);

    // Verificar duplicados
    const existing = await findAccount({ userId, address });
    ```
  </Accordion>

  <Accordion title="Usar IDs Externos" icon="hashtag">
    ```javascript theme={null}
    {
      "externalId": `${yourUserId}-wallet-polygon-usdc`,
      // Facilita búsquedas y previene duplicados
    }
    ```
  </Accordion>

  <Accordion title="Manejar Retrasos de Verificación" icon="clock">
    ```javascript theme={null}
    if (account.status === 'PENDING') {
      showMessage('Verificación de cuenta en progreso');
      // Verifica nuevamente en 1 hora o espera webhook
    }
    ```
  </Accordion>
</AccordionGroup>

## Próximos Pasos

<CardGroup cols={2}>
  <Card title="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/guides/accounts/pre-fund-accounts">
    Habilita liquidaciones instantáneas
  </Card>

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