Saltar al contenido principal

​
¿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.
Cada cuenta está vinculada a un usuario específico y debe ser verificada antes de usar en transacciones.

​
Tipos de Cuenta

Cuentas Bancarias

PSE, SPEI, ACH, WireCuentas bancarias fiat tradicionales para recibir moneda local.Usar para: Off-ramps (cripto → fiat)

Billeteras Cripto

USDC/USDT en múltiples redesDirecciones de billetera blockchain para recibir criptomoneda.Usar para: On-ramps (fiat → cripto)

​
Inicio Rápido

1

Crear Usuario

Los usuarios deben existir antes de agregar cuentas
POST /api/v2/users
2

Elegir Tipo de Cuenta

Cuenta bancaria para off-ramps, billetera para on-ramps
3

Crear Cuenta

Enviar detalles de la cuenta
POST /api/v2/accounts
4

Esperar Verificación

El estado de la cuenta cambia a ACTIVE después de verificación
5

Usar en Ramps

Referenciar ID de cuenta al crear ramps

​
Creando Cuentas

​
Ejemplo de Cuenta Bancaria

{
  "type": "PSE",
  "userId": "4d23aa52-1b40-4584-a8ea-58aba6099c5c",
  "externalId": "bank-account-1",
  "data": {
    "firstName": "Juan",
    "lastName": "García",
    "email": "[email protected]",
    "phone": "+573001234567",
    "accountNumber": "1234567890",
    "bankCode": "0001",
    "type": "savings",
    "countryCode": "CO",
    "document": {
      "type": "NUIP",
      "number": "1234567890",
      "issuedCountryCode": "CO"
    }
  }
}

​
Ejemplo de Cuenta de Billetera

{
  "type": "WALLET",
  "userId": "4d23aa52-1b40-4584-a8ea-58aba6099c5c",
  "externalId": "wallet-1",
  "data": {
    "firstName": "Juan",
    "lastName": "García",
    "email": "[email protected]",
    "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

GET /api/v2/accounts/userId/{userId}

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

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: 
PATCH /api/v2/accounts/{accountId}

{
  "type": "PSE",
  "data": {
    "accountNumber": "9876543210",
    "bankCode": "0002",
    "type": "checking"
  }
}
Actualizar ciertos campos puede requerir re-verificación y establecer el estado de la cuenta de vuelta a PENDING.

​
Eliminando Cuentas

DELETE /api/v2/accounts/{accountId}
Las cuentas usadas en ramps pendientes o en procesamiento no pueden eliminarse.

​
Mejores Prácticas

// 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 });

{
  "externalId": `${yourUserId}-wallet-polygon-usdc`,
  // Facilita búsquedas y previene duplicados
}

if (account.status === 'PENDING') {
  showMessage('Verificación de cuenta en progreso');
  // Verifica nuevamente en 1 hora o espera webhook
}

​
Próximos Pasos

Cuentas Bancarias

Configura cuentas bancarias para diferentes países

Billeteras Cripto

Configura cuentas de billetera de criptomoneda

Cuentas Pre-Fondeadas

Habilita liquidaciones instantáneas

Referencia API

Documentación completa de la API de Cuentas