Conceptos Clave

Cuentas Externas del Comercio

Configuración de cuentas bancarias y billeteras cripto para recibir fondos

Cuentas Externas del Comercio

Configura las cuentas bancarias externas y billeteras cripto de tu comercio para recibir fondos de liquidaciones de cuenta virtual y compras de criptomonedas.

¿Qué son las Cuentas Externas del Comercio?

Las Cuentas Externas del Comercio son las cuentas bancarias y billeteras cripto propias de tu organización donde recibes fondos de las operaciones de Koywe.

Tipos de Cuentas Externas

Cuentas Bancarias Externas

Tus cuentas bancarias empresariales para recibir liquidaciones fiat y retiros

Billeteras Cripto Externas

Tus direcciones de billetera cripto para recibir criptomonedas de deals ONRAMP


Cuentas Bancarias Externas vs Cuentas Virtuales

Entendiendo la diferencia:

CaracterísticaCuenta VirtualCuenta Bancaria Externa
UbicaciónDentro de KoyweTu propio banco
PropósitoOperaciones y transaccionesDestino de liquidación final
ConfiguraciónAutomáticaConfiguración manual
UsoPAYINs, PAYOUTs, transferenciasRetiros, liquidaciones
MonedasMúltiples soportadasEspecíficas del banco
ComisionesNinguna para ops internasPuede tener comisiones de transferencia

Liquidación Automática: Los fondos en cuentas virtuales se liquidan automáticamente a tu cuenta bancaria externa registrada después de un período configurado (típicamente 1-7 días). También puedes solicitar retiros manualmente.


Configuración de Cuentas Bancarias Externas

Cuándo Necesitas una Cuenta Bancaria Externa

Requerido para:

  • Recibir liquidaciones automáticas de cuentas virtuales
  • Retirar fondos de saldos virtuales
  • Recibir pagos del comercio
  • Cumplimiento y verificación

Creando una Cuenta Bancaria Externa

Asociación Automática: Las cuentas bancarias se asocian automáticamente con la información comercial registrada de tu comercio. No es necesario enviar nombre del titular o números de documento - usamos la información ya en el sistema.

1async function addMerchantBankAccount(token, orgId, merchantId) {
2 const response = await axios.post(
3 `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/bank-accounts`,
4 {
5 country: 'CO',
6 currency: 'COP',
7 bankCode: 'BANCOLOMBIA',
8 accountNumber: '1234567890',
9 accountType: 'checking', // o 'savings'
10 isPrimary: true // Establecer como cuenta de liquidación predeterminada
11 },
12 { headers: { 'Authorization': `Bearer ${token}` } }
13 );
14
15 console.log('Cuenta bancaria agregada:', response.data.id);
16 console.log('Estado:', response.data.status); // "PENDING_VERIFICATION"
17
18 return response.data;
19}
20
21const bankAccount = await addMerchantBankAccount(token, orgId, merchantId);

Campos Requeridos por País

Flexibilidad del Código Bancario: Para la mayoría de los países, el código bancario puede deducirse del número de cuenta. Aún puedes proporcionarlo, pero la API validará contra el valor deducido. Para países donde es requerido, la validación asegura que el banco esté en la lista soportada.

Chile 🇨🇱

1{
2 country: 'CL',
3 currency: 'CLP',
4 bankCode: 'BANCO_CHILE', // Requerido: BANCO_CHILE, BCI, SANTANDER_CHILE, etc.
5 accountNumber: '12345678' // Requerido
6}

Validaciones: El código bancario debe estar en la lista de bancos válidos.


Colombia 🇨🇴

1{
2 country: 'CO',
3 currency: 'COP',
4 bankCode: 'BANCOLOMBIA', // Requerido: BANCOLOMBIA, DAVIVIENDA, BOGOTA, etc.
5 accountNumber: '1234567890', // Requerido
6 accountType: 'checking' // Requerido: 'checking' o 'savings'
7}

Validaciones: El tipo de cuenta debe ser soportado por el banco. Longitud del número de cuenta validada (mín/máx).


Brasil 🇧🇷

1{
2 country: 'BR',
3 currency: 'BRL',
4 accountNumber: '12345-6', // Requerido (O pixKey)
5 // bankCode: '001' // Opcional (deducido de accountNumber)
6}

Validaciones: Código bancario deducido del número de cuenta. PIX key puede usarse en lugar del número de cuenta.


México 🇲🇽

1{
2 country: 'MX',
3 currency: 'MXN',
4 accountNumber: '012345678901234567' // Requerido: CLABE (18 dígitos)
5 // bankCode: 'BBVA_MEXICO' // Opcional (deducido de accountNumber)
6}

Validaciones: Validación formato CLABE (18 dígitos). Validación dígito verificador. Banco deducido de CLABE.


Argentina 🇦🇷

1{
2 country: 'AR',
3 currency: 'ARS',
4 accountNumber: '0123456789012345678901', // Requerido: CVU o CBU o alias
5 // bankCode: 'BANCO_NACION' // Opcional (deducido de accountNumber)
6}

Validaciones: Validación formato CVU/CBU. Validación dígito verificador. Banco deducido del número de cuenta. Alias soportado.


Perú 🇵🇪

1{
2 country: 'PE',
3 currency: 'PEN',
4 accountNumber: '01234567890123456789', // Requerido: formato CCI
5 // bankCode: 'BCP' // Opcional (deducido de accountNumber)
6}

Validaciones: Validación formato CCI (20 dígitos). Banco deducido del número de cuenta.


Bolivia 🇧🇴

1{
2 country: 'BO',
3 currency: 'BOB',
4 accountNumber: '1234567890' // Requerido
5 // bankCode: 'BNB' // Opcional (deducido de accountNumber)
6}

Validaciones: Banco deducido del número de cuenta.


Estados Unidos 🇺🇸

1{
2 country: 'US',
3 currency: 'USD',
4 accountNumber: '123456789', // Requerido
5 routingNumber: '021000021' // Requerido
6 // bankCode: 'CHASE' // Opcional (deducido de routingNumber)
7}

Validaciones: Banco deducido del routing number. Banco genérico guardado si no se encuentra.

Proceso de Verificación

1

Cuenta Creada

La cuenta bancaria externa se crea con estado PENDING_VERIFICATION

2

Microdepósito Enviado (si es requerido)

Koywe puede enviar un pequeño depósito de prueba para verificar la propiedad de la cuenta

3

Verificación Completada

Verificas el monto del depósito o la cuenta se auto-verifica

4

Cuenta Activada

El estado cambia a VERIFIED y está lista para liquidaciones

Verificación Automática: La cuenta bancaria se vincula automáticamente con la información comercial registrada de tu comercio. Asegúrate de que tu perfil de comercio tenga el nombre legal correcto y el ID fiscal, ya que se usarán para la verificación de cuenta.

Listando Cuentas Bancarias del Comercio

Node.js
1async function getMerchantBankAccounts(token, orgId, merchantId) {
2 const response = await axios.get(
3 `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/bank-accounts`,
4 { headers: { 'Authorization': `Bearer ${token}` } }
5 );
6
7 console.log('Cuentas bancarias externas:');
8 response.data.forEach(account => {
9 console.log(`- ${account.currency}: ${account.bankCode} ****${account.accountNumber.slice(-4)}`);
10 console.log(` Primaria: ${account.isPrimary}, Estado: ${account.status}`);
11 });
12
13 return response.data;
14}
15
16const accounts = await getMerchantBankAccounts(token, orgId, merchantId);

Configuración de Billeteras Cripto Externas

Cuándo Necesitas una Billetera Cripto Externa

Requerido para:

  • Recibir criptomoneda de deals ONRAMP
  • Enviar cripto a tus propias soluciones de custodia
  • Tenencias cripto a largo plazo fuera de Koywe

Billeteras Integradas vs Externas: Koywe proporciona billeteras integradas automáticamente (vía endpoint /wallet). Las billeteras externas son TUS PROPIAS billeteras en dispositivos hardware, exchanges, u otras soluciones de custodia donde quieres recibir cripto.

Agregando una Billetera Cripto Externa

1async function addExternalCryptoWallet(token, orgId, merchantId, walletData) {
2 const response = await axios.post(
3 `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/external-wallets`,
4 {
5 name: walletData.name, // ej., "Billetera Ledger Empresa"
6 currency: walletData.currency, // USDC, USDT, BTC, ETH, etc.
7 network: walletData.network, // ETHEREUM, POLYGON, BITCOIN, etc.
8 address: walletData.address, // Tu dirección de billetera
9 isPrimary: walletData.isPrimary || false
10 },
11 { headers: { 'Authorization': `Bearer ${token}` } }
12 );
13
14 console.log('Billetera externa agregada:', response.data.id);
15 console.log('Dirección:', response.data.address);
16 console.log('Red:', response.data.network);
17
18 return response.data;
19}
20
21// Ejemplo: Agregar USDC en Ethereum
22const usdcWallet = await addExternalCryptoWallet(token, orgId, merchantId, {
23 name: 'Ledger Empresa - USDC',
24 currency: 'USDC',
25 network: 'ETHEREUM',
26 address: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb2',
27 isPrimary: true
28});
29
30console.log('Billetera USDC registrada para operaciones ONRAMP');

Redes y Monedas Soportadas

MonedaRedes SoportadasNotas
USDCEthereum, Polygon, BSCStablecoin más popular
USDTEthereum, Polygon, BSC, TronSoporte multi-cadena
ETHEthereumEthereum nativo
BTCBitcoinSolo Bitcoin mainnet
MATICPolygonPolygon nativo
BNBBSCBSC nativo

Coincidencia de Red Crítica: Al crear deals ONRAMP, el parámetro network debe coincidir con una de las redes de billeteras externas registradas. ¡Siempre verifica la red antes de enviar cripto!

Listando Billeteras Cripto Externas

Node.js
1async function getExternalWallets(token, orgId, merchantId) {
2 const response = await axios.get(
3 `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/external-wallets`,
4 { headers: { 'Authorization': `Bearer ${token}` } }
5 );
6
7 console.log('Billeteras cripto externas:');
8 response.data.forEach(wallet => {
9 console.log(`- ${wallet.currency} (${wallet.network})`);
10 console.log(` Dirección: ${wallet.address}`);
11 console.log(` Primaria: ${wallet.isPrimary}, Estado: ${wallet.status}`);
12 });
13
14 return response.data;
15}
16
17const wallets = await getExternalWallets(token, orgId, merchantId);

Usando Cuentas Externas en Operaciones

ONRAMP: Enviar Cripto a Billetera Externa

Al crear deals ONRAMP, especifica tu billetera externa como destino:

Node.js
1// 1. Obtener cotización
2const quote = await axios.post(
3 `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/quotes`,
4 {
5 type: 'ONRAMP',
6 originCurrencySymbol: 'COP',
7 destinationCurrencySymbol: 'USDC',
8 amountIn: 1000000, // 1M COP
9 network: 'ETHEREUM'
10 },
11 { headers: { 'Authorization': `Bearer ${token}` } }
12);
13
14// 2. Crear deal con billetera externa como destino
15const deal = await axios.post(
16 `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/deals`,
17 {
18 type: 'ONRAMP',
19 destinationAccountId: usdcWallet.id, // Tu ID de billetera externa
20 quoteId: quote.data.id
21 },
22 { headers: { 'Authorization': `Bearer ${token}` } }
23);
24
25console.log('Deal ONRAMP creado');
26console.log('Cripto se enviará a:', usdcWallet.address);
27console.log('Red:', usdcWallet.network);

Usar Integradas vs Externas: Para cripto operacional (trading frecuente, OFFRAMP), usa billeteras integradas. Para tenencias a largo plazo o requisitos específicos de custodia, usa billeteras externas.

Retiros: Mover Fondos a Cuenta Bancaria Externa

Solicita retiro de cuenta virtual a tu cuenta bancaria externa:

Node.js
1async function withdrawToExternalBank(token, orgId, merchantId, withdrawalData) {
2 // Verificar saldo de cuenta virtual primero
3 const balances = await axios.get(
4 `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/bank-accounts/balances`,
5 { headers: { 'Authorization': `Bearer ${token}` } }
6 );
7
8 const copBalance = balances.data.find(b => b.currencySymbol === 'COP');
9
10 if (copBalance.availableBalance < withdrawalData.amount) {
11 throw new Error('Saldo insuficiente para retiro');
12 }
13
14 // Crear orden de retiro
15 const withdrawal = await axios.post(
16 `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/withdrawals`,
17 {
18 currency: 'COP',
19 amount: withdrawalData.amount,
20 destinationAccountId: withdrawalData.bankAccountId, // Tu cuenta bancaria externa
21 description: 'Retiro a cuenta empresarial'
22 },
23 { headers: { 'Authorization': `Bearer ${token}` } }
24 );
25
26 console.log('Retiro iniciado:', withdrawal.data.id);
27 console.log('Monto:', withdrawal.data.amount, 'COP');
28 console.log('Estado:', withdrawal.data.status); // "PROCESSING"
29 console.log('Tiempo estimado:', withdrawal.data.estimatedSettlement);
30
31 return withdrawal.data;
32}
33
34const withdrawal = await withdrawToExternalBank(token, orgId, merchantId, {
35 amount: 5000000, // 5M COP
36 bankAccountId: bankAccount.id
37});

Liquidaciones Automáticas: Si tienes liquidaciones automáticas habilitadas, los fondos se transferirán a tu cuenta bancaria externa primaria automáticamente después del período de retención configurado. Los retiros manuales te dan más control sobre el tiempo.


Mejores Prácticas

Seguridad

Verificar Direcciones

Siempre verifica dos veces las direcciones de billetera cripto antes de agregarlas. Los errores son irreversibles.

Usar Montos de Prueba

Envía transacciones de prueba pequeñas a nuevas billeteras externas antes de transferencias grandes.

Monitorear Webhooks

Configura webhooks para rastrear liquidaciones y retiros a cuentas externas.

Mantener Registros

Mantén registros de todas las cuentas externas para cumplimiento y auditoría.

Gestión de Cuentas

Hacer:

  • Mantener cuentas primarias actualizadas
  • Verificar nuevas cuentas inmediatamente
  • Usar billeteras separadas por red
  • Documentar propósitos de cuentas internamente

No hacer:

  • Compartir credenciales de cuenta
  • Usar direcciones de depósito de exchange como billeteras externas (usar direcciones de retiro)
  • Agregar billeteras no verificadas o de prueba en producción
  • Usar cuentas personales para operaciones comerciales

Patrones Comunes

Configuración Multi-Moneda

Para negocios que operan en múltiples países:

1// Configurar cuentas bancarias externas para cada moneda
2const copAccount = await axios.post(
3 `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/bank-accounts`,
4 {
5 country: 'CO',
6 currency: 'COP',
7 bankCode: 'BANCOLOMBIA',
8 accountNumber: '1234567890',
9 accountType: 'checking',
10 isPrimary: true
11 },
12 { headers: { 'Authorization': `Bearer ${token}` } }
13);
14
15const brlAccount = await axios.post(
16 `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/bank-accounts`,
17 {
18 country: 'BR',
19 currency: 'BRL',
20 accountNumber: '12345-6', // Banco deducido automáticamente
21 isPrimary: false
22 },
23 { headers: { 'Authorization': `Bearer ${token}` } }
24);
25
26const mxnAccount = await axios.post(
27 `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/bank-accounts`,
28 {
29 country: 'MX',
30 currency: 'MXN',
31 accountNumber: '012345678901234567', // CLABE - banco deducido
32 isPrimary: false
33 },
34 { headers: { 'Authorization': `Bearer ${token}` } }
35);
36
37console.log('Cuentas externas multi-moneda configuradas');
38console.log('Todas las cuentas auto-vinculadas a la información comercial del comercio');

Configuración Cripto Multi-Red

Para tenencias cripto diversificadas:

1// USDC en múltiples redes
2const usdcEthereum = await addExternalCryptoWallet(token, orgId, merchantId, {
3 name: 'USDC - Ethereum Principal',
4 currency: 'USDC',
5 network: 'ETHEREUM',
6 address: '0x...',
7 isPrimary: true
8});
9
10const usdcPolygon = await addExternalCryptoWallet(token, orgId, merchantId, {
11 name: 'USDC - Polygon Comisiones Bajas',
12 currency: 'USDC',
13 network: 'POLYGON',
14 address: '0x...',
15 isPrimary: false
16});
17
18// Diferentes stablecoins
19const usdtTron = await addExternalCryptoWallet(token, orgId, merchantId, {
20 name: 'USDT - Tron',
21 currency: 'USDT',
22 network: 'TRON',
23 address: 'T...',
24 isPrimary: false
25});
26
27console.log('Billeteras externas multi-red configuradas');

Próximos Pasos