Skip to main content

Converting Funds to Supported Currency

Exchange money between different currencies in user's wallet.

Use Case Overview​

Allow users to convert funds between supported currencies with real-time exchange rates.

See Full Documentation

For complete API reference, see Currency Conversion section.

Quick Example​

async function convertCurrency(fromAmount, fromCurrency, toCurrency) {
    // 1. Calculate conversion
    const calc = await api.calculateConversion({
        amount_from: fromAmount * 100,
        currency_from: fromCurrency,
        currency_to: toCurrency
    });
    
    console.log(`Rate: ${calc.exchange_rate}`);
    console.log(`You'll receive: ${calc.amount_to_decimal} ${toCurrency}`);
    
    // 2. Execute conversion
    const result = await api.executeConversion({
        amount_from: fromAmount * 100,
        currency_from: fromCurrency,
        currency_to: toCurrency
    });
    
    return result;
}

// Usage
await convertCurrency(100, 'EUR', 'USD');
// €100 → $108.50 (example)

Implementation Steps​

1. Calculate Conversion

Get exchange rate and preview conversion:

POST /rest/v1/currency/calculate HTTP/1.1
Host: wallet.paysera.com
Content-Type: application/json
Authorization: MAC id="...", ...

{
  "amount_from": 10000,
  "currency_from": "EUR",
  "currency_to": "USD"
}

Response:

{
  "amount_from": 10000,
  "amount_from_decimal": "100.00",
  "currency_from": "EUR",
  "amount_to": 10850,
  "amount_to_decimal": "108.50",
  "currency_to": "USD",
  "exchange_rate": 1.085
}
2. Execute Conversion

Confirm and execute the conversion:

POST /rest/v1/currency/convert HTTP/1.1
Host: wallet.paysera.com
Content-Type: application/json
Authorization: MAC id="...", ...

{
  "amount_from": 10000,
  "currency_from": "EUR",
  "currency_to": "USD"
}

Complete Example​

class CurrencyConverter {
    async getRate(from, to) {
        const calc = await api.calculateConversion({
            amount_from: 100,
            currency_from: from,
            currency_to: to
        });
        return calc.exchange_rate;
    }
    
    async convert(amount, from, to, confirm = true) {
        // Calculate first
        const calculation = await api.calculateConversion({
            amount_from: amount * 100,
            currency_from: from,
            currency_to: to
        });
        
        console.log(`
            Converting: ${calculation.amount_from_decimal} ${from}
            You'll receive: ${calculation.amount_to_decimal} ${to}
            Rate: ${calculation.exchange_rate}
        `);
        
        if (!confirm) {
            return calculation;
        }
        
        // Execute conversion
        const result = await api.executeConversion({
            amount_from: amount * 100,
            currency_from: from,
            currency_to: to
        });
        
        console.log('✅ Conversion completed');
        return result;
    }
    
    async convertAll(from, to) {
        const balance = await api.getBalance(from);
        return await this.convert(balance.amount_decimal, from, to);
    }
}

// Usage
const converter = new CurrencyConverter();

// Get current rate
const rate = await converter.getRate('EUR', 'USD');
console.log(`1 EUR = ${rate} USD`);

// Convert specific amount
await converter.convert(100, 'EUR', 'USD');

// Convert all EUR to USD
await converter.convertAll('EUR', 'USD');

Common Use Cases​

Use Case 1: Multi-Currency Account
async function prepareCurrencyForPayment(amount, requiredCurrency) {
    const balance = await api.getBalance(requiredCurrency);
    
    if (balance.amount >= amount) {
        return { ready: true };
    }
    
    // Check other currencies
    const eurBalance = await api.getBalance('EUR');
    
    if (eurBalance.amount > 0) {
        await converter.convert(amount / 100, 'EUR', requiredCurrency);
        return { ready: true, converted: true };
    }
    
    return { ready: false, needsDeposit: true };
}
Use Case 2: Travel Money
async function prepareForTravel(destination, amount) {
    const currencies = {
        'USA': 'USD',
        'UK': 'GBP',
        'Japan': 'JPY'
    };
    
    const targetCurrency = currencies[destination];
    
    const result = await converter.convert(amount, 'EUR', targetCurrency);
    
    console.log(`✅ ${result.amount_to_decimal} ${targetCurrency} ready for ${destination}`);
}
Use Case 3: Best Rate Finder
async function findBestConversion(amount, fromCurrency, toCurrencies) {
    const rates = [];
    
    for (const toCurrency of toCurrencies) {
        const calc = await api.calculateConversion({
            amount_from: amount * 100,
            currency_from: fromCurrency,
            currency_to: toCurrency
        });
        
        rates.push({
            currency: toCurrency,
            amount: calc.amount_to_decimal,
            rate: calc.exchange_rate
        });
    }
    
    const best = rates.sort((a, b) => b.amount - a.amount)[0];
    
    console.log(`Best rate: ${fromCurrency} → ${best.currency} (${best.rate})`);
    return best;
}

// Usage
await findBestConversion(100, 'EUR', ['USD', 'GBP', 'CHF']);

Advanced Topics​

Best Practices

1. Always Calculate First

// ✅ Good - preview before executing
const preview = await api.calculateConversion({...});
if (userConfirms(preview)) {
    await api.executeConversion({...});
}

// ❌ Bad - execute without preview
await api.executeConversion({...});

2. Handle Rate Changes

async function convertWithRateCheck(amount, from, to, maxRate) {
    const calc = await api.calculateConversion({
        amount_from: amount * 100,
        currency_from: from,
        currency_to: to
    });
    
    if (calc.exchange_rate > maxRate) {
        throw new Error('Rate too high, wait for better rate');
    }
    
    return await api.executeConversion({
        amount_from: amount * 100,
        currency_from: from,
        currency_to: to
    });
}

3. Monitor Conversion History

async function trackConversions() {
    const history = await api.getTransactionHistory({
        type: 'currency_conversion',
        limit: 10
    });
    
    return history.map(tx => ({
        date: tx.created_at,
        from: `${tx.amount_from_decimal} ${tx.currency_from}`,
        to: `${tx.amount_to_decimal} ${tx.currency_to}`,
        rate: tx.exchange_rate
    }));
}
Error Handling

Insufficient Funds

try {
    await converter.convert(1000, 'EUR', 'USD');
} catch (error) {
    if (error.code === 'insufficient_funds') {
        console.log('Not enough EUR balance');
        // Redirect to upload funds
    }
}

Unsupported Currency

const SUPPORTED_CURRENCIES = ['EUR', 'USD', 'GBP', 'CHF', 'PLN'];

function validateCurrency(currency) {
    if (!SUPPORTED_CURRENCIES.includes(currency)) {
        throw new Error(`Currency ${currency} not supported`);
    }
}
Rate Monitoring
class RateMonitor {
    async watchRate(from, to, targetRate, callback) {
        const checkRate = async () => {
            const current = await converter.getRate(from, to);
            
            if (current >= targetRate) {
                callback(current);
                return true;
            }
            return false;
        };
        
        // Check every 5 minutes
        const interval = setInterval(async () => {
            const reached = await checkRate();
            if (reached) {
                clearInterval(interval);
            }
        }, 5 * 60 * 1000);
        
        await checkRate();
    }
}

// Usage
const monitor = new RateMonitor();
await monitor.watchRate('EUR', 'USD', 1.10, (rate) => {
    console.log(`Target rate reached: ${rate}`);
});
Testing
// Test conversion calculation
async function testCalculation() {
    const result = await api.calculateConversion({
        amount_from: 10000,
        currency_from: 'EUR',
        currency_to: 'USD'
    });
    
    console.assert(result.currency_from === 'EUR');
    console.assert(result.currency_to === 'USD');
    console.assert(result.exchange_rate > 0);
}

// Test conversion execution
async function testConversion() {
    const before = await api.getBalance('EUR');
    
    await api.executeConversion({
        amount_from: 1000,
        currency_from: 'EUR',
        currency_to: 'USD'
    });
    
    const after = await api.getBalance('EUR');
    console.assert(after.amount === before.amount - 1000);
}