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

Dibujando diagrama…

Proceso:

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

Ejemplo Rápido

JavaScript

// 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`,
  {
    orderType: 'BALANCE_TRANSFER', executable: true,
    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.finalAmountOut, 'USD'); // ej., 248.75 USD
console.log('Comisión:', quote.data.fee, '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

JavaScript

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

JavaScript

const quote = await axios.post(
  `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/quotes`,
  {
    orderType: 'BALANCE_TRANSFER', executable: true,
    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.finalAmountOut} USD`);
console.log(`Comisión: ${quote.data.fee} COP`);
console.log(`Cotización expira en: ${quote.data.validForSeconds} segundos`);

Paso 3: Crear Orden de Transferencia

JavaScript

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

JavaScript

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

BALANCE_TRANSFER soporta todas las combinaciones de las 8 monedas principales de Koywe:

ARS · BOB · BRL · CLP · COP · MXN · PEN · USD

Cualquiera de ellas puede ser origen o destino, en ambas direcciones: moneda local a USD (COP → USD), USD a moneda local (USD → BRL), o moneda local a moneda local (CLP → MXN). No hay pares restringidos.

Más común: Moneda local ↔ USD

Ejemplo Completo

JavaScript

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`,
      {
        orderType: 'BALANCE_TRANSFER', executable: true,
        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.finalAmountOut} ${toCurrency}`);
    console.log(`  Comisión: ${quote.fee} ${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.finalAmountOut,
      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