Cuentas Virtuales

Las Cuentas Virtuales son cuentas de saldo multi-moneda que mantienen tus fondos dentro del sistema Koywe, permitiendo operaciones de pago sin problemas sin cuentas bancarias tradicionales.

¿Qué son las Cuentas Virtuales?

Una Cuenta Virtual es una cuenta de saldo en una moneda específica, similar a una cuenta bancaria pero existente dentro de la plataforma Koywe.

Características Clave

• Una por moneda por comercio: Cada comercio tiene una cuenta virtual para cada moneda con la que trabaja
• Creadas automáticamente: Generadas cuando creas un comercio
• Saldos en tiempo real: Actualizaciones instantáneas cuando ocurren transacciones
• Sin cuenta bancaria necesaria: Mantén fondos sin abrir múltiples cuentas bancarias
• Usadas para todas las operaciones: Origen y destino para PAYINs, PAYOUTs y transferencias

Cómo Funcionan las Cuentas Virtuales

Las cuentas virtuales sirven como:

• Cuentas receptoras para pagos de clientes (PAYIN)
• Cuentas de almacenamiento para fondos en múltiples monedas
• Cuentas de origen para pagos a proveedores (PAYOUT)
• Endpoints de transferencia para cambios de moneda (BALANCE_TRANSFER)
• Fuente de financiamiento para compras de cripto (ONRAMP)
• Destino para ventas de cripto (OFFRAMP)

Tipos de Saldo

Cada cuenta virtual rastrea tres tipos de saldos:

1. Saldo Disponible

La cantidad inmediatamente disponible para usar.

1
{
2
  "availableBalance": 1000000,  // 1,000,000 COP disponible
3
  "currencySymbol": "COP"
4
}

Puede usarse para:

• Crear órdenes PAYOUT
• BALANCE_TRANSFER a otras monedas
• Compras cripto ONRAMP

2. Saldo Pendiente

Fondos que están siendo procesados pero aún no están disponibles.

1
{
2
  "pendingBalance": 50000,  // 50,000 COP pendiente
3
  "currencySymbol": "COP"
4
}

Ejemplos:

• Pago de cliente siendo confirmado (PAYIN en estado PROCESSING)
• Venta de cripto siendo liquidada (OFFRAMP en PROCESSING)

3. Saldo Reservado

Fondos temporalmente bloqueados para operaciones en curso.

1
{
2
  "reservedBalance": 25000,  // 25,000 COP reservado
3
  "currencySymbol": "COP"
4
}

Ejemplos:

• Orden PAYOUT en progreso
• BALANCE_TRANSFER siendo ejecutado

Verificar Saldos

Obtener Todos los Saldos de un Comercio

1
async function getMerchantBalances(token, orgId, merchantId) {
2
  const response = await axios.get(
3
    `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/bank-accounts/balances`,
4
    {
5
      headers: { 'Authorization': `Bearer ${token}` }
6
    }
7
  );
8
  
9
  return response.data;
10
}
11
12
// Uso
13
const balances = await getMerchantBalances(token, orgId, merchantId);
14
15
balances.forEach(balance => {
16
  console.log(`${balance.currencySymbol}: ${balance.availableBalance} disponible`);
17
});

Respuesta:

1
[
2
  {
3
    "id": "va_cop_12345",
4
    "currencySymbol": "COP",
5
    "availableBalance": 1000000,
6
    "pendingBalance": 50000,
7
    "reservedBalance": 25000,
8
    "totalBalance": 1075000,
9
    "merchantId": "mrc_xyz789"
10
  },
11
  {
12
    "id": "va_usd_67890",
13
    "currencySymbol": "USD",
14
    "availableBalance": 500,
15
    "pendingBalance": 0,
16
    "reservedBalance": 0,
17
    "totalBalance": 500,
18
    "merchantId": "mrc_xyz789"
19
  }
20
]

Operaciones de Saldo

Acreditación (Agregar Fondos)

Los fondos se acreditan automáticamente a las cuentas virtuales a través de:

1. Órdenes PAYIN (pagos de clientes)

1
// Cliente paga 50,000 COP
2
// Cuenta Virtual COP: +50,000

2. Órdenes OFFRAMP (vender cripto)

1
// Vender 10 USDC por COP
2
// Cuenta Virtual COP: +8,000 (tasa ejemplo)

Débito (Retirar Fondos)

Los fondos se debitan automáticamente de las cuentas virtuales a través de:

1. Órdenes PAYOUT (pagos a proveedores)

1
// Pagar proveedor 100,000 COP
2
// Cuenta Virtual COP: -100,000

2. Órdenes BALANCE_TRANSFER (cambio de moneda)

1
// Convertir 1,000,000 COP a USD
2
// Cuenta Virtual COP: -1,000,000
3
// Cuenta Virtual USD: +1,250 (tasa ejemplo)

3. Órdenes ONRAMP (comprar cripto)

1
// Comprar 10 USDC con COP
2
// Cuenta Virtual COP: -8,000 (tasa ejemplo)

Validación de Saldo

Antes de Crear Órdenes PAYOUT

Siempre verifica el saldo disponible antes de crear un PAYOUT:

1
async function safeCreatePayout(token, orgId, merchantId, payoutAmount, currency) {
2
  // 1. Obtener saldo actual
3
  const balance = await getBalanceForCurrency(token, orgId, merchantId, currency);
4
  
5
  // 2. Validar fondos suficientes
6
  if (balance.availableBalance < payoutAmount) {
7
    throw new Error(
8
      `Saldo insuficiente: ${balance.availableBalance} ${currency} disponible, ` +
9
      `${payoutAmount} ${currency} requerido`
10
    );
11
  }
12
  
13
  // 3. Crear orden de payout
14
  const order = await createPayoutOrder(token, orgId, merchantId, {
15
    amount: payoutAmount,
16
    currency: currency,
17
    // ... otros campos
18
  });
19
  
20
  return order;
21
}
22
23
// Uso
24
try {
25
  const payout = await safeCreatePayout(token, orgId, merchantId, 100000, 'COP');
26
  console.log('Payout creado:', payout.id);
27
} catch (error) {
28
  console.error('Error:', error.message);
29
}

Liquidación de Fondos y Tenencias a Largo Plazo

Comportamiento de Liquidación

Las cuentas virtuales están diseñadas para operaciones de pago activas, no para almacenamiento de fondos a largo plazo:

Qué sucede durante la liquidación:

• Los fondos se transfieren a tu cuenta bancaria registrada del comercio
• El saldo de la cuenta virtual vuelve a cero
• Recibes una notificación sobre la liquidación
• El historial de transacciones se mantiene para reconciliación

Alternativa: Tenencias en Dólares Digitales (USDC)

Beneficios de Tenencias en USDC:

• ✅ Sin liquidación automática - mantén fondos el tiempo que necesites
• ✅ Valor estable - vinculado 1:1 al Dólar Estadounidense
• ✅ Liquidez instantánea - convierte de vuelta a fiat en cualquier momento
• ✅ Menores tarifas - transferencias basadas en blockchain
• ✅ Acceso global - usa a través de fronteras

Convertir Fiat a USDC

1
async function convertToUSDC(token, orgId, merchantId, amount, currency) {
2
  // 1. Obtener cotización para ONRAMP (fiat a cripto)
3
  const quote = await axios.post(
4
    `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/quotes`,
5
    {
6
      type: 'ONRAMP',
7
      originCurrencySymbol: currency,
8
      destinationCurrencySymbol: 'USDC',
9
      amountIn: amount
10
    },
11
    { headers: { 'Authorization': `Bearer ${token}` } }
12
  );
13
  
14
  console.log(`Convirtiendo ${amount} ${currency} → ${quote.data.amountOut} USDC`);
15
  
16
  // 2. Crear orden ONRAMP
17
  const order = await axios.post(
18
    `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/orders`,
19
    {
20
      type: 'ONRAMP',
21
      originCurrencySymbol: currency,
22
      destinationCurrencySymbol: 'USDC',
23
      amountIn: amount,
24
      quoteId: quote.data.id,
25
      cryptoWalletId: 'wallet_abc123'  // Tu billetera integrada
26
    },
27
    { headers: { 'Authorization': `Bearer ${token}` } }
28
  );
29
  
30
  return order.data;
31
}
32
33
// Uso: Convertir saldo COP a USDC
34
const usdcOrder = await convertToUSDC(token, orgId, merchantId, 1000000, 'COP');
35
console.log('Fondos ahora mantenidos como USDC en billetera:', usdcOrder.cryptoWalletId);

Convertir USDC de Vuelta a Fiat

Cuando necesites los fondos de vuelta en fiat:

1
async function convertUSDCToFiat(token, orgId, merchantId, usdcAmount, targetCurrency) {
2
  // 1. Obtener cotización para OFFRAMP (cripto a fiat)
3
  const quote = await axios.post(
4
    `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/quotes`,
5
    {
6
      type: 'OFFRAMP',
7
      originCurrencySymbol: 'USDC',
8
      destinationCurrencySymbol: targetCurrency,
9
      amountIn: usdcAmount
10
    },
11
    { headers: { 'Authorization': `Bearer ${token}` } }
12
  );
13
  
14
  // 2. Crear orden OFFRAMP
15
  const order = await axios.post(
16
    `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/orders`,
17
    {
18
      type: 'OFFRAMP',
19
      originCurrencySymbol: 'USDC',
20
      destinationCurrencySymbol: targetCurrency,
21
      amountIn: usdcAmount,
22
      quoteId: quote.data.id,
23
      cryptoWalletId: 'wallet_abc123'
24
    },
25
    { headers: { 'Authorization': `Bearer ${token}` } }
26
  );
27
  
28
  return order.data;
29
}
30
31
// Uso: Convertir USDC de vuelta a COP
32
const copOrder = await convertUSDCToFiat(token, orgId, merchantId, 250, 'COP');
33
console.log('USDC convertido de vuelta a COP en cuenta virtual');

Árbol de Decisión de Gestión de Fondos

Más información sobre ONRAMP (Comprar Cripto) →

Más información sobre OFFRAMP (Vender Cripto) →

Gestión Multi-Moneda

Monedas Soportadas

Las cuentas virtuales se crean automáticamente para:

Cambio de Moneda vía BALANCE_TRANSFER

Transfiere fondos entre monedas instantáneamente:

1
async function transferBetweenCurrencies(token, orgId, merchantId) {
2
  // 1. Obtener cotización
3
  const quote = await axios.post(
4
    `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/quotes`,
5
    {
6
      type: 'BALANCE_TRANSFER',
7
      originCurrencySymbol: 'COP',
8
      destinationCurrencySymbol: 'USD',
9
      amountIn: 1000000  // 1,000,000 COP
10
    },
11
    { headers: { 'Authorization': `Bearer ${token}` } }
12
  );
13
  
14
  console.log('Tasa de cambio:', quote.data.exchangeRate);
15
  console.log('Recibirás:', quote.data.amountOut, 'USD');
16
  
17
  // 2. Crear orden de transferencia
18
  const order = await axios.post(
19
    `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/orders`,
20
    {
21
      type: 'BALANCE_TRANSFER',
22
      originCurrencySymbol: 'COP',
23
      destinationCurrencySymbol: 'USD',
24
      amountIn: 1000000,
25
      quoteId: quote.data.id
26
    },
27
    { headers: { 'Authorization': `Bearer ${token}` } }
28
  );
29
  
30
  return order.data;
31
}

Aprende más sobre BALANCE_TRANSFER →

Mejores Prácticas

Gestión de Saldo

Estrategia de Moneda

Estrategia ejemplo:

• Operas principalmente en Colombia → Mantén la mayoría de fondos en COP
• Pagas proveedores internacionales → Mantén algo de saldo USD
• Ventas ocasionales en Brasil → Convierte BRL a COP según sea necesario

Escenarios Comunes

Escenario 1: Flujo de Pago de Cliente

1. Cliente inicia pago: 50,000 COP
2. Orden PAYIN creada: Estado PENDING
3. Cuenta Virtual COP: pendiente +50,000
4. Cliente completa pago
5. Estado de orden: PAID
6. Cuenta Virtual COP: disponible +50,000
7. Tu aplicación recibe webhook: order.completed

Escenario 2: Flujo de Pago a Proveedor

1. Verificar Cuenta Virtual USD: 500 disponible
2. Crear PAYOUT: 100 USD al proveedor
3. Cuenta Virtual USD: reservado +100, disponible -100
4. Transferencia bancaria iniciada
5. Banco confirma transferencia
6. Estado de orden: COMPLETED
7. Cuenta Virtual USD: reservado -100 (ahora solo 400 total)

Escenario 3: Cambio de Moneda

1. Cuenta Virtual COP: 1,000,000 disponible
2. Cuenta Virtual USD: 0 disponible
3. Crear BALANCE_TRANSFER: 1,000,000 COP → USD
4. Tasa de cambio: 4,000 COP por USD
5. Cuenta Virtual COP: -1,000,000
6. Cuenta Virtual USD: +250
7. Orden se completa instantáneamente

Próximos Pasos