Skip to Content
Gestión de SaldosTransferencias

Transferencias de Saldo (Cambio de Moneda)

Transfiere fondos entre diferentes cuentas virtuales de moneda instantáneamente.

¿Qué es BALANCE_TRANSFER?

BALANCE_TRANSFER te permite convertir fondos de una moneda a otra dentro de tus cuentas virtuales - instantáneamente y sin transferencias bancarias externas.

Casos de uso:

  • Convertir COP a USD para pagos internacionales
  • Rebalancear tenencias de moneda
  • Fijar tasas de cambio favorables
  • Preparar fondos para payouts de moneda específica

Cómo Funciona

Proceso:

  1. Verificar saldo de moneda origen
  2. Obtener cotización de tasa de cambio
  3. Crear orden BALANCE_TRANSFER
  4. Fondos transferidos instantáneamente entre cuentas

Ejemplo Rápido

// Convertir 1,000,000 COP a USD
 
// 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
  },
  { headers: { 'Authorization': `Bearer ${token}` } }
);
 
console.log('Tasa de cambio:', quote.data.exchangeRate); // ej., 4000 COP por USD
console.log('Recibirás:', quote.data.amountOut, 'USD'); // ej., 248.75 USD
console.log('Comisión:', quote.data.koyweFee, 'COP'); // ej., 5000 COP
 
// 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  // Bloquear la tasa
  },
  { headers: { 'Authorization': `Bearer ${token}` } }
);
 
console.log('Transferencia completada:', order.data.status); // "COMPLETED"

Liquidación Instantánea: ¡Las órdenes BALANCE_TRANSFER se completan inmediatamente - sin esperar confirmaciones bancarias!

Integración Paso a Paso

Paso 1: Verificar Saldo Origen

const balances = await axios.get(
  `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/accounts/balances`,
  { headers: { 'Authorization': `Bearer ${token}` } }
);
 
const copBalance = balances.data.find(b => b.currencySymbol === 'COP');
 
if (copBalance.availableBalance < 1000000) {
  throw new Error('Saldo COP insuficiente');
}

Paso 2: Obtener Cotización de Tasa de Cambio

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
  },
  { headers: { 'Authorization': `Bearer ${token}` } }
);
 
// Mostrar tasa al usuario
console.log(`Tasa: 1 USD = ${quote.data.exchangeRate} COP`);
console.log(`Recibirás: ${quote.data.amountOut} USD`);
console.log(`Comisión: ${quote.data.koyweFee} COP`);
console.log(`Cotización expira en: ${quote.data.validFor} segundos`);

Paso 3: 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,  // Usar cotización para bloquear tasa
    externalId: `transfer-${Date.now()}`,
    description: 'Conversión COP a USD'
  },
  { headers: { 'Authorization': `Bearer ${token}` } }
);
 
console.log('Estado:', order.data.status); // "COMPLETED" (instantáneo)

Paso 4: Verificar Nuevos Saldos

const newBalances = await axios.get(
  `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/accounts/balances`,
  { headers: { 'Authorization': `Bearer ${token}` } }
);
 
const copBalance = newBalances.data.find(b => b.currencySymbol === 'COP');
const usdBalance = newBalances.data.find(b => b.currencySymbol === 'USD');
 
console.log('Saldo COP:', copBalance.availableBalance); // Disminuyó
console.log('Saldo USD:', usdBalance.availableBalance); // Aumentó

Pares de Moneda Soportados

DesdeHaciaCaso de Uso
COPUSDPagos internacionales
BRLUSDTransacciones transfronterizas
MXNUSDTenencias en dólares estadounidenses
CLPUSDCobertura de moneda
USDCOPOperaciones en moneda local
USDBRLOperaciones brasileñas

Más común: Moneda local ↔ USD

Ejemplo Completo

async function transferCurrency(fromCurrency, toCurrency, amount) {
  try {
    // 1. Autenticar
    const authResponse = await axios.post(
      'https://api-sandbox.koywe.com/api/v1/auth/sign-in',
      { apiKey: process.env.KOYWE_API_KEY, secret: process.env.KOYWE_SECRET }
    );
    const token = authResponse.data.token;
    
    // 2. Verificar saldo origen
    const balances = await axios.get(
      `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/accounts/balances`,
      { headers: { 'Authorization': `Bearer ${token}` } }
    );
    
    const sourceBalance = balances.data.find(b => b.currencySymbol === fromCurrency);
    
    if (!sourceBalance || sourceBalance.availableBalance < amount) {
      throw new Error(`Saldo ${fromCurrency} insuficiente`);
    }
    
    console.log(`✓ Saldo suficiente: ${sourceBalance.availableBalance} ${fromCurrency}`);
    
    // 3. Obtener cotización
    const quoteResponse = await axios.post(
      `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/quotes`,
      {
        type: 'BALANCE_TRANSFER',
        originCurrencySymbol: fromCurrency,
        destinationCurrencySymbol: toCurrency,
        amountIn: amount
      },
      { headers: { 'Authorization': `Bearer ${token}` } }
    );
    
    const quote = quoteResponse.data;
    console.log(`✓ Cotización recibida`);
    console.log(`  Tasa: 1 ${toCurrency} = ${quote.exchangeRate} ${fromCurrency}`);
    console.log(`  Monto salida: ${quote.amountOut} ${toCurrency}`);
    console.log(`  Comisión: ${quote.koyweFee} ${fromCurrency}`);
    
    // 4. Crear transferencia
    const orderResponse = await axios.post(
      `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/orders`,
      {
        type: 'BALANCE_TRANSFER',
        originCurrencySymbol: fromCurrency,
        destinationCurrencySymbol: toCurrency,
        amountIn: amount,
        quoteId: quote.id
      },
      { headers: { 'Authorization': `Bearer ${token}` } }
    );
    
    const order = orderResponse.data;
    console.log(`✓ Transferencia completada instantáneamente`);
    console.log(`  ID de Orden: ${order.id}`);
    console.log(`  Estado: ${order.status}`);
    
    return {
      success: true,
      orderId: order.id,
      amountOut: quote.amountOut,
      currency: toCurrency
    };
    
  } catch (error) {
    console.error('Transferencia fallida:', error.response?.data || error.message);
    throw error;
  }
}
 
// Uso
await transferCurrency('COP', 'USD', 1000000);

Próximos Pasos

📈Cotizaciones y Tasas

Aprende sobre tasas de cambio y cotizaciones

👛Cuentas Virtuales

Comprender saldos multi-moneda

🧪Pruebas

Probar transferencias en sandbox

📖Referencia API

Documentación completa de API

Last updated on
Guía de IntegraciónCuentas de Depósito