Skip to Content
Conceptos ClaveCuentas Virtuales

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.

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

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.

{
  "pendingBalance": 50000,  // 50,000 COP pendiente
  "currencySymbol": "COP"
}

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.

{
  "reservedBalance": 25000,  // 25,000 COP reservado
  "currencySymbol": "COP"
}

Ejemplos:

  • Orden PAYOUT en progreso
  • BALANCE_TRANSFER siendo ejecutado

Verificar Saldos

Obtener Todos los Saldos de un Comercio

async function getMerchantBalances(token, orgId, merchantId) {
  const response = await axios.get(
    `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/accounts/balances`,
    {
      headers: { 'Authorization': `Bearer ${token}` }
    }
  );
  
  return response.data;
}
 
// Uso
const balances = await getMerchantBalances(token, orgId, merchantId);
 
balances.forEach(balance => {
  console.log(`${balance.currencySymbol}: ${balance.availableBalance} disponible`);
});
def get_merchant_balances(token, org_id, merchant_id):
    response = requests.get(
        f'https://api-sandbox.koywe.com/api/v1/organizations/{org_id}/merchants/{merchant_id}/accounts/balances',
        headers={'Authorization': f'Bearer {token}'}
    )
    
    return response.json()
 
# Uso
balances = get_merchant_balances(token, org_id, merchant_id)
 
for balance in balances:
    print(f"{balance['currencySymbol']}: {balance['availableBalance']} disponible")
curl -X GET 'https://api-sandbox.koywe.com/api/v1/organizations/TU_ORG_ID/merchants/TU_MERCHANT_ID/accounts/balances' \
  -H 'Authorization: Bearer TU_TOKEN'

Respuesta:

[
  {
    "id": "va_cop_12345",
    "currencySymbol": "COP",
    "availableBalance": 1000000,
    "pendingBalance": 50000,
    "reservedBalance": 25000,
    "totalBalance": 1075000,
    "merchantId": "mrc_xyz789"
  },
  {
    "id": "va_usd_67890",
    "currencySymbol": "USD",
    "availableBalance": 500,
    "pendingBalance": 0,
    "reservedBalance": 0,
    "totalBalance": 500,
    "merchantId": "mrc_xyz789"
  }
]

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)
// Cliente paga 50,000 COP
// Cuenta Virtual COP: +50,000
  1. Órdenes OFFRAMP (vender cripto)
// Vender 10 USDC por COP
// 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)
// Pagar proveedor 100,000 COP
// Cuenta Virtual COP: -100,000
  1. Órdenes BALANCE_TRANSFER (cambio de moneda)
// Convertir 1,000,000 COP a USD
// Cuenta Virtual COP: -1,000,000
// Cuenta Virtual USD: +1,250 (tasa ejemplo)
  1. Órdenes ONRAMP (comprar cripto)
// Comprar 10 USDC con COP
// 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:

async function safeCreatePayout(token, orgId, merchantId, payoutAmount, currency) {
  // 1. Obtener saldo actual
  const balance = await getBalanceForCurrency(token, orgId, merchantId, currency);
  
  // 2. Validar fondos suficientes
  if (balance.availableBalance < payoutAmount) {
    throw new Error(
      `Saldo insuficiente: ${balance.availableBalance} ${currency} disponible, ` +
      `${payoutAmount} ${currency} requerido`
    );
  }
  
  // 3. Crear orden de payout
  const order = await createPayoutOrder(token, orgId, merchantId, {
    amount: payoutAmount,
    currency: currency,
    // ... otros campos
  });
  
  return order;
}
 
// Uso
try {
  const payout = await safeCreatePayout(token, orgId, merchantId, 100000, 'COP');
  console.log('Payout creado:', payout.id);
} catch (error) {
  console.error('Error:', error.message);
}

Liquidación de Fondos y Tenencias a Largo Plazo

Liquidación Automática: Los fondos mantenidos en cuentas virtuales no pueden permanecer indefinidamente. Después de cierto número de días, los saldos se liquidan automáticamente a la cuenta bancaria registrada de tu comercio.

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)

Mantén Fondos a Largo Plazo: En lugar de esperar la liquidación automática, puedes convertir tu saldo fiat a USDC (dólares digitales) y mantener fondos en billeteras cripto integradas indefinidamente.

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

async function convertToUSDC(token, orgId, merchantId, amount, currency) {
  // 1. Obtener cotización para ONRAMP (fiat a cripto)
  const quote = await axios.post(
    `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/quotes`,
    {
      type: 'ONRAMP',
      originCurrencySymbol: currency,
      destinationCurrencySymbol: 'USDC',
      amountIn: amount
    },
    { headers: { 'Authorization': `Bearer ${token}` } }
  );
  
  console.log(`Convirtiendo ${amount} ${currency} → ${quote.data.amountOut} USDC`);
  
  // 2. Crear orden ONRAMP
  const order = await axios.post(
    `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/orders`,
    {
      type: 'ONRAMP',
      originCurrencySymbol: currency,
      destinationCurrencySymbol: 'USDC',
      amountIn: amount,
      quoteId: quote.data.id,
      cryptoWalletId: 'wallet_abc123'  // Tu billetera integrada
    },
    { headers: { 'Authorization': `Bearer ${token}` } }
  );
  
  return order.data;
}
 
// Uso: Convertir saldo COP a USDC
const usdcOrder = await convertToUSDC(token, orgId, merchantId, 1000000, 'COP');
console.log('Fondos ahora mantenidos como USDC en billetera:', usdcOrder.cryptoWalletId);
def convert_to_usdc(token, org_id, merchant_id, amount, currency):
    # Obtener cotización
    quote_response = requests.post(
        f'https://api-sandbox.koywe.com/api/v1/organizations/{org_id}/merchants/{merchant_id}/quotes',
        json={
            'type': 'ONRAMP',
            'originCurrencySymbol': currency,
            'destinationCurrencySymbol': 'USDC',
            'amountIn': amount
        },
        headers={'Authorization': f'Bearer {token}'}
    )
    quote = quote_response.json()
    
    print(f"Convirtiendo {amount} {currency} → {quote['amountOut']} USDC")
    
    # Crear orden ONRAMP
    order_response = requests.post(
        f'https://api-sandbox.koywe.com/api/v1/organizations/{org_id}/merchants/{merchant_id}/orders',
        json={
            'type': 'ONRAMP',
            'originCurrencySymbol': currency,
            'destinationCurrencySymbol': 'USDC',
            'amountIn': amount,
            'quoteId': quote['id'],
            'cryptoWalletId': 'wallet_abc123'
        },
        headers={'Authorization': f'Bearer {token}'}
    )
    
    return order_response.json()
 
# Uso
usdc_order = convert_to_usdc(token, org_id, merchant_id, 1000000, 'COP')
print(f"Fondos ahora mantenidos como USDC en billetera: {usdc_order['cryptoWalletId']}")

Convertir USDC de Vuelta a Fiat

Cuando necesites los fondos de vuelta en fiat:

async function convertUSDCToFiat(token, orgId, merchantId, usdcAmount, targetCurrency) {
  // 1. Obtener cotización para OFFRAMP (cripto a fiat)
  const quote = await axios.post(
    `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/quotes`,
    {
      type: 'OFFRAMP',
      originCurrencySymbol: 'USDC',
      destinationCurrencySymbol: targetCurrency,
      amountIn: usdcAmount
    },
    { headers: { 'Authorization': `Bearer ${token}` } }
  );
  
  // 2. Crear orden OFFRAMP
  const order = await axios.post(
    `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/orders`,
    {
      type: 'OFFRAMP',
      originCurrencySymbol: 'USDC',
      destinationCurrencySymbol: targetCurrency,
      amountIn: usdcAmount,
      quoteId: quote.data.id,
      cryptoWalletId: 'wallet_abc123'
    },
    { headers: { 'Authorization': `Bearer ${token}` } }
  );
  
  return order.data;
}
 
// Uso: Convertir USDC de vuelta a COP
const copOrder = await convertUSDCToFiat(token, orgId, merchantId, 250, 'COP');
console.log('USDC convertido de vuelta a COP en cuenta virtual');

Estrategia Recomendada:

  • Mantén fondos operacionales en cuentas virtuales para operaciones diarias de PAYIN/PAYOUT
  • Convierte saldos excedentes a USDC para tenencias a largo plazo
  • Convierte USDC de vuelta a fiat cuando necesites hacer grandes pagos o retiros

Á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:

MonedaSímboloRegión
Peso ColombianoCOPColombia
Real BrasileñoBRLBrasil
Peso MexicanoMXNMéxico
Peso ChilenoCLPChile
Peso ArgentinoARSArgentina
Sol PeruanoPENPerú
Dólar EstadounidenseUSDInternacional
EuroEURInternacional

Cambio de Moneda vía BALANCE_TRANSFER

Transfiere fondos entre monedas instantáneamente:

async function transferBetweenCurrencies(token, orgId, merchantId) {
  // 1. Obtener cotización
  const quote = await axios.post(
    `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/quotes`,
    {
      type: 'BALANCE_TRANSFER',
      originCurrencySymbol: 'COP',
      destinationCurrencySymbol: 'USD',
      amountIn: 1000000  // 1,000,000 COP
    },
    { headers: { 'Authorization': `Bearer ${token}` } }
  );
  
  console.log('Tasa de cambio:', quote.data.exchangeRate);
  console.log('Recibirás:', quote.data.amountOut, 'USD');
  
  // 2. Crear orden de transferencia
  const order = await axios.post(
    `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/orders`,
    {
      type: 'BALANCE_TRANSFER',
      originCurrencySymbol: 'COP',
      destinationCurrencySymbol: 'USD',
      amountIn: 1000000,
      quoteId: quote.data.id
    },
    { headers: { 'Authorization': `Bearer ${token}` } }
  );
  
  return order.data;
}

Aprende más sobre BALANCE_TRANSFER →

Mejores Prácticas

Gestión de Saldo

Haz:

  • Verifica saldos antes de crear órdenes PAYOUT
  • Monitorea saldos pendientes para pagos entrantes
  • Configura alertas para saldos bajos
  • Reconcilia regularmente con tu sistema contable

No hagas:

  • Asumir disponibilidad instantánea de fondos PAYIN (verifica el estado)
  • Crear órdenes PAYOUT que excedan el saldo disponible
  • Ignorar saldos reservados en tus cálculos

Estrategia de Moneda

Operaciones Multi-Moneda: Mantén saldos en las monedas en las que operas con más frecuencia para minimizar comisiones de conversión y exposición a tasas de cambio.

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

🧾Órdenes y Tipos de Orden

Aprende cómo las órdenes afectan los saldos de cuentas virtuales

🔄Transferencias de Saldo

Guía completa para cambio de moneda

💵Aceptar Pagos

Aprende cómo acreditar tus cuentas virtuales

💸Pagar Proveedores

Aprende cómo usar saldos de cuenta virtual para pagos

Last updated on
Organizaciones y ComerciosCuentas Externas del Comercio