EXCHANGE_RATE_GUIDE.md

Exchange Rate Management Guide

Overview

Paystack does NOT automatically adapt to exchange rate fluctuations. Paystack processes all payments in Naira (NGN) - the local currency. Exchange rate conversion is handled by our backend system.

Current Implementation

The system now uses dynamic exchange rates that automatically fetch the current NGN to USD rate from external APIs, with intelligent caching and fallback mechanisms.

How It Works

1. Exchange Rate Fetching

When a payment is processed, the system:

1. Checks cache (1-hour cache duration)
2. If cache expired or missing, fetches from external API
3. Falls back to fixed rate if APIs fail

2. Rate Sources (Priority Order)

1. ExchangeRate-API (Free, no API key needed)

   • URL: https://api.exchangerate-api.com/v4/latest/USD
   • Rate limit: Generous free tier
   • Reliability: High

2. CurrencyAPI (Free tier available)

   • Requires: CURRENCY_API_KEY environment variable
   • More reliable, better rate limits
   • Sign up at: https://currencyapi.com

3. Fixer.io (Paid, but very reliable)

   • Requires: FIXER_API_KEY environment variable
   • Best for production
   • Sign up at: https://fixer.io

4. Fallback Rate

   • Uses NGN_PER_USD from .env (default: 750)
   • Used when all APIs fail

Configuration

Basic Setup (No API Keys)

Works out of the box with ExchangeRate-API (free):

NGN_PER_USD=750  # Fallback rate if APIs fail

Recommended Setup (With API Keys)

For better reliability, add one or more API keys:

# Primary: CurrencyAPI (recommended)
CURRENCY_API_KEY=your_currencyapi_key_here

# Alternative: Fixer.io (if you have it)
FIXER_API_KEY=your_fixer_key_here

# Fallback (always required)
NGN_PER_USD=750

How Rates Are Used

Payment Flow

1. User funds wallet with 1000 NGN
2. System fetches current rate (e.g., 850 NGN/USD)
3. Converts to USD: 1000 / 850 = $1.18
4. Converts to points: $1.18 / $0.05 = 23.6 → 24 points

Rate Locking

• At payment initiation: Rate is calculated and stored in metadata
• At payment verification: Rate is recalculated (may differ slightly)
• Final rate: Uses the rate at verification time (more accurate)

Cache Management

Cache Duration

• 1 hour by default
• Prevents excessive API calls
• Balances accuracy vs. API rate limits

Cache Behavior

• Cache is checked before API calls
• Cache is updated after successful API fetch
• Cache is cleared on server restart

Manual Cache Clear

// In code
exchangeRateService.clearCache();

Rate Fluctuation Handling

Scenario 1: NGN Depreciates (Rate goes up)

• Example: 750 → 850 NGN/USD
• Impact: Users get fewer points for same NGN amount
• Example: 1000 NGN = 26 points (at 750) vs 23 points (at 850)

Scenario 2: NGN Appreciates (Rate goes down)

• Example: 750 → 650 NGN/USD
• Impact: Users get more points for same NGN amount
• Example: 1000 NGN = 26 points (at 750) vs 30 points (at 650)

Why This Matters

• Fixed rate (old): Always gives same points regardless of real exchange rate
• Dynamic rate (new): Adjusts automatically, keeps pricing accurate

Monitoring

Check Current Rate

const rate = await exchangeRateService.getNGNToUSDRate();
console.log('Current rate:', rate);

Log Rate in Transactions

Rates are stored in transaction metadata:

{
  "fx": 850,
  "pointValueUsd": 0.05,
  "amountInNaira": 1000,
  "amountInDollars": 1.18
}

Best Practices

1. Use Fallback Rate

Always set NGN_PER_USD in .env as a safety net:

NGN_PER_USD=750  # Update monthly or as needed

2. Monitor Rate Changes

• Check logs for rate fetching failures
• Update fallback rate quarterly
• Consider paid API for production

3. Handle Rate Discrepancies

• Small differences between initiation and verification are normal
• System uses verification-time rate (more accurate)
• Both rates stored in metadata for audit

4. Production Recommendations

• Use CurrencyAPI or Fixer.io for reliability
• Monitor API rate limits
• Set up alerts for API failures
• Update fallback rate monthly

Troubleshooting

APIs Failing

If all APIs fail:

1. Check internet connectivity
2. Verify API keys (if using)
3. Check rate limits
4. System automatically uses fallback rate

Rate Too High/Low

If rate seems incorrect:

1. Check cache (might be stale)
2. Verify API is working
3. Check fallback rate in .env
4. Clear cache and retry

Rate Not Updating

1. Check cache duration (1 hour default)
2. Restart server to clear cache
3. Verify API is returning fresh data

Alternative Approaches

Option 1: Fixed Rate (Old)

• Simple but inaccurate
• Requires manual updates
• Use if APIs are unreliable

Option 2: Dynamic Rate (Current)

• Automatic updates
• More accurate
• Requires API access

Option 3: Fixed at Payment Time

• Lock rate when payment initiated
• More predictable for users
• Requires storing rate in payment metadata

Option 4: Manual Update

• Admin updates rate daily/weekly
• Most control
• Requires admin interface

API Key Setup

CurrencyAPI (Recommended)

1. Sign up: https://currencyapi.com
2. Get free API key
3. Add to .env: CURRENCY_API_KEY=your_key

Fixer.io

1. Sign up: https://fixer.io
2. Choose plan (free tier available)
3. Add to .env: FIXER_API_KEY=your_key

Summary

✅ Paystack processes in NGN - no exchange rate handling
✅ Our system handles conversion - NGN → USD → Points
✅ Dynamic rates - automatically fetched from APIs
✅ Intelligent caching - 1-hour cache, prevents excessive calls
✅ Fallback protection - uses fixed rate if APIs fail
✅ Rate stored in metadata - for audit and transparency

The system now automatically adapts to exchange rate fluctuations while maintaining reliability through caching and fallback mechanisms.