Airtime Java Quickstart

This quick start will guide you through integrating Reloadly’s Airtime API into your Java application. Prerequisites needed for this guide are:

• The reader should have a decent understanding of Java.
• A Reloadly account – if you don’t have one, you can sign up here
• Next, you need to have funds in your test wallet. When you sign up, a certain amount of funds are automatically added to your test wallet. You can fund your live wallet by following the steps in the Wallet section

Sign in to retrieve your client_id and client_secret keys for test mode. You can get both keys by toggling from live to test mode on the sidebar and navigating to Developers > API settings

Get an access token

Reloadly issues access tokens (also called bearer tokens) that are used to authorize API requests. Using your test client_id and client_secret, make a request to Reloadly’s authorization URL to obtain the appropriate access token. You can get a test access token by making a request in your Java application like this

import org.apache.http.util.EntityUtils;
import org.apache.http.NameValuePair;
import org.apache.http.client.HttpClient;
import org.apache.http.client.entity.UrlEncodedFormEntity;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.impl.client.HttpClientBuilder;
import org.apache.http.message.BasicNameValuePair;
import org.apache.http.entity.StringEntity;
import org.json.JSONObject;
import org.json.JSONArray;
import java.util.ArrayList;
import java.util.List;
import org.apache.http.entity.mime.MultipartEntity;
import org.apache.http.entity.mime.content.StringBody;
 
public class App {
  public static void main(String[] args ) throws java.io.IOException {
    HttpClient httpClient = HttpClientBuilder.create().build();
 
    HttpPost request = new HttpPost("https://auth.reloadly.com/oauth/token");
    request.setHeader("Content-Type", "application/json");
    JSONObject payload = new JSONObject();
    payload.put("client_id", "qwcLzXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX");
    payload.put("client_secret", "7kscVxQZ32-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX");
    payload.put("grant_type", "client_credentials");
    payload.put("audience", "https://topups-sandbox.reloadly.com");
    request.setEntity(new StringEntity(payload.toString()));
    String response = EntityUtils.toString(httpClient.execute(request).getEntity());
 
    System.out.println(response);
  }
}

Production access tokens are valid for 60 days, test access tokens are only valid for 24 hours.

If your request is successful, you should get the following response.

{
    "access_token": "eyJraWQiOiI1N2JjZjNhNy01YmYwLTQ1M2QtODQ0Mi03ODhlMTA4OWI3MDIiLCJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiI2NzkzIiwiaXNzIjoiaHR0cHM6Ly9yZWxvYWRseS1zYW5kYm94LmF1dGgwLmNvbS8iLCJodHRwczovL3JlbG9hZGx5LmNvbS9zYW5kYm94Ijp0cnVlLCJodHRwczovL3JlbG9hZGx5LmNvbS9wcmVwYWlkVXNlcklkIjoiNjc5MyIsImd0eSI6ImNsaWVudC1jcmVkZW50aWFscyIsImF1ZCI6Imh0dHBzOi8vdG9wdXBzLWhzMjU2LXNhbmRib3gucmVsb2FkbHkuY29tIiwibmJmIjoxNjU0MDgzNjY3LCJhenAiOiI2NzkzIiwic2NvcGUiOiJzZW5kLXRvcHVwcyByZWFkLW9wZXJhdG9ycyByZWFkLXByb21vdGlvbnMgcmVhZC10b3B1cHMtaGlzdG9yeSByZWFkLXByZXBhaWQtYmFsYW5jZSByZWFkLXByZXBhaWQtY29tbWlzc2lvbnMiLCJleHAiOjE2NTQxNzAwNjcsImh0dHBzOi8vcmVsb2FkbHkuY29tL2p0aSI6IjYwMTY4ODNiLWYxYTgtNGJhMy1hNmM3LWIwNjBkNDRmN2EyMCIsImlhdCI6MTY1NDA4MzY2NywianRpIjoiZGUwNzRlM2QtM2JkYi00N2ExLTkzNDktZTk1YmZiNjZlNGVmIn0.ZXUzCYbCCTzpDMr5hP7YvgWYqniy9kBY0Y5vWS8wRrA",
    "scope": "developer",
    "expires_in": 86400,
    "token_type": "Bearer"
}

Make an airtime or data top-up

Now that you have an access token, you can make an airtime or data top-up with the Airtime API. You can find details for the operator of your choice on your Reloadly dashboard by navigating on the sidebar to the Pricing > Airtime section.

In the examples below, we are using a mobile number and an operator registered in the United Arab Emirates to show how making an airtime top-up works in a Java application.

import org.apache.http.util.EntityUtils;
import org.apache.http.NameValuePair;
import org.apache.http.client.HttpClient;
import org.apache.http.client.entity.UrlEncodedFormEntity;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.impl.client.HttpClientBuilder;
import org.apache.http.message.BasicNameValuePair;
import org.apache.http.entity.StringEntity;
import org.json.JSONObject;
import org.json.JSONArray;
import java.util.ArrayList;
import java.util.List;
import org.apache.http.entity.mime.MultipartEntity;
import org.apache.http.entity.mime.content.StringBody;
 
public class App {
  public static void main(String[] args ) throws java.io.IOException {
    HttpClient httpClient = HttpClientBuilder.create().build();
 
    HttpPost request = new HttpPost("https://topups-sandbox.reloadly.com/topups");
    request.setHeader("Content-Type", "application/json");
    request.setHeader("Authorization", "Bearer <YOUR_TOKEN_HERE>");
    JSONObject payload = new JSONObject();
    payload.put("operatorId", 1100);
    payload.put("amount", 832);
    payload.put("useLocalAmount", false);
    payload.put("customIdentifier", "airtime-top-up");
    payload.put("recipientEmail", "jeanb@reloadly.com");
    payload.put("recipientPhone", new JSONObject()
      .put("countryCode", "AE")
      .put("number", "0503971821")
    );
    payload.put("senderPhone", new JSONObject()
      .put("countryCode", "CA")
      .put("number", "11231231231")
    );
    request.setEntity(new StringEntity(payload.toString()));
    String response = EntityUtils.toString(httpClient.execute(request).getEntity());
 
    System.out.println(response);
  }
}

If your request is successful, you should receive a response from Reloadly

{
    "transactionId": 33469,
    "status": "SUCCESSFUL",
    "operatorTransactionId": null,
    "customIdentifier": "airtime-top-up",
    "recipientPhone": "971503971821",
    "recipientEmail": null,
    "senderPhone": "11231231231",
    "countryCode": "AE",
    "operatorId": 1100,
    "operatorName": "Etisalat United Arab Emirates",
    "discount": 41.6,
    "discountCurrencyCode": "NGN",
    "requestedAmount": 832,
    "requestedAmountCurrencyCode": "NGN",
    "deliveredAmount": 5.6,
    "deliveredAmountCurrencyCode": "AED",
    "transactionDate": "2022-06-06 10:57:48",
    "pinDetail": null,
    "balanceInfo": {
        "oldBalance": 809811.69103,
        "newBalance": 809021.29103,
        "cost": 790.4,
        "currencyCode": "NGN",
        "currencyName": "Nigerian Naira",
        "updatedAt": "2022-06-06 14:57:48"
    }
}

If you made it to this point, you have successfully made your first top-up in a Java application.