FX Rates API

Pata viwango vya ubadilishaji wa fedha kwa miamala ya sarafu mbalimbali.

Pata Kiwango cha Ubadilishaji

Pata kiwango cha ubadilishaji cha sasa kati ya sarafu mbili.


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

Vigezo vya Hoja (Query)

Kigezo	Aina	Inahitajika	Maelezo
`from`	string	Ndiyo	Msimbo wa sarafu ya chanzo (USD, KES, TZS, UGX, ZAR)
`to`	string	Ndiyo	Msimbo wa sarafu ya lengo (USD, KES, TZS, UGX, ZAR)

Mfano wa Ombi


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)

Jibu la Mafanikio

Msimbo wa Hali: 200 OK


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

Sehemu za Jibu

Sehemu	Aina	Maelezo
`from`	string	Msimbo wa sarafu ya chanzo
`to`	string	Msimbo wa sarafu ya lengo
`rate`	number	Kiwango cha ubadilishaji (1 from = rate × to)

Jozi za Sarafu Zinazoungwa Mkono

Mazingira ya Majaribio

Kutoka	Hadi	Kiwango	Hali
USD	KES	129	Imewekwa

Kumbuka: Katika mazingira ya majaribio, USD→KES tu ndio iliyowekwa. Kuuliza jozi nyingine kutarudisha kosa la 404.

Mazingira ya Uzalishaji

Wasiliana na meneja wako wa akaunti kuweka jozi za sarafu kwa uzalishaji.

Sasisho za Viwango

Viwango vya ubadilishaji vinasasishwa:

Kila siku saa 17:00 UTC
Viwango vinabaki vimewekwa kati ya sasisho
Vinatokana na viwango rasmi vya soko

Majibu ya Makosa

400 — Vigezo Vinakosekana

Kigezo cha from au to kinakosekana:


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

401 — Haijaidhinishwa

Authorization inakosekana au isiyo sahihi:


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

404 — Kiwango Hakijawekwa

Jozi ya sarafu iliyoombwa haijawekwa:


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

Kumbuka: USD → KES tu ndio iliyowekwa katika mazingira ya majaribio.

Mifano ya Matumizi

Angalia Kiwango Kabla ya Malipo ya Nje

Daima pata kiwango cha sasa kabla ya kuanzisha malipo ya nje ya sarafu mbalimbali:


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}`,
  };
}

Onyesha Kiwango kwa Mtumiaji


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";
  }
}

Shughulikia Viwango Visivyowekwa


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
  // ...
}

Mfano wa Hesabu

Ikiwa unataka kutuma 100 KES kwa mpokeaji:

Pata kiwango: USD → KES = 129
Hesabu USD inayohitajika: 100 KES ÷ 129 = 0.7752 USD
Ongeza ada: 0.7752 USD × 1.02 (ada ya 2%) = 0.7907 USD jumla

Mfano kutoka muamala halisi:


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

Mbinu Bora

Angalia upatikanaji: Daima thibitisha jozi ya sarafu imewekwa kabla ya kujaribu malipo ya nje
Hifadhi viwango: Viwango vinasasishwa kila siku saa 17:00 UTC, unaweza kuhifadhi hadi saa 24
Kushughulikia makosa: Shughulikia makosa ya 404 kwa unyeti na mjulishe watumiaji jozi zisipowekwa
Usanidi wa uzalishaji: Omba jozi maalum za sarafu kutoka kwa meneja wako wa akaunti

Majaribio

Jozi za Sarafu za Mazingira ya Majaribio

Kwa majaribio, tumia jozi iliyowekwa ya USD → KES:


# Hii inafanya kazi
curl "https://api.test.wakapay.io/business/rate?from=USD&to=KES" \
  -H "Authorization: Bearer YOUR_TOKEN"

Yanayohusiana

Payouts API — Tuma malipo ya sarafu mbalimbali
Wallet API — Angalia salio kabla ya ubadilishaji
Transactions API — Tazama historia ya ubadilishaji