How to track the status of each top-up you make

Raphael Ugwu

July 12, 2022

3 min

Table of Contents

When working with top-ups, it’s important to know not only how to make a top-up, but also how to track its status in real time. Some operators may have connectivity issues or outages and when this happens, it’s important to know if the top-up you made was processed successfully, is queued or failed.

In this guide, you will learn how to determine the status of every top-up you make. This guide is broken down into the following steps:

Getting your access token
Getting the operator details for the mobile number you want to top-up
Making an asynchronous top-up
Tracking the status of your top-up

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

Getting the operator details of the mobile number you want to top-up.

Let’s say you want to make a top-up to a mobile number registered in Argentina +54 911 405 691 17. The first step is to get the operator which this number is registered to. You can do this by using the mobile number and Argentina’s two-letter ISO code to retrieve every detail of the number’s operator. Below is a code sample in cURL that shows how to achieve this

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

If successful, you should have a response similar to the JSON snippet below:

{
  "id": 17,
  "operatorId": 17,
  "name": "Personal Argentina",
  "bundle": false,
  "data": false,
  "pin": false,
  "supportsLocalAmounts": false,
  "supportsGeographicalRechargePlans": false,
  "denominationType": "RANGE",
  "senderCurrencyCode": "NGN",
  "senderCurrencySymbol": "?",
  "destinationCurrencyCode": "ARS",
  "destinationCurrencySymbol": "$",
  "commission": 8,
  "internationalDiscount": 8,
  "localDiscount": 0,
  "mostPopularAmount": 4160,
  "mostPopularLocalAmount": null,
  "minAmount": 416.02,
  "maxAmount": 5824,
  "localMinAmount": null,
  "localMaxAmount": null,
  "country": {
    "isoName": "AR",
    "name": "Argentina"
  },
  "fx": {
    "rate": 0.168,
    "currencyCode": "ARS"
  },
  "logoUrls": [
    "https://s3.amazonaws.com/rld-operator/51fb6a28-9274-4118-baaa-180297d9a0fc-size-1.png",
    "https://s3.amazonaws.com/rld-operator/51fb6a28-9274-4118-baaa-180297d9a0fc-size-3.png",
    "https://s3.amazonaws.com/rld-operator/51fb6a28-9274-4118-baaa-180297d9a0fc-size-2.png"
  ],
  "fixedAmounts": [],
  "fixedAmountsDescriptions": {},
  "localFixedAmounts": [],
  "localFixedAmountsDescriptions": {},
  "suggestedAmounts": [
    417,
    2080,
    4160
  ],
  "suggestedAmountsMap": {},
  "geographicalRechargePlans": [],
  "promotions": [],
  "status": "ACTIVE"
}

Making an asynchronous top-up

From the JSON response, we can see that the mobile number’s operator is Personal Argentina.

Once you are done with retrieving the operator details of the phone number, the next step is to make an asynchronous top-up using the phone number and the operator ID specified in the JSON response.

An asynchronous top-up (async top-up) performs the exact same action as a regular top-up. The only difference is that instead of the top-up details as a response, an async top-up returns a single transaction ID which can be used to track the status of the top-up

The cURL code snippet below shows how an async top-up request is made

curl -i -X POST \
  https://topups-sandbox.reloadly.com/topups-async \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "operatorId": 17,
    "amount": 417,
    "useLocalAmount": false,
    "customIdentifier": "This is example identifier 1390",
    "recipientEmail": "peter@nauta.com.cu",
    "recipientPhone": {
      "countryCode": "AR",
      "number": "91140569117"
    },
    "senderPhone": {
      "countryCode": "CA",
      "number": "11231231231"
    }
  }'

Once successful, the response below is gotten:

{
  "transactionId": 35059
}

Tracking the status of your top-up

Now you have a single translation ID for the top-up you made, you can then use this to track its status by making a request to an endpoint that monitors top-ups.

curl -i -X GET \
  https://topups-sandbox.reloadly.com/topups/35059/status \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Once, successful, this request shares a response that shows you everything you need to know about the top-up.

{
  "code": null,
  "message": null,
  "status": "SUCCESSFUL",
  "transaction": {
    "transactionId": 35059,
    "status": "SUCCESSFUL",
    "operatorTransactionId": null,
    "customIdentifier": "This is example identifier 1390",
    "recipientPhone": "5491140569117",
    "recipientEmail": "peter@nauta.com.cu",
    "senderPhone": "1231231231",
    "countryCode": "AR",
    "operatorId": 17,
    "operatorName": "Personal Argentina",
    "discount": 33.36,
    "discountCurrencyCode": "NGN",
    "requestedAmount": 417,
    "requestedAmountCurrencyCode": "NGN",
    "deliveredAmount": 107.4,
    "deliveredAmountCurrencyCode": "ARS",
    "transactionDate": "2022-06-27 11:01:49",
    "pinDetail": null,
    "balanceInfo": {
      "oldBalance": 805804.36995,
      "newBalance": 805420.72995,
      "cost": 383.64,
      "currencyCode": "NGN",
      "currencyName": "Nigerian Naira",
      "updatedAt": "2022-06-27 15:01:49"
    }
  }
}