Saltar al contenido principal

​
¿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.
Los usuarios pueden tener múltiples cuentas de diferentes tipos. Cada cuenta está vinculada a un usuario específico.

​
Tipos de Cuenta

Cuentas bancarias fiat tradicionales para recibir moneda localTipos:
  • 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

​
Estado de la Cuenta

EstadoDescripción¿Puede Transaccionar?
ACTIVECuenta verificada y lista✅ Sí
PENDINGEsperando verificación❌ No
REJECTEDVerificación fallida❌ No
INACTIVEDeshabilitada por usuario/admin❌ No

​
Creando Cuentas

​
Cuenta PSE (Colombia)

Cuenta bancaria colombiana para recibir COP: 
{
  "type": "PSE",
  "userId": "user-id-aqui",
  "externalId": "account-123",
  "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"
    }
  }
}

​
Cuenta SPEI (México)

Cuenta bancaria mexicana usando CLABE: 
{
  "type": "SPEI",
  "userId": "user-id-aqui",
  "externalId": "account-456",
  "data": {
    "firstName": "María",
    "lastName": "López",
    "email": "[email protected]",
    "phone": "+525512345678",
    "clabe": "012345678901234567",
    "clabeType": "CLABE",
    "countryCode": "MX",
    "document": {
      "type": "RFC",
      "number": "LOMM900515ABC",
      "issuedCountryCode": "MX"
    }
  }
}
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

​
Cuenta de Billetera

Billetera cripto para recibir USDC/USDT: 
{
  "type": "WALLET",
  "userId": "user-id-aqui",
  "externalId": "wallet-789",
  "data": {
    "firstName": "Juan",
    "lastName": "Pérez",
    "email": "[email protected]",
    "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: 
{
  "type": "ACH",
  "userId": "user-id-aqui",
  "externalId": "ach-001",
  "data": {
    "firstName": "Jane",
    "lastName": "Smith",
    "email": "[email protected]",
    "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

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

​
Buscar Cuentas

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): 
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
Algunas actualizaciones pueden requerir re-verificación y establecer temporalmente el estado de la cuenta como PENDING.

​
Eliminando Cuentas

DELETE /api/v2/accounts/{accountId}
Las cuentas usadas en ramps pendientes o en procesamiento no pueden ser eliminadas hasta que esas transacciones se completen.

​
Mejores Prácticas

  • 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
  • Proporciona un externalId único para cada cuenta
  • Usa tu identificador de cuenta interno
  • Permite búsqueda fácil de cuenta
  • Previene cuentas duplicadas
  • 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
  • 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

​
Próximos Pasos

Guía de Gestión de Cuentas

Guía completa para gestionar cuentas

Configuración de Cuentas Bancarias

Configura cuentas bancarias para diferentes países

Billeteras Cripto

Configura cuentas de billetera de criptomoneda

Cuentas Pre-Fondeadas

Aprende sobre ejecución instantánea con liquidez pre-depositada

Referencia API

Ve la documentación de la API de Cuentas