How to make a data top-up to an international phone number

Raphael Ugwu

July 12, 2022

6 min

Table of Contents

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 mostPopularLocalAmount property.
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 localFixedAmountsDescriptions object.

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

Resources

Reloadly Airtime API

Reloadly Developer Documentation

Raphael Ugwu

This might also interest you:

What is a Utility API? Benefits for Businesses and How to Integrate Them

Justin Calderon

9 min

With the right utility payment API, you can improve your profitability while helping customers pay their utility bills more conveniently.

Prepaid Card Fraud: How Your Business Can Resolve and Mitigate Malicious Activity

Justin Calderon

14 min

Prepaid card fraud is becoming more common, forcing both sellers and issuers to create strategies to better protect customers and users. Here’s how your business can better mitigate and prevent fraud.

How to Create Customized Visa Prepaid Cards in 6 Easy Steps

Justin Calderon

9 min

Creating white-label prepaid cards can help you reward employees, customers, and sales reps in a way that is also beneficial to your brand and business.

Content by developers to developers.

Subscribe to The Monthly Reload for Developers and start receiving all the developers’ updates.

The Monthly Reload: the newsletter for you

Subscribe to our Newsletter and don’t miss any news about our industry and products.

How to make a data top-up to an international phone number

Raphael Ugwu

Getting the operator details of the international mobile number

Making a data top-up to the international mobile number

Resources

Raphael Ugwu

This might also interest you:

What is a Utility API? Benefits for Businesses and How to Integrate Them

Justin Calderon

Prepaid Card Fraud: How Your Business Can Resolve and Mitigate Malicious Activity

Justin Calderon

How to Create Customized Visa Prepaid Cards in 6 Easy Steps

Justin Calderon

Content by developers to developers.

The Monthly Reload: the newsletter for you

It’s time to build, make your first API call today

Products

Pricing

Company

Developers

Social

Resources

Use Cases

Legal