Skip to Content
API ReferenceFX Rates

FX Rates API

Get foreign exchange rates for cross-currency transactions.

Get Exchange Rate

Retrieve the current exchange rate between two currencies.

GET /business/rate?from={fromCurrency}&to={toCurrency}

Query Parameters

ParameterTypeRequiredDescription
fromstringYesSource currency code (USD, KES, TZS, UGX, ZAR)
tostringYesTarget currency code (USD, KES, TZS, UGX, ZAR)

Example Request

curl "https://api.test.wakapay.io/business/rate?from=USD&to=KES" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
const params = new URLSearchParams({
  from: "USD",
  to: "KES",
});
 
const response = await fetch(
  `https://api.test.wakapay.io/business/rate?${params}`,
  {
    headers: { Authorization: `Bearer ${token}` },
  },
);
 
const data = await response.json();
console.log(data);
import requests
 
params = {
    'from': 'USD',
    'to': 'KES'
}
 
response = requests.get(
    'https://api.test.wakapay.io/business/rate',
    params=params,
    headers={'Authorization': f'Bearer {access_token}'}
)
 
rate = response.json()
print(rate)

Success Response

Status Code: 200 OK

{
  "from": "USD",
  "rate": 129,
  "to": "KES"
}

Response Fields

FieldTypeDescription
fromstringSource currency code
tostringTarget currency code
ratenumberExchange rate (1 from = rate × to)

Supported Currency Pairs

Test Environment

FromToRateStatus
USDKES129Configured

Note: In test environment, only USD→KES is configured. Querying other pairs will return a 404 error.

Production Environment

Contact your account manager to configure currency pairs for production.

Rate Updates

Exchange rates are updated:

  • Daily at 17:00 UTC
  • Rates remain fixed between updates
  • Based on official market rates

Error Responses

400 - Missing Parameters

Missing from or to parameter:

{
  "code": 0,
  "error": "from and to are required"
}

401 - Unauthorized

Missing or invalid authorization:

{
  "message": "missing value in request header"
}

404 - Rate Not Configured

The requested currency pair is not configured:

{
  "code": 0,
  "error": "rate USD_TZS not configured"
}

Note: Only USD → KES is configured in test environment.

Usage Examples

Check Rate Before Payout

Always get the current rate before initiating a cross-currency payout:

async function calculatePayout(fromCurrency, toCurrency, amount) {
  // Get current FX rate
  const rateResponse = await fetch(
    `https://api.test.wakapay.io/business/rate?from=${fromCurrency}&to=${toCurrency}`,
    {
      headers: { Authorization: `Bearer ${token}` },
    },
  );
 
  const rateData = await rateResponse.json();
 
  if (rateData.error) {
    throw new Error(`Rate not configured: ${rateData.error}`);
  }
 
  const { rate } = rateData;
  const convertedAmount = amount * rate;
 
  return {
    sendAmount: amount,
    sendCurrency: fromCurrency,
    receiveAmount: convertedAmount,
    receiveCurrency: toCurrency,
    rate: rate,
    display: `1 ${fromCurrency} = ${rate} ${toCurrency}`,
  };
}

Display Rate to User

async function showExchangeRate(from, to) {
  try {
    const response = await fetch(
      `https://api.test.wakapay.io/business/rate?from=${from}&to=${to}`,
      {
        headers: { Authorization: `Bearer ${token}` },
      },
    );
 
    const data = await response.json();
 
    if (data.error) {
      return `Rate ${from}→${to} not available`;
    }
 
    return `1 ${from} = ${data.rate} ${to}`;
  } catch (error) {
    console.error("Failed to get rate:", error);
    return "Rate unavailable";
  }
}

Handle Unconfigured Rates

async function sendCrossCurrencyPayout(params) {
  const { from, to, amount } = params;
 
  // Check if rate exists
  const rateResponse = await fetch(
    `https://api.test.wakapay.io/business/rate?from=${from}&to=${to}`,
    {
      headers: { Authorization: `Bearer ${token}` },
    },
  );
 
  if (rateResponse.status === 404) {
    throw new Error(
      `Currency pair ${from}→${to} is not configured. ` +
        `Please contact support to enable this currency pair.`,
    );
  }
 
  const { rate } = await rateResponse.json();
 
  // Proceed with payout using the rate
  // ...
}

Calculation Example

If you want to send 100 KES to a recipient:

  1. Get the rate: USD → KES = 129
  2. Calculate USD needed: 100 KES ÷ 129 = 0.7752 USD
  3. Add fees: 0.7752 USD × 1.02 (2% fee) = 0.7907 USD total

Example from real transaction:

{
  "senderAmount": 0.7751937984496124,
  "senderCurrency": "USD",
  "receiverAmount": 100,
  "receiverCurrency": "KES",
  "totalDebited": 0.7906976744186047
}

Best Practices

  • Check availability: Always verify the currency pair is configured before attempting payouts
  • Cache rates: Rates update daily at 17:00 UTC, you can cache for up to 24 hours
  • Error handling: Handle 404 errors gracefully and inform users when pairs aren’t configured
  • Production setup: Request specific currency pairs from your account manager

Testing

Test Environment Currency Pairs

For testing, use the configured USD → KES pair:

# This works
curl "https://api.test.wakapay.io/business/rate?from=USD&to=KES" \
  -H "Authorization: Bearer YOUR_TOKEN"
Last updated on
Wallet & BalanceRecipient Verification