Currency Conversion

Convert between different currencies in Paysera accounts with real-time exchange rates.

Feature Availability

This feature is not available by default and must be enabled for specific clients. Contact Paysera support and request the CLIENT_CONVERT_CURRENCY scope.

What is Currency Conversion?

Currency Conversion allows users to exchange money between different currencies within their Paysera accounts. The service provides:

• 💱 Real-time exchange rates
• 💰 Multi-currency support
• 🔒 Secure conversions
• 📊 Conversion history
• ⚡ Instant processing

---

Key Features

View Key Features

1. Calculate Before Converting

Preview conversion results before executing:

• Check current exchange rates
• Calculate exact amounts
• Estimate fees
• No commitment required

2. Execute Conversions

Perform actual currency exchanges:

• Convert between any supported currencies
• Set min/max limits for protection
• Get instant confirmation
• Track conversion history

3. Multi-Currency Accounts

Manage multiple currencies:

• Hold balances in different currencies
• Convert between account currencies
• Optimize for best rates

---

Required Scope

The scope you need depends on whether you're calculating or executing a conversion:

• Calculate a conversion - you only need the CLIENT_CONVERT_CURRENCY scope, granted to your client by Paysera support (see the Feature Availability note above).
• Convert currency via the wallet - you additionally need to extend your access token with the convert_currency scope, granted via an SMS request.

Extended Scope

convert_currency is an extended scope that requires SMS verification:

1. Initiate SMS code sending
2. User receives SMS with code
3. Provide code during token refresh
4. Scope is added to access token

Request Extended Scope

// 1. Request SMS code
await api.requestSMSCode({
    scope: 'convert_currency'
});

// 2. User receives code via SMS

// 3. Refresh token with code
const newToken = await api.refreshToken({
    scope: 'convert_currency',
    sms_code: userProvidedCode
});

---

How It Works

Conversion Flow

Step-by-Step Process

1. Calculate - Preview conversion result
2. Review - Check rate and amounts
3. Convert - Execute if acceptable
4. Verify - Confirm with SMS code
5. Complete - Receive confirmation

---

Advanced Topics

Supported Currencies

Common currencies supported:

• EUR (Euro)
• USD (US Dollar)
• GBP (British Pound)
• PLN (Polish Złoty)
• RON (Romanian Leu)
• BGN (Bulgarian Lev)
• And many more...

Check Available Currencies

Contact Paysera support for the complete list of supported currencies and current rates.

Exchange Rates

How Rates Are Determined

• Based on interbank rates
• Updated in real-time
• Include small service fee
• May vary per account type

Rate Examples

EUR → USD:

Amount: 100.00 EUR
Rate: 1.0850
Result: 108.50 USD

USD → EUR:

Amount: 100.00 USD
Rate: 0.9216
Result: 92.16 EUR

Rate Changes

Exchange rates fluctuate constantly. The rate shown during calculation may differ slightly when executing the conversion.

Conversion Limits

Different limits may apply:

Limit Type	Description
Daily Limit	Maximum amount per day
Monthly Limit	Maximum amount per month
Per Transaction	Maximum single conversion
Minimum Amount	Minimum conversion size

Custom Limits

Some accounts have custom conversion rates and limits. Contact support for details.

Quick Start Example

Basic Conversion Flow

import PayseraWalletClient from 'paysera-wallet-api';

const client = new PayseraWalletClient({
    accessToken: 'your_access_token_with_convert_currency_scope'
});

async function convertCurrency() {
    try {
        // 1. Calculate conversion
        const calculation = await client.calculateConversion({
            from_currency: 'EUR',
            to_currency: 'USD',
            from_amount_decimal: '100.00'
        });
        
        console.log(`Converting 100 EUR:`);
        console.log(`You will receive: ${calculation.to_amount_decimal} USD`);
        
        // 2. Execute conversion
        const conversion = await client.convertCurrency({
            from_currency: 'EUR',
            to_currency: 'USD',
            from_amount_decimal: '100.00',
            account_number: 'EVP1234567890',
            max_from_amount_decimal: '100.00' // Safety limit
        });
        
        console.log('✅ Conversion successful!');
        console.log(`Conversion ID: ${conversion.id}`);
        console.log(`Converted: ${conversion.from_amount_decimal} ${conversion.from_currency}`);
        console.log(`Received: ${conversion.to_amount_decimal} ${conversion.to_currency}`);
        
    } catch (error) {
        console.error('Conversion failed:', error.message);
    }
}

convertCurrency();

Error Handling

Common Errors

Error Code	Description	Solution
not_found	Account not found	Verify account number
no_rights	No conversion permissions	Check scope and permissions
not_enough_funds	Insufficient balance	Add funds or reduce amount
limits_exceeded	Conversion limits exceeded	Wait or contact support
expectation_failed	Rate changed significantly	Recalculate and try again

Error Example

try {
    await client.convertCurrency({...});
} catch (error) {
    switch (error.code) {
        case 'not_enough_funds':
            console.error('Insufficient balance');
            break;
            
        case 'expectation_failed':
            console.error('Exchange rate changed');
            // Recalculate and show new rate
            break;
            
        case 'limits_exceeded':
            console.error('Daily limit reached');
            break;
    }
}

Best Practices

1. Always Calculate First

// ✅ Good - calculate before converting
const preview = await api.calculateConversion({...});
console.log(`You will receive: ${preview.to_amount_decimal}`);

if (userAcceptsRate) {
    await api.convertCurrency({...});
}

// ❌ Bad - convert without showing user
await api.convertCurrency({...});

2. Use Safety Limits

// ✅ Good - protect against rate changes
await api.convertCurrency({
    from_currency: 'EUR',
    to_currency: 'USD',
    to_amount_decimal: '100.00',
    max_from_amount_decimal: '95.00', // Won't pay more than 95 EUR
    account_number: accountNumber
});

3. Handle Rate Changes

async function safeConversion(params) {
    const maxRetries = 3;
    
    for (let i = 0; i < maxRetries; i++) {
        try {
            const calc = await api.calculateConversion(params);
            const approved = await showRateToUser(calc);
            if (!approved) return null;
            
            return await api.convertCurrency({
                ...params,
                max_from_amount: calc.from_amount + 10 // 0.10 EUR buffer
            });
            
        } catch (error) {
            if (error.code === 'expectation_failed' && i < maxRetries - 1) {
                console.log('Rate changed, recalculating...');
                continue;
            }
            throw error;
        }
    }
}

4. Cache Account Info

const accountCache = new Map();

async function getAccountNumber(currency) {
    if (accountCache.has(currency)) {
        return accountCache.get(currency);
    }
    
    const account = await api.getAccountByCurrency(currency);
    accountCache.set(currency, account.number);
    return account.number;
}

Use Cases

1. Travel Money Exchange

Convert currency before traveling:

async function prepareForTravel(amount, fromCurrency, toCurrency) {
    const conversion = await api.convertCurrency({
        from_currency: fromCurrency,
        to_currency: toCurrency,
        from_amount_decimal: amount,
        account_number: await getAccountNumber(fromCurrency)
    });
    
    console.log(`✈️ Travel money ready!`);
    console.log(`Converted ${amount} ${fromCurrency} → ${conversion.to_amount_decimal} ${toCurrency}`);
}

2. Online Shopping

Convert for international purchases:

async function payInLocalCurrency(itemPrice, itemCurrency) {
    const calc = await api.calculateConversion({
        from_currency: 'EUR',
        to_currency: itemCurrency,
        to_amount_decimal: itemPrice
    });
    
    console.log(`Item costs ${itemPrice} ${itemCurrency}`);
    console.log(`You will pay ${calc.from_amount_decimal} EUR`);
    
    if (await userConfirms()) {
        await api.convertCurrency({...});
    }
}

3. Freelancer Payments

Convert received payments:

async function convertPayment(receivedAmount, receivedCurrency, preferredCurrency) {
    const conversion = await api.convertCurrency({
        from_currency: receivedCurrency,
        to_currency: preferredCurrency,
        from_amount_decimal: receivedAmount,
        account_number: await getAccountNumber(receivedCurrency)
    });
    
    console.log(`💰 Payment converted`);
    console.log(`${receivedAmount} ${receivedCurrency} → ${conversion.to_amount_decimal} ${preferredCurrency}`);
}

---

API Endpoints

Calculate Conversion

Preview conversion without executing:

GET /rest/v1/currency-conversion?from_currency=EUR&to_currency=USD&from_amount_decimal=100.00

Learn more →

Execute Conversion

Perform actual currency exchange:

POST /rest/v1/currency-conversion
Content-Type: application/json

{
    "from_currency": "EUR",
    "to_currency": "USD",
    "from_amount_decimal": "100.00",
    "account_number": "EVP1234567890"
}

Learn more →

---

Next Steps

1. Calculate Conversions - Preview exchange rates
2. Execute Conversions - Perform currency exchange
3. Authentication - Get access tokens
4. API Reference - Complete API docs

---

Need Help?

• API Support: tech_support@paysera.com
• Request Access: Contact support to enable currency conversion
• Rate Information: Check current rates in your Paysera account