Balance Transfers (Currency Exchange)

Transfer funds between different currency virtual accounts instantly.

What is BALANCE_TRANSFER?

BALANCE_TRANSFER allows you to convert funds from one currency to another within your virtual accounts - instantly and without external bank transfers.

Use cases:

Convert COP to USD for international payments
Rebalance currency holdings
Lock in favorable exchange rates
Prepare funds for specific currency payouts

How It Works

Drawing diagram…

Process:

Check source currency balance
Get exchange rate quote
Create BALANCE_TRANSFER order
Funds instantly transferred between accounts

Quick Example

JavaScript

// Convert 1,000,000 COP to USD
 
// 1. Get quote
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('Exchange rate:', quote.data.exchangeRate); // e.g., 4000 COP per USD
console.log('Will receive:', quote.data.finalAmountOut, 'USD'); // e.g., 248.75 USD
console.log('Fee:', quote.data.fee, 'COP'); // e.g., 5000 COP
 
// 2. Create transfer order
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  // Lock the rate
  },
  { headers: { 'Authorization': `Bearer ${token}` } }
);
 
console.log('Transfer completed:', order.data.status); // "COMPLETED"

Instant Settlement: BALANCE_TRANSFER orders complete immediately - no waiting for bank confirmations!

Step-by-Step Integration

Step 1: Check Source Balance

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('Insufficient COP balance');
}

Step 2: Get Exchange Rate Quote

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}` } }
);
 
// Show rate to user
console.log(`Rate: 1 USD = ${quote.data.exchangeRate} COP`);
console.log(`You'll receive: ${quote.data.finalAmountOut} USD`);
console.log(`Fee: ${quote.data.fee} COP`);
console.log(`Quote expires in: ${quote.data.validForSeconds} seconds`);

Step 3: Create Transfer Order

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,  // Use quote to lock rate
    externalId: `transfer-${Date.now()}`,
    description: 'COP to USD conversion'
  },
  { headers: { 'Authorization': `Bearer ${token}` } }
);
 
console.log('Status:', order.data.status); // "COMPLETED" (instant)

Step 4: Verify New Balances

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('COP balance:', copBalance.availableBalance); // Decreased
console.log('USD balance:', usdBalance.availableBalance); // Increased

Supported Currency Pairs

BALANCE_TRANSFER supports every combination of Koywe’s 8 core currencies:

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

Any of these can be the origin or the destination, in either direction — local currency to USD (COP → USD), USD to local currency (USD → BRL), or local currency to local currency (CLP → MXN). There are no restricted pairs.

Most common: Local currency ↔ USD

Complete Example

JavaScript

async function transferCurrency(fromCurrency, toCurrency, amount) {
  try {
    // 1. Authenticate
    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. Check source balance
    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(`Insufficient ${fromCurrency} balance`);
    }
    
    console.log(`✓ Sufficient balance: ${sourceBalance.availableBalance} ${fromCurrency}`);
    
    // 3. Get quote
    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(`✓ Quote received`);
    console.log(`  Rate: 1 ${toCurrency} = ${quote.exchangeRate} ${fromCurrency}`);
    console.log(`  Amount out: ${quote.finalAmountOut} ${toCurrency}`);
    console.log(`  Fee: ${quote.fee} ${fromCurrency}`);
    
    // 4. Create transfer
    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(`✓ Transfer completed instantly`);
    console.log(`  Order ID: ${order.id}`);
    console.log(`  Status: ${order.status}`);
    
    return {
      success: true,
      orderId: order.id,
      amountOut: quote.finalAmountOut,
      currency: toCurrency
    };
    
  } catch (error) {
    console.error('Transfer failed:', error.response?.data || error.message);
    throw error;
  }
}
 
// Usage
await transferCurrency('COP', 'USD', 1000000);

Next Steps

Quotes & Rates

Learn about exchange rates and quotes

Virtual Accounts

Understanding multi-currency balances

Testing

Test transfers in sandbox

API Reference

Complete API documentation