How to confirm exchange rates when purchasing an international top-up with Reloadly

With Reloadly’s API, you can make an airtime or data top-up to a mobile number that is not registered in your home country. However, this feature requires that the funds used for the top-up are charged from your wallet.

The value of the funds in your wallet are set in your local currency. As global exchange rates constantly fluctuate, you need to be aware of the current exchange rate of a country when making a top-up to a mobile number registered in that country.

This guide will show you how to use Reloadly’s API in detecting the exchange rate applied to a mobile number registered in a different country from yours.

The objective of this guide can be achieved with the following steps:

• Getting your access token
• Getting the operator details of your international mobile number
• Getting the exchange rate details of your number’s operator

You can get your access token by following the steps in this quickstart.

Getting the operator details of your international mobile number

Let’s say your local country is Nigeria and you have an international number registered in the United Kingdom. The number is +447951631338. 
First you need to detect the operator of this number. You can do this by making a request to an endpoint that automatically detects operators. The cURL code sample below shows how you can achieve this:

curl -i -X GET \
  'https://topups.reloadly.com/operators/auto-detect/phone/447951631338/countries/GB’ \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

In the above example, a GET request has been made using the phone number and the ISO code of the country where the phone number is registered. If the request is successful, you should have a response similar to this:

{
  "id": 535,
  "operatorId": 535,
  "name": "EE PIN England",
  "bundle": false,
  "data": false,
  "pin": true,
  "supportsLocalAmounts": true,
  "supportsGeographicalRechargePlans": false,
  "denominationType": "FIXED",
  "senderCurrencyCode": "NGN",
  "senderCurrencySymbol": "?",
  "destinationCurrencyCode": "GBP",
  "destinationCurrencySymbol": "£",
  "commission": 2,
  "internationalDiscount": 2,
  "localDiscount": 0,
  "mostPopularAmount": 6398.39,
  "mostPopularLocalAmount": 30,
  "minAmount": null,
  "maxAmount": null,
  "localMinAmount": null,
  "localMaxAmount": null,
  "country": {
    "isoName": "GB",
    "name": "United Kingdom"
  },
  "fx": {
    "rate": 0.00156,
    "currencyCode": "GBP"
  },
  "logoUrls": [
    "https://s3.amazonaws.com/rld-operator/a4b08c21-08b3-42dc-9235-c3c7e0e967a9-size-2.png",
    "https://s3.amazonaws.com/rld-operator/a4b08c21-08b3-42dc-9235-c3c7e0e967a9-size-1.png",
    "https://s3.amazonaws.com/rld-operator/a4b08c21-08b3-42dc-9235-c3c7e0e967a9-size-3.png"
  ],
  "fixedAmounts": [
    3199.19,
    6398.39,
    9601.74,
    12800.94,
    19199.32
  ],
  "fixedAmountsDescriptions": {
    "3199.19": "5GBP Pin",
    "6398.39": "10GBP Pin",
    "9601.74": "15GBP Pin",
    "12800.94": "20GBP Pin",
    "19199.32": "30GBP Pin"
  },
  "localFixedAmounts": [
    5,
    10,
    15,
    20,
    30
  ],
  "localFixedAmountsDescriptions": {
    "5.00": "5GBP Pin",
    "10.00": "10GBP Pin",
    "15.00": "15GBP Pin",
    "20.00": "20GBP Pin",
    "30.00": "30GBP Pin"
  },
  "suggestedAmounts": [],
  "suggestedAmountsMap": {},
  "geographicalRechargePlans": [],
  "promotions": [],
  "status": "ACTIVE"
}

Getting the exchange rate details of your number’s operator

Now you’ve gotten the operator details, next is to get the exchange rate between the operator’s currency and the currency in your wallet. You can do this by making a request via the FX rate endpoint as shown in the cURL code sample below

curl -i -X POST \
  https://topups-sandbox.reloadly.com/operators/fx-rate \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "operatorId": 535,
    "amount": 1000
  }'

In the above code sample, a POST request has been made using the phone number’s operator ID and the local amount denomination you want to make a top-up in which is NGN in my case (remember in the initial example I’m located in Nigeria). If the request is successful, you should have a response similar to this:

{
  "id": 535,
  "name": "EE PIN England",
  "fxRate": 1.56242,
  "currencyCode": "GBP"
}

Thus the response above shows that a top-up of 1000 NGN from your wallet would be credited as 1.56242 GBP on an international number registered in the United Kingdom.

Resources

Reloadly Airtime API

Reloadly Developer Documentation