Reloadly’s Airtime API isn’t restricted to airtime top-ups; data bundles can also be sent as well. In this guide, you will learn how to use Reloadly’s API to send a data bundle to an international mobile number.
This guide can be broken down into the following steps
- Getting your access token
- Getting the operator details of the international mobile number
- Checking if the mobile number’s operator can make data top-ups
- Making a data top-up to the international mobile number
You can get your access token by following the steps in this quickstart.
Getting the operator details of the international mobile number
Suppose you have an international mobile number; +233 54 090 3921. You can make a quick Google search with the international dialing code (+233) and deduce that the number is registered in Ghana and that’s it. You have no idea what the number’s operator is. To find this out, you can make a request to Reloadly’s auto-detect endpoint using the number and Ghana’s two letter ISO code. The cURL code sample below shows how this can be done
curl -i -X GET \
'https://topups-sandbox.reloadly.com/operators/auto-detect/phone/233540903921/countries/GH'\
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>'
If this request is carried out successfully, you should receive a response similar to the data below
{
"id": 150,
"operatorId": 150,
"name": "MTN Ghana",
"bundle": false,
"data": false,
"pin": false,
"supportsLocalAmounts": true,
"supportsGeographicalRechargePlans": false,
"denominationType": "RANGE",
"senderCurrencyCode": "NGN",
"senderCurrencySymbol": "?",
"destinationCurrencyCode": "GHS",
"destinationCurrencySymbol": "GH?",
"commission": 1,
"internationalDiscount": 1,
"localDiscount": 0,
"mostPopularAmount": 6240,
"mostPopularLocalAmount": null,
"minAmount": 70.72,
"maxAmount": 33281,
"localMinAmount": 1,
"localMaxAmount": 500,
"country": {
"isoName": "GH",
"name": "Ghana"
},
"fx": {
"rate": 0.012,
"currencyCode": "GHS"
},
"logoUrls": [
"https://s3.amazonaws.com/rld-operator/47fdee6a-c4a1-41c0-963e-843cae07b0c9-size-3.png",
"https://s3.amazonaws.com/rld-operator/47fdee6a-c4a1-41c0-963e-843cae07b0c9-size-1.png",
"https://s3.amazonaws.com/rld-operator/47fdee6a-c4a1-41c0-963e-843cae07b0c9-size-2.png"
],
"fixedAmounts": [],
"fixedAmountsDescriptions": {},
"localFixedAmounts": [],
"localFixedAmountsDescriptions": {},
"suggestedAmounts": [
416,
2080,
4160,
6240,
8320,
10400,
12480,
14560,
16640,
18720,
20801,
22881,
24961,
27041,
29121,
31201,
33281
],
"suggestedAmountsMap": {},
"geographicalRechargePlans": [],
"promotions": [],
"status": "ACTIVE"
}
With the response received in the last section, it’s clear that the mobile number’s operator is MTN Ghana.
Reloadly has a different operator ID for making data top-ups to a mobile number. For instance, the operator ID you would use to purchase airtime is different from the operator ID would use in purchasing data – even if the operator is the same.
Thus to check if MTN Ghana can make data top-ups, we will make a request to Reloadly’s endpoint to view all the operators that can make data top-ups. For parameters, we’ll use Ghana’s two digit ISO code and a query parameter that specifies data top-ups. Below is a cURL code sample that shows how to do this
curl -i -X GET \
'https://topups-sandbox.reloadly.com/operators/countries/GH?includeData=true' \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>'
Once successful, the response to this request is similar to the data below
[
{
"id": 1109,
"operatorId": 1109,
"name": "Airtel-Tigo Ghana Data ",
"bundle": false,
"data": true,
"pin": false,
"supportsLocalAmounts": true,
"supportsGeographicalRechargePlans": false,
"denominationType": "FIXED",
"senderCurrencyCode": "NGN",
"senderCurrencySymbol": "?",
"destinationCurrencyCode": "GHS",
"destinationCurrencySymbol": "GH?",
"commission": 0,
"internationalDiscount": 0,
"localDiscount": 0,
"mostPopularAmount": 5200.25,
"mostPopularLocalAmount": 50,
"minAmount": null,
"maxAmount": null,
"localMinAmount": null,
"localMaxAmount": null,
"country": {
"isoName": "GH",
"name": "Ghana"
},
"fx": {
"rate": 0.0096,
"currencyCode": "GHS"
},
"logoUrls": [
"https://s3.amazonaws.com/rld-portal-avatar-prd/0c0d0d6c-2e48-499d-ab2e-87c6c7709f3e.png",
"https://s3.amazonaws.com/rld-portal-avatar-prd/475e3687-5361-49c8-9143-9e91978eeeb4.png",
"https://s3.amazonaws.com/rld-portal-avatar-prd/99b60abb-f35b-4bf4-8810-02bf9f8fc6c2.png"
],
"fixedAmounts": [
312.02,
520.03,
532.51,
624.03,
1040.05,
1560.08,
2080.1,
5200.25
],
"fixedAmountsDescriptions": {
"312.02": "1GB Plan Mobile Data",
"520.03": "1.1GB Mobile Data",
"532.51": "625MB Mobile Data",
"624.03": "2GB Plan Mobile Data\t",
"1040.05": "1.75GB Mobile Data\t",
"1560.08": "5.5GB Plan Mobile Data",
"2080.10": "4.65GB Mobile Data\t",
"5200.25": "11GB Mobile Data"
},
"localFixedAmounts": [
3,
5,
5.13,
6,
10,
15,
20,
50
],
"localFixedAmountsDescriptions": {
"3.00": "1GB Plan Mobile Data",
"5.00": "1.1GB Mobile Data",
"5.13": "625MB Mobile Data",
"6.00": "2GB Plan Mobile Data\t",
"10.00": "1.75GB Mobile Data\t",
"15.00": "5.5GB Plan Mobile Data",
"20.00": "4.65GB Mobile Data\t",
"50.00": "11GB Mobile Data"
},
"suggestedAmounts": [],
"suggestedAmountsMap": {},
"geographicalRechargePlans": [],
"promotions": [],
"status": "ACTIVE"
},
{
"id": 642,
"operatorId": 642,
"name": "Glo Ghana Data",
"bundle": false,
"data": true,
"pin": false,
"supportsLocalAmounts": true,
"supportsGeographicalRechargePlans": false,
"denominationType": "FIXED",
"senderCurrencyCode": "NGN",
"senderCurrencySymbol": "?",
"destinationCurrencyCode": "GHS",
"destinationCurrencySymbol": "GH?",
"commission": 0,
"internationalDiscount": 0,
"localDiscount": 0,
"mostPopularAmount": 24961.2,
"mostPopularLocalAmount": 300,
"minAmount": null,
"maxAmount": null,
"localMinAmount": null,
"localMaxAmount": null,
"country": {
"isoName": "GH",
"name": "Ghana"
},
"fx": {
"rate": 0.012,
"currencyCode": "GHS"
},
"logoUrls": [
"https://s3.amazonaws.com/rld-operator/607ef89f-9f39-47fe-abfd-4977aa8b60b3-size-1.png",
"https://s3.amazonaws.com/rld-operator/607ef89f-9f39-47fe-abfd-4977aa8b60b3-size-3.png",
"https://s3.amazonaws.com/rld-operator/607ef89f-9f39-47fe-abfd-4977aa8b60b3-size-2.png"
],
"fixedAmounts": [
83.2,
166.41,
416.02,
832.04,
1664.08,
3328.16,
4160.2,
4992.24,
6656.32,
8320.4,
12480.6,
24961.2
],
"fixedAmountsDescriptions": {
"83.20": "300MB Plan, Validity 2days.",
"166.41": "600MB Plan, Validity 4days.",
"416.02": "1.5GB Plan, Validity 10days.",
"832.04": "4GB Plan, Validity 7days.",
"1664.08": "4.2GB Plan, Validity 30days.",
"3328.16": "10GB, Validity 30days.",
"4160.20": "15GB Plan, Validity 30days.",
"4992.24": "20GB, Validity 30days.",
"6656.32": "30GB Plan, Validity 60days.",
"8320.40": "60GB, Validity 90days.",
"12480.60": "100GB, Validity 90days.",
"24961.20": "UNLIMITED Data, Validity 30days."
},
"localFixedAmounts": [
1,
2,
5,
10,
20,
40,
50,
60,
80,
100,
150,
300
],
"localFixedAmountsDescriptions": {
"1.00": "300MB Plan, Validity 2days.",
"2.00": "600MB Plan, Validity 4days.",
"5.00": "1.5GB Plan, Validity 10days.",
"10.00": "4GB Plan, Validity 7days.",
"20.00": "4.2GB Plan, Validity 30days.",
"40.00": "10GB, Validity 30days.",
"50.00": "15GB Plan, Validity 30days.",
"60.00": "20GB, Validity 30days.",
"80.00": "30GB Plan, Validity 60days.",
"100.00": "60GB, Validity 90days.",
"150.00": "100GB, Validity 90days.",
"300.00": "UNLIMITED Data, Validity 30days."
},
"suggestedAmounts": [],
"suggestedAmountsMap": {},
"geographicalRechargePlans": [],
"promotions": [],
"status": "ACTIVE"
},
{
"id": 643,
"operatorId": 643,
"name": "MTN Ghana Data",
"bundle": false,
"data": true,
"pin": false,
"supportsLocalAmounts": true,
"supportsGeographicalRechargePlans": false,
"denominationType": "FIXED",
"senderCurrencyCode": "NGN",
"senderCurrencySymbol": "?",
"destinationCurrencyCode": "GHS",
"destinationCurrencySymbol": "GH?",
"commission": 0,
"internationalDiscount": 0,
"localDiscount": 0,
"mostPopularAmount": 4160.2,
"mostPopularLocalAmount": 50,
"minAmount": null,
"maxAmount": null,
"localMinAmount": null,
"localMaxAmount": null,
"country": {
"isoName": "GH",
"name": "Ghana"
},
"fx": {
"rate": 0.012,
"currencyCode": "GHS"
},
"logoUrls": [
"https://s3.amazonaws.com/rld-operator/47fdee6a-c4a1-41c0-963e-843cae07b0c9-size-3.png",
"https://s3.amazonaws.com/rld-operator/47fdee6a-c4a1-41c0-963e-843cae07b0c9-size-1.png",
"https://s3.amazonaws.com/rld-operator/47fdee6a-c4a1-41c0-963e-843cae07b0c9-size-2.png"
],
"fixedAmounts": [
41.6,
83.2,
249.61,
416.02,
832.04,
1664.08,
2496.12,
3328.16,
4160.2
],
"fixedAmountsDescriptions": {
"41.60": "24.05MB Mobile Data",
"83.20": "96.15MB Social Media Mobile Data",
"249.61": "471.70MB Mobile Data Bundle",
"416.02": "917.43MB Video Bundle Mobile Data",
"832.04": "1.79GB Video Mobile Data1",
"1664.08": "2000MB Monthly Video Mobile Data\t",
"2496.12": "3500MB Monthly Video Mobile Data\t",
"3328.16": "5000MB Monthly Video Mobile Data\t",
"4160.20": "7000MB Monthly Video Mobile Data\t"
},
"localFixedAmounts": [
0.5,
1,
3,
5,
10,
20,
30,
40,
50
],
"localFixedAmountsDescriptions": {
"0.50": "24.05MB Mobile Data",
"1.00": "96.15MB Social Media Mobile Data",
"3.00": "471.70MB Mobile Data Bundle",
"5.00": "917.43MB Video Bundle Mobile Data",
"10.00": "1.79GB Video Mobile Data1",
"20.00": "2000MB Monthly Video Mobile Data\t",
"30.00": "3500MB Monthly Video Mobile Data\t",
"40.00": "5000MB Monthly Video Mobile Data\t",
"50.00": "7000MB Monthly Video Mobile Data\t"
},
"suggestedAmounts": [],
"suggestedAmountsMap": {},
"geographicalRechargePlans": [],
"promotions": [],
"status": "ACTIVE"
},
{
"id": 771,
"operatorId": 771,
"name": "Surfline Ghana Data",
"bundle": false,
"data": true,
"pin": false,
"supportsLocalAmounts": true,
"supportsGeographicalRechargePlans": false,
"denominationType": "FIXED",
"senderCurrencyCode": "NGN",
"senderCurrencySymbol": "?",
"destinationCurrencyCode": "GHS",
"destinationCurrencySymbol": "GH?",
"commission": 0,
"internationalDiscount": 0,
"localDiscount": 0,
"mostPopularAmount": 49839.2,
"mostPopularLocalAmount": 799,
"minAmount": null,
"maxAmount": null,
"localMinAmount": null,
"localMaxAmount": null,
"country": {
"isoName": "GH",
"name": "Ghana"
},
"fx": {
"rate": 0.012,
"currencyCode": "GHS"
},
"logoUrls": [
"https://s3.amazonaws.com/rld-operator/033167db-663e-4ca9-8934-183ac220fd95-size-3.png",
"https://s3.amazonaws.com/rld-operator/033167db-663e-4ca9-8934-183ac220fd95-size-2.png",
"https://s3.amazonaws.com/rld-operator/033167db-663e-4ca9-8934-183ac220fd95-size-1.png"
],
"fixedAmounts": [
832.04,
1664.08,
2912.14,
3328.16,
5824.28,
8320.4,
9152.44,
15392.74,
21217.02,
27041.3,
29953.44,
33198.4,
34113.64,
49839.2,
66480
],
"fixedAmountsDescriptions": {
"832.04": "1.5GB 24Hrs",
"1664.08": "3GB 3days",
"2912.14": "4.5GB 7days",
"3328.16": "6GB 30days",
"5824.28": "8GB 30days",
"8320.40": "15GB 30days",
"9152.44": "Unlimited Night 30days",
"15392.74": "30GB 30days",
"21217.02": "45GB 30days",
"27041.30": "75GB 45days",
"29953.44": "Unlimited 30days",
"33198.40": "Standard Unlimited 30days",
"34113.64": "100GB 60days",
"49839.20": "Super Unlimited 30days",
"66480.00": "Ultra Unlimited 30days"
},
"localFixedAmounts": [
10,
20,
35,
40,
70,
100,
110,
185,
255,
325,
360,
399,
410,
599,
799
],
"localFixedAmountsDescriptions": {
"10.00": "1.5GB 24Hrs",
"20.00": "3GB 3days",
"35.00": "4.5GB 7days",
"40.00": "6GB 30days",
"70.00": "8GB 30days",
"100.00": "15GB 30days",
"110.00": "Unlimited Night 30days",
"185.00": "30GB 30days",
"255.00": "45GB 30days",
"325.00": "75GB 45days",
"360.00": "Unlimited 30days",
"399.00": "Standard Unlimited 30days",
"410.00": "100GB 60days",
"599.00": "Super Unlimited 30days",
"799.00": "Ultra Unlimited 30days"
},
"suggestedAmounts": [],
"suggestedAmountsMap": {},
"geographicalRechargePlans": [],
"promotions": [],
"status": "ACTIVE"
},
{
"id": 770,
"operatorId": 770,
"name": "Vodafone Ghana Data",
"bundle": false,
"data": true,
"pin": false,
"supportsLocalAmounts": true,
"supportsGeographicalRechargePlans": false,
"denominationType": "FIXED",
"senderCurrencyCode": "NGN",
"senderCurrencySymbol": "?",
"destinationCurrencyCode": "GHS",
"destinationCurrencySymbol": "GH?",
"commission": 0,
"internationalDiscount": 0,
"localDiscount": 0,
"mostPopularAmount": 4493.02,
"mostPopularLocalAmount": 54,
"minAmount": null,
"maxAmount": null,
"localMinAmount": null,
"localMaxAmount": null,
"country": {
"isoName": "GH",
"name": "Ghana"
},
"fx": {
"rate": 0.012,
"currencyCode": "GHS"
},
"logoUrls": [
"https://s3.amazonaws.com/rld-operator/9d8ea314-790c-4ba8-8220-8277fc6ead3c-size-3.png",
"https://s3.amazonaws.com/rld-operator/9d8ea314-790c-4ba8-8220-8277fc6ead3c-size-2.png",
"https://s3.amazonaws.com/rld-operator/9d8ea314-790c-4ba8-8220-8277fc6ead3c-size-1.png"
],
"fixedAmounts": [
166.41,
894.44,
4493.02
],
"fixedAmountsDescriptions": {
"166.41": "Volume 122MB, BrowserDaily, Validity 3days.",
"894.44": "Volume 563MB, StarterMonthly, Validity 37days.",
"4493.02": "Volume 5767MB, StreamerWeekly, Validity 10days."
},
"localFixedAmounts": [
2,
10.75,
54
],
"localFixedAmountsDescriptions": {
"2.00": "Volume 122MB, BrowserDaily, Validity 3days.",
"10.75": "Volume 563MB, StarterMonthly, Validity 37days.",
"54.00": "Volume 5767MB, StreamerWeekly, Validity 10days."
},
"suggestedAmounts": [],
"suggestedAmountsMap": {},
"geographicalRechargePlans": [],
"promotions": [],
"status": "ACTIVE"
}
]
As can be seen, our response contains details of every operator in Ghana that can make data top-ups. Let’s note some points:
- MTN Ghana Data is in the list, with an operator ID of 643.
- The amount most MTN Ghana Data customers recharged is 50 GHS, as can be seen in the
mostPopularLocalAmountproperty. - A 50 GHS data top-up on MTN Ghana will provide 7000 MB video mobile data valid for a month as can be seen in the
localFixedAmountsDescriptionsobject.
The fixedAmounts and the localFixedAmounts objects are directly proportional. This means that the first value in the fixedAmounts object is the FX equivalent of the first value in the localFixedAmounts object (in the tutorial’s case, 41.6 NGN = 0.5 GHS)
Making a data top-up to the international mobile number
Now that we have all the details of MTN Ghana’s data operator, we can make a data top-up to the international mobile number. Let’s make a top-up request using MTN Ghana Data’s operator ID
curl -i -X POST \
https://topups-sandbox.reloadly.com/topups \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
-H 'Content-Type: application/json' \
-d '{
"operatorId": 643,
"amount": 4160,
"useLocalAmount": false,
"customIdentifier": "mtn-ghana-data-topup",
"recipientEmail": "anyone@email.com",
"recipientPhone": {
"countryCode": "GH",
"number": "233540903921"
},
"senderPhone": {
"countryCode": "CA",
"number": " 11231231231"
}
}'
In the example above, 4160 NGN is used as the amount because it is equal to 50 GHS as we noted in the last paragraph. Should this request be successful, you will get a response similar to what is below
{
"transactionId": 34953,
"status": "SUCCESSFUL",
"operatorTransactionId": null,
"customIdentifier": "mtn-ghana-data-topup",
"recipientPhone": "233540903921",
"recipientEmail": "anyone@email.com",
"senderPhone": "1231231231",
"countryCode": "GH",
"operatorId": 643,
"operatorName": "MTN Ghana Data",
"discount": 0,
"discountCurrencyCode": "NGN",
"requestedAmount": 4160,
"requestedAmountCurrencyCode": "NGN",
"deliveredAmount": 50,
"deliveredAmountCurrencyCode": "GHS",
"transactionDate": "2022-06-23 13:23:50",
"pinDetail": null,
"balanceInfo": {
"oldBalance": 809964.36995,
"newBalance": 805804.36995,
"cost": 4160,
"currencyCode": "NGN",
"currencyName": "Nigerian Naira",
"updatedAt": "2022-06-23 17:23:50"
}
}
