GiftCards Java Quickstart

Use this quick start if you want to purchase or send a gift card code with Reloadly’s Gift card API using a Java application. Prerequisites needed for this guide are:

• The reader should have a decent understanding of Java.
• A Reloadly account. If you don’t already have one, follow the registration procedure.
• 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 the right parameters, 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 similar to the example below

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://giftcards-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 a gift card purchase

Now that you have an access token, you can purchase a gift card with the Gift Card API. You can find details for the gift card product of your choice on your Reloadly dashboard by navigating on the sidebar to the Pricing > Gift Card section.

In the examples below, we will show how purchasing a gift card works by ordering an Amazon gift card that is only eligible for use in the United States.

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://giftcards-sandbox.reloadly.com/orders");
    request.setHeader("Content-Type", "application/json");
    request.setHeader("Authorization", "Bearer <YOUR_TOKEN_HERE>");
    JSONObject payload = new JSONObject();
    payload.put("productId", 5);
    payload.put("countryCode", "US");
    payload.put("quantity", 1);
    payload.put("unitPrice", 5);
    payload.put("customIdentifier", "gift-card-amazon-order");
    payload.put("senderName", "John Doe");
    payload.put("recipientEmail", "anyone@email.com");
    payload.put("recipientPhoneDetails", new JSONObject()
      .put("countryCode", "US")
      .put("phoneNumber", "8579184613")
    );
    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": 3116,
    "amount": 3139.45,
    "discount": 25.65,
    "currencyCode": "NGN",
    "fee": 285.00,
    "smsFee": 4.45,
    "recipientEmail": "anyone@email.com",
    "recipientPhone": "18579184613",
    "customIdentifier": "gift-card-amazon-order",
    "status": "SUCCESSFUL",
    "transactionCreatedTime": "2022-06-10 08:06:04",
    "product": {
        "productId": 5,
        "productName": "Amazon US",
        "countryCode": "US",
        "quantity": 1,
        "unitPrice": 5,
        "totalPrice": 5,
        "currencyCode": "USD",
        "brand": {
            "brandId": 2,
            "brandName": "Amazon"
        }
    }
}

If you made it to this point, you have successfully purchased your first gift card in a Java application