1 of 32

ENG

Introduction

Making an airtime top-up comes in handy for different applications - personal and businesslike. Reloadly's Airtime API handles these use cases by providing endpoints that grant you access to over 700 operators in more than 140 countries. With this outreach, you can send airtime and also subscribe to data bundles in different currencies. The most important data you will need to send airtime successfully is the recipient's mobile number. To further learn how to integrate this RESTful API into your application, you can check out this documentation. It contains a reference of each endpoint in the Airtime API.

Quickstart

Authorization

On the dashboard, you can get your client credentials by navigating to the Developers > API settings section

Choose your environment

Client Credentials

Parameter

Description

client_id

This is a private identifier for your account

client_secret

This is a private key that should not be shared

Environments

Parameter

Description

Sandbox

Use endpoints in test mode and simulate real-like responses

Live

Work with live credentials to build applications

Get your access token

Once you have your client credentials, the next step is for you to retrieve your access token. Reloadly issues access tokens (also called bearer tokens) that are used to authorize API requests. Make a request to the https://auth.reloadly.com/oauth/token URL to obtain the appropriate access token

curl --location --request POST 'https://auth.reloadly.com/oauth/token' \
--header 'Content-Type: application/json' \
--data-raw '{
	"client_id":"YOUR_CLIENT_ID",
	"client_secret":"YOUR_CLIENT_SECRET",
	"grant_type":"client_credentials",
	"audience":"https://topups.reloadly.com"
}'

http https://auth.reloadly.com/oauth/token \
    client_id=CLIENTID \
    client_secret=CLIENTSECRET \
    grant_type=client_credentials \
    audience='https://topups-sandbox.reloadly.com'

Pay attention to the value of the audience parameter: https://topups-sandbox.reloadly.com. This is the corresponding value for the Sandbox environment. When going to production you want to use https://topups.reloadly.com instead

Once successful, you will get response data containing your access token, its privileges, and its lifespan

{
  "access_token":"eyJraWQiOiIwMDA1YzFmMC0xMjQ3LTRmNmUtYjU2ZC1jM2ZkZDVmMzhhOTIiLCJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9",
  "scope":"send-topups read-operators read-promotions read-topups-history read-prepaid-balance read-prepaid-commissions",
  "expires_in":5184000,
  "token_type":"Bearer"
}::Info

If you get an response with "errorCode": "INVALID_CREDENTIALS" you're most likely using the wrong set of credentials for the environment from where you want to get a token. Remember: the credentials used for Production are invalid in Sandbox and viceversa.

Make your first top-up

Now you've got your access token, the next step is to make a top-up on a mobile number. Reloadly spans across more than 700 operators in over 140 countries. This ensures you have a lot of options when making your first top-up. To top up a mobile number, you can make a POST request to the /topups endpoint

curl --location --request POST 'https://topups.reloadly.com/topups' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN_HERE' \
--header 'Accept: application/com.reloadly.topups-v1+json' \
--header 'Content-Type: application/json' \
--data-raw '{
	"operatorId":"685",
	"amount":"10",
	"customIdentifier": "This is example identifier 092",
	"recipientPhone": {
		"countryCode": "NG",
		"number": "08147658721"
	},
	"senderPhone": {
		"countryCode": "CA",
		"number": "1231231231"
	}
}'

http 'https://topups.reloadly.com/topups' \
    'Authorization: Bearer YOUR_ACCESS_TOKEN_HERE' \
    'Accept: application/com.reloadly.topups-v1+json' \
    'Content-Type: application/json' \
    recipientPhone[countryCode]="NG" \
    recipientPhone[number]="08147658721" \
    senderPhone[countryCode]="CA" \
    senderPhone[number]="1231231231"\
    operatorId=685 \
    amount=10 \
    customIdentifier="This is example identifier 092"

If this request is successful, you will get a response containing details of your top-up

{
  "transactionId":2127484,
  "operatorTransactionId":"2021040116191786605021010",
  "customIdentifier":null,
  "recipientPhone":"2348147658720",
  "recipientEmail":null,
  "senderPhone":null,
  "countryCode":"NG",
  "operatorId":341,
  "operatorName":"MTN Nigeria",
  "discount":0,
  "discountCurrencyCode":"NGN",
  "requestedAmount":100,
  "requestedAmountCurrencyCode":"NGN",
  "deliveredAmount":100,
  "deliveredAmountCurrencyCode":"NGN",
  "transactionDate":"2021-04-01 11:19:16",
  "pinDetail":null,
  "balanceInfo":{
    "oldBalance":9790.75,
    "newBalance":9690.75,
    "currencyCode":"NGN",
    "currencyName":"Nigerian Naira",
    "updatedAt":"2021-04-01 15:19:16"
  }
}

Next steps

Great! You have gotten started with Reloadly in the fastest way possible. Feel free to modify the code samples above in order to get more practice with our API. You can also check out the rest of the documentation for a concise understanding of the Airtime product.

Changelog

22 March 2022

NOTICE - PARAMETER ADDITIONS TO TOP-UP / TRANSACTION RESPONSES

Updates have been made to include the cost parameter in the response details of the following endpoints:

/topups
/topups/{{transactionId}}/status
/topups/reports/transactions
/topups/reports/transactions/{transactionId}

09 September 2021

NOTICE - PARAMETER ADDITIONS TO INDIAN OPERATORS

Updates have been made to include the following parameters in the details of all Indian operators

fixedAmountsPlanNames
localFixedAmountsPlanNames

More details on this can be found in the Get operator by ID and the Get operator by ISO code sections of the documentation

14 July 2021

NOTICE - UPCOMING CHANGE

In future releases, the commission parameter in the response data of the following endpoints will be deprecated.

/operators
/operators/{operatorid}
/operators/auto-detect/phone/{phone}/countries/{iso}
/operators/countries/{countrycode}

Users are advised to work with the internationalDiscount or localDiscount parameter as it contains the same data on the operator.

Account Balance

View an account's balance

With the /account/balance endpoint, you can retrieve the balance of your account in real-time

Account Balance

GET https://topups.reloadly.com/accounts/balance

Headers

Name

Type

Description

Authorization

string

Your access token is required as a bearer token in the request's header

{
  "balance":550.75,
  "currencyCode":"USD",
  "currencyName":"US Dollar",
  "updatedAt":"2018-12-04 08:45:51"
}

{
  "timeStamp":"2021-05-11 21:14:00",
  "message":"Full authentication is required to access this resource",
  "path":"/accounts/balance",
  "errorCode":"INVALID_TOKEN",
  "infoLink":null,
  "details":[
    
  ]
}

{
  "timestamp":"2021-05-11T21:14:29.629+0000",
  "status":404,
  "error":"Not Found",
  "message":"No message available",
  "path":"/accounts/balanc"
}

Request samples

curl --location --request GET 'https://topups.reloadly.com/accounts/balance' \
--header 'Accept: application/com.reloadly.topups-v1+json' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN_HERE' \
--header 'Content-Type: application/json'

using System;
using System.Threading.Tasks;
using System.Net.Http;
using System.Text;
using Newtonsoft.Json;

namespace WebAPIClient {
  class Program {

    static async Task Main(string[] args) {
      await ApiCall();
    }

    private static async Task ApiCall() {

      var message = new HttpRequestMessage(HttpMethod.Get, "https://topups.reloadly.com/accounts/balance");

      message.Headers.TryAddWithoutValidation("Authorization", "Bearer YOUR_ACCESS_TOKEN_HERE");
      message.Headers.TryAddWithoutValidation("Accept", "application/com.reloadly.topups-v1+json");
      message.Headers.TryAddWithoutValidation("Content-Type", "application/json");

      using
      var httpClient = new HttpClient();
      var response = await httpClient.SendAsync(message);
      var responseBody = await response.Content.ReadAsStringAsync();
      var result = JsonConvert.DeserializeObject < dynamic > (responseBody);

      Console.WriteLine(result);
    }

  }
}

package main

import (
  "fmt"
  "net/http"
  "io/ioutil"
)

func main() {

  url := "https://topups.reloadly.com/accounts/balance"
  method := "GET"

  client := &http.Client {
  }
  req, err := http.NewRequest(method, url, nil)

  if err != nil {
    fmt.Println(err)
    return
  }
  req.Header.Add("Accept", "application/com.reloadly.topups-v1+json")
  req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN_HERE")
  req.Header.Add("Content-Type", "application/json")

  res, err := client.Do(req)
  if err != nil {
    fmt.Println(err)
    return
  }
  defer res.Body.Close()

  body, err := ioutil.ReadAll(res.Body)
  if err != nil {
    fmt.Println(err)
    return
  }
  fmt.Println(string(body))
}

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
Request request = new Request.Builder()
  .url("https://topups.reloadly.com/accounts/balance")
  .method("GET", null)
  .addHeader("Accept", "application/com.reloadly.topups-v1+json")
  .addHeader("Authorization", "Bearer YOUR_ACCESS_TOKEN_HERE")
  .addHeader("Content-Type", "application/json")
  .build();
Response response = client.newCall(request).execute();

var myHeaders = new Headers();
myHeaders.append("Accept", "application/com.reloadly.topups-v1+json");
myHeaders.append("Authorization", "Bearer YOUR_ACCESS_TOKEN_HERE");
myHeaders.append("Content-Type", "application/json");

var requestOptions = {
  method: 'GET',
  headers: myHeaders,
  redirect: 'follow'
};

fetch("https://topups.reloadly.com/accounts/balance", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://topups.reloadly.com/accounts/balance',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => array(
    'Accept: application/com.reloadly.topups-v1+json',
    'Authorization: Bearer YOUR_ACCESS_TOKEN_HERE',
    'Content-Type: application/json'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

import requests
import json

url = "https://topups.reloadly.com/accounts/balance"

payload={}
headers = {
  'Accept': 'application/com.reloadly.topups-v1+json',
  'Authorization': 'Bearer YOUR_ACCESS_TOKEN_HERE',
  'Content-Type': 'application/json'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

Response parameters

Parameter

Type

Description

balance

number

This indicates the current account balance

currencyCode

string

This indicates the account's currency code

currencyName

string

This indicates the account's currency name

updatedAt

string

This indicates the last time a top-up was made from the account

Countries

Get all countries

Using the /countries endpoint, you can retrieve data on over 140 countries where airtime top-ups can be made with the Airtime API

Countries

GET https://topups.reloadly.com/countries

Headers

Name

Type

Description

Authorization*

string

Your access token is required as a bearer token in the request's header

[
  {
    "isoName":"AF",
    "name":"Afghanistan",
    "currencyCode":"AFN",
    "currencyName":"Afghan Afghani",
    "currencySymbol":"؋",
    "flag":"https://s3.amazonaws.com/rld-flags/af.svg",
    "callingCodes":[
      "+93"
    ]
  },
  {
    "isoName":"AS",
    "name":"American Samoa",
    "currencyCode":"USD",
    "currencyName":"US Dollar",
    "currencySymbol":"$",
    "flag":"https://s3.amazonaws.com/rld-flags/as.svg",
    "callingCodes":[
      "+1684"
    ]
  },
  {
    "isoName":"AI",
    "name":"Anguilla",
    "currencyCode":"XCD",
    "currencyName":"East Caribbean Dollar",
    "currencySymbol":"XCD",
    "flag":"https://s3.amazonaws.com/rld-flags/ai.svg",
    "callingCodes":[
      "+1264"
    ]
  },
  {
    "isoName":"AG",
    "name":"Antigua and Barbuda",
    "currencyCode":"XCD",
    "currencyName":"East Caribbean Dollar",
    "currencySymbol":"XCD",
    "flag":"https://s3.amazonaws.com/rld-flags/ag.svg",
    "callingCodes":[
      "+1268"
    ]
  }
]

{
  "timeStamp":"2021-05-11 21:14:00",
  "message":"Full authentication is required to access this resource",
  "path":"/countries",
  "errorCode":"INVALID_TOKEN",
  "infoLink":null,
  "details":[
    
  ]
}

{
  "timestamp":"2021-05-12T09:23:19.861+0000",
  "status":404,
  "error":"Not Found",
  "message":"No message available",
  "path":"/country"
}

Request samples

curl --location --request GET 'https://topups.reloadly.com/countries' \
--header 'Accept: application/com.reloadly.topups-v1+json' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN_HERE'

using System;
using System.Threading.Tasks;
using System.Net.Http;
using System.Text;
using Newtonsoft.Json;

namespace WebAPIClient {
  class Program {

    static async Task Main(string[] args) {
      await ApiCall();
    }

    private static async Task ApiCall() {
      
      var message = new HttpRequestMessage(HttpMethod.Get, "https://topups.reloadly.com/countries");

      message.Headers.TryAddWithoutValidation("Authorization", "Bearer YOUR_ACCESS_TOKEN_HERE");
      message.Headers.TryAddWithoutValidation("Accept", "application/com.reloadly.topups-v1+json");

      using
      var httpClient = new HttpClient();
      var response = await httpClient.SendAsync(message);
      var responseBody = await response.Content.ReadAsStringAsync();
      var result = JsonConvert.DeserializeObject < dynamic > (responseBody);

      Console.WriteLine(result);
    }

  }
}

package main

import (
  "fmt"
  "net/http"
  "io/ioutil"
)

func main() {

  url := "https://topups.reloadly.com/countries"
  method := "GET"

  client := &http.Client {
  }
  req, err := http.NewRequest(method, url, nil)

  if err != nil {
    fmt.Println(err)
    return
  }
  req.Header.Add("Accept", "application/com.reloadly.topups-v1+json")
  req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN_HERE")

  res, err := client.Do(req)
  if err != nil {
    fmt.Println(err)
    return
  }
  defer res.Body.Close()

  body, err := ioutil.ReadAll(res.Body)
  if err != nil {
    fmt.Println(err)
    return
  }
  fmt.Println(string(body))
}

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
Request request = new Request.Builder()
  .url("https://topups.reloadly.com/countries")
  .method("GET", null)
  .addHeader("Accept", "application/com.reloadly.topups-v1+json")
  .addHeader("Authorization", "Bearer YOUR_ACCESS_TOKEN_HERE")
  .build();
Response response = client.newCall(request).execute();

var request = require('request');
var options = {
  'method': 'GET',
  'url': 'https://topups.reloadly.com/countries',
  'headers': {
    'Accept': 'application/com.reloadly.topups-v1+json',
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN_HERE'
  }
};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://topups.reloadly.com/countries',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => array(
    'Accept: application/com.reloadly.topups-v1+json',
    'Authorization: Bearer YOUR_ACCESS_TOKEN_HERE'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

import requests
import json

url = "https://topups.reloadly.com/countries"

payload={}
headers = {
  'Accept': 'application/com.reloadly.topups-v1+json',
  'Authorization': 'Bearer YOUR_ACCESS_TOKEN_HERE'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

Response parameters

Parameter

Type

Description

isoName

string

This indicates the ISO code of the country

name

string

This indicates the country's name

currencyCode

string

This indicates the code of the country's currency

currencyName

string

This indicates the name of the country's currency

currencySymbol

string

This indicates the symbol of the country's currency

flag

string

This is a link to an SVG image of the country's flag

callingCodes

string

This indicates the country's international dialing code

Get country by ISO Code

With the /countries/{countrycode} endpoint, you can retrieve the details of a country by making a request with its ISO code

Country by ISO code

GET https://topups.reloadly.com/countries/{countrycode}

Path Parameters

Name

Type

Description

countryCode*

string

The country's ISO Code

Headers

Name

Type

Description

Authorization*

string

Your access token is required as a bearer token in the request's header

{
  "isoName":"US",
  "name":"United States",
  "currencyCode":"USD",
  "currencyName":"US Dollar",
  "currencySymbol":"$",
  "flag":"https://s3.amazonaws.com/rld-flags/us.svg",
  "callingCodes":[
    "+1"
  ]
}

{
  "timeStamp":"2021-05-12 07:17:42",
  "message":"Full authentication is required to access this resource",
  "path":"/countries/US",
  "errorCode":"INVALID_TOKEN",
  "infoLink":null,
  "details":[
    
  ]
}

{
  "timeStamp":"2021-05-12 07:15:00",
  "message":"Country not found and/or not currently supported",
  "path":"/countries/PKGG",
  "errorCode":"COUNTRY_NOT_SUPPORTED",
  "infoLink":null,
  "details":[
    
  ]
}

Request samples

curl --location --request GET 'https://topups.reloadly.com/countries/PK' \
--header 'Accept: application/com.reloadly.topups-v1+json' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN_HERE'

using System;
using System.Threading.Tasks;
using System.Net.Http;
using System.Text;
using Newtonsoft.Json;

namespace WebAPIClient {
  class Program {

    static async Task Main(string[] args) {
      await ApiCall();
    }

    private static async Task ApiCall() {

      var message = new HttpRequestMessage(HttpMethod.Get, "https://topups.reloadly.com/countries/PK");

      message.Headers.TryAddWithoutValidation("Authorization", "Bearer YOUR_ACCESS_TOKEN_HERE");
      message.Headers.TryAddWithoutValidation("Accept", "application/com.reloadly.topups-v1+json");

      using
      var httpClient = new HttpClient();
      var response = await httpClient.SendAsync(message);
      var responseBody = await response.Content.ReadAsStringAsync();
      var result = JsonConvert.DeserializeObject < dynamic > (responseBody);

      Console.WriteLine(result);
    }

  }
}

package main

import (
  "fmt"
  "net/http"
  "io/ioutil"
)

func main() {

  url := "https://topups.reloadly.com/countries/PK"
  method := "GET"

  client := &http.Client {
  }
  req, err := http.NewRequest(method, url, nil)

  if err != nil {
    fmt.Println(err)
    return
  }
  req.Header.Add("Accept", "application/com.reloadly.topups-v1+json")
  req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN_HERE")

  res, err := client.Do(req)
  if err != nil {
    fmt.Println(err)
    return
  }
  defer res.Body.Close()

  body, err := ioutil.ReadAll(res.Body)
  if err != nil {
    fmt.Println(err)
    return
  }
  fmt.Println(string(body))
}

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
Request request = new Request.Builder()
  .url("https://topups.reloadly.com/countries/PK")
  .method("GET", null)
  .addHeader("Accept", "application/com.reloadly.topups-v1+json")
  .addHeader("Authorization", "Bearer YOUR_ACCESS_TOKEN_HERE")
  .build();
Response response = client.newCall(request).execute();

var myHeaders = new Headers();
myHeaders.append("Accept", "application/com.reloadly.topups-v1+json");
myHeaders.append("Authorization", "Bearer YOUR_ACCESS_TOKEN_HERE");

var requestOptions = {
  method: 'GET',
  headers: myHeaders,
  redirect: 'follow'
};

fetch("https://topups.reloadly.com/countries/PK", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://topups.reloadly.com/countries/PK',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => array(
    'Accept: application/com.reloadly.topups-v1+json',
    'Authorization: Bearer YOUR_ACCESS_TOKEN_HERE'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

import requests
import json

url = "https://topups.reloadly.com/countries/PK"

payload={}
headers = {
  'Accept': 'application/com.reloadly.topups-v1+json',
  'Authorization': 'Bearer YOUR_ACCESS_TOKEN_HERE'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

Response parameters

Parameters

Type

Description

isoName

string

This indicates the ISO code of the country

name

string

This indicates the country's name

currencyCode

string

This indicates the code of the country's currency

currencyName

string

This indicates the name of the country's currency

currencySymbol

string

This indicates the symbol of the country's currency

flag

string

This is a link to an SVG image of the country's flag

callingCodes

string

This indicates the country's international dialing code

Operators

Get all operators

The /operators endpoint allows you to retrieve information on any of the 700+ available operators that can be used to make top-ups with the Airtime API

Operators

GET https://topups.reloadly.com/operators

Query Parameters

Name

Type

Description

includeBundles

boolean

Indicates if any airtime and data bundles being offered by the operator should be included in the API response. Default value is true

includeData

boolean

Indicates if any airtime or data plans being offered by the operator should be included in the API response. Default value is true

includePin

boolean

Indicates if PIN details for the operator should be included in the API response. Default value is true

suggested AmountsMap

boolean

Indicates if the suggestedAmountsMap field should be returned. Default value is false

suggested Amounts

boolean

Indicates if the suggestedAmounts field should be returned. Default value is false

size

integer

This indicates the number of operators to be retrieved on a page. Default value is 200

page

integer

This indicates the page of the operator list being retrieved. Default value is 1

Headers

Name

Type

Description

Authorization*

string

Your access token is required as a bearer token in the request's header

{
  "content":[
    {
      "operatorId":88,
      "name":"Movistar Colombia",
      "bundle":false,
      "data":false,
      "pin":false,
      "supportsLocalAmounts":false,
      "denominationType":"RANGE",
      "senderCurrencyCode":"USD",
      "senderCurrencySymbol":"$",
      "destinationCurrencyCode":"COP",
      "destinationCurrencySymbol":"$",
      "commission":4.42,
      "internationalDiscount":4.42,
      "localDiscount":0.00,
      "mostPopularAmount":null,
      "minAmount":5.00,
      "maxAmount":50,
      "localMinAmount":null,
      "localMaxAmount":null,
      "country":{
        "isoName":"CO",
        "name":"Colombia"
      },
      "fx":{
        "rate":2192.1867,
        "currencyCode":"COP"
      },
      "logoUrls":[
        "https://s3.amazonaws.com/rld-operator/3f4a8bcd3268-size-1.png",
        "https://s3.amazonaws.com/rld-operator/3f4a8bcd3268-size-2.png",
        "https://s3.amazonaws.com/rld-operator/3f4a8bcd3268-size-3.png"
      ],
      "fixedAmounts":[
        
      ],
      "fixedAmountsDescriptions":[
        
      ],
      "localFixedAmounts":[
        
      ],
      "localFixedAmountsDescriptions":[
        
      ],
      "suggestedAmounts":[
        7,
        10,
        15,
        20,
        25,
        30,
        35,
        40,
        45,
        50,
        55,
        60,
        65
      ],
      "suggestedAmountsMap":{
        "7":19482.51,
        "10":27832.16,
        "15":41748.23,
        "20":55664.31,
        "25":69580.39,
        "30":83496.46,
        "35":97412.54,
        "40":111328.61,
        "45":125244.69,
        "50":139160.77,
        "55":153076.84,
        "60":166992.92,
        "65":180909.00
      },
      "promotions":[
        
      ]
    }
  ],
  "pageable":{
    "sort":{
      "unsorted":true,
      "sorted":false
    },
    "pageSize":1,
    "pageNumber":0,
    "offset":0,
    "paged":true,
    "unpaged":false
  },
  "totalPages":609,
  "totalElements":609,
  "last":false,
  "sort":{
    "unsorted":true,
    "sorted":false
  },
  "first":true,
  "numberOfElements":3,
  "size":3,
  "number":0
}

{
  "timeStamp":"2021-05-12 08:06:03",
  "message":"Full authentication is required to access this resource",
  "path":"/operators",
  "errorCode":"INVALID_TOKEN",
  "infoLink":null,
  "details":[
    
  ]
}

{
  "timestamp":"2021-05-12T08:00:42.221+0000",
  "status":404,
  "error":"Not Found",
  "message":"No message available",
  "path":"/operator"
}

Request samples

curl --location --request GET 'https://topups.reloadly.com/operators' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN_HERE' \
--header 'Accept: application/com.reloadly.topups-v1+json'

using System;
using System.Threading.Tasks;
using System.Net.Http;
using System.Text;
using Newtonsoft.Json;

namespace WebAPIClient {
  class Program {

    static async Task Main(string[] args) {
      await ApiCall();
    }

    private static async Task ApiCall() {

      var message = new HttpRequestMessage(HttpMethod.Get, "https://topups.reloadly.com/operators");

      message.Headers.TryAddWithoutValidation("Authorization", "Bearer YOUR_ACCESS_TOKEN_HERE");
      message.Headers.TryAddWithoutValidation("Accept", "application/com.reloadly.topups-v1+json");

      using
      var httpClient = new HttpClient();
      var response = await httpClient.SendAsync(message);
      var responseBody = await response.Content.ReadAsStringAsync();
      var result = JsonConvert.DeserializeObject < dynamic > (responseBody);

      Console.WriteLine(result);
    }

  }
}

package main

import (
  "fmt"
  "net/http"
  "io/ioutil"
)

func main() {

  url := "https://topups.reloadly.com/operators"
  method := "GET"

  client := &http.Client {
  }
  req, err := http.NewRequest(method, url, nil)

  if err != nil {
    fmt.Println(err)
    return
  }
  req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN_HERE")
  req.Header.Add("Accept", "application/com.reloadly.topups-v1+json")

  res, err := client.Do(req)
  if err != nil {
    fmt.Println(err)
    return
  }
  defer res.Body.Close()

  body, err := ioutil.ReadAll(res.Body)
  if err != nil {
    fmt.Println(err)
    return
  }
  fmt.Println(string(body))
}

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
Request request = new Request.Builder()
  .url("https://topups.reloadly.com/operators")
  .method("GET", null)
  .addHeader("Authorization", "Bearer YOUR_ACCESS_TOKEN_HERE")
  .addHeader("Accept", "application/com.reloadly.topups-v1+json")
  .build();
Response response = client.newCall(request).execute();

var request = require('request');
var options = {
  'method': 'GET',
  'url': 'https://topups.reloadly.com/operators',
  'headers': {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN_HERE',
    'Accept': 'application/com.reloadly.topups-v1+json',
  }
};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://topups.reloadly.com/operators',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => array(
    'Authorization: Bearer YOUR_ACCESS_TOKEN_HERE',
    'Accept: application/com.reloadly.topups-v1+json',
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

import requests
import json

url = "https://topups.reloadly.com/operators"

payload={}
headers = {
  'Authorization': 'Bearer YOUR_ACCESS_TOKEN_HERE',
  'Accept': 'application/com.reloadly.topups-v1+json',
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

Response parameters

Parameter

Type

Description

id/operatorId

integer

The ID of the operator

name

string

The operator's name

bundle

boolean

Indicates if the operator has any existing bundle plans

data

boolean

Indicates if the operator has any existing data plans.

pin

boolean

Indicates if the operator supports PIN transactions

supports

LocalAmounts

boolean

Indicates if the operator can make top-ups in local amounts

denominationType

string

Indicates if the operator makes top-ups through a fixed amount or a range of amounts. Options include FIXED and RANGE

senderCurrencyCode

string

Indicates the currency code of the account where the top-up is being made from

senderCurrency

Symbol

string

Indicates the currency symbol of the account where the top-up is being made from

destinationCurrencyCode

string

Indicates the currency code of the mobile number where the top-up is being sent to

destinationCurrencySymbol

string

Indicates the currency symbol of the mobile number where the top-up is being sent to

commission

integer

Indicates if the operator offers a commission or discount

international

Discount

integer

Indicates if the operator offers a discount for top-ups made to foreign numbers

localDiscount

integer

Indicates if the operator offers a discount for top-ups made to local numbers

mostPopularAmount

integer

Indicates the amount that is often used to make a top-up

mostPopular

LocalAmount

integer

Indicates the amount that is often used to make a top-up locally

minAmount

integer

Indicates the minimum amount that can be used to make a top-up

maxAmount

integer

Indicates the maximum amount that can be used to make a top-up

localMinAmount

integer

Indicates the minimum amount that can be used to make a top-up locally

localMaxAmount

integer

Indicates the maximum amount that can be used to make a top-up locally

isoName

string

Indicates the country's ISO code

name

string

Indicates the country's name

rate

integer

Indicates the FX rate at which the top-up will be made

currencyCode

string

Indicates the code of the currency at which the top-up will be made

logoURLs

string

These are links to SVG images of the operator's logos

fixedAmounts

integer

Indicates the fixed amounts that a top-up can be made in with the operator

fixedAmounts

Description

string

Indicates the descriptions for the operator's fixed amounts

localFixedAmounts

integer

Indicates the local fixed amounts that a top-up can be made in with the operator

localFixed

AmountsDescription

string

Indicates the descriptions for the operator's local fixed amounts

suggestedAmounts

integer

Indicates the suggested amounts that can be used to make a top-up with the operator

suggested

AmountsMap

string

Indicates the suggested amounts that can be mapped through

promotions

string

Indicates the promotions currently offered by the operator

Get operator by ID

With the /operators/{operatorid} endpoint, a user can fetch details of an operator by making a request with the operator's ID

Operator by ID

GET https://topups.reloadly.com/operators/{operatorid}

Path Parameters

Name

Type

Description

operatorId*

integer

This indicates the operator's ID

Query Parameters

Name

Type

Description

supports Geographical RechargePlans

boolean

Indicates if the supportsGeograhicalRechargePlans field should be returned. Default value is false

suggested AmountsMap

boolean

Indicates if the suggestedAmountsMap field should be returned. Default value is false

suggested Amounts

boolean

Indicates if the suggestedAmounts field should be returned. Default value is false

Headers

Name

Type

Description

Authorization*

string

Your access token is required as a bearer token in the request's header

{
  "operatorId":200,
  "name":"Airtel India",
  "bundle":false,
  "data":false,
  "pin":false,
  "supportsGeographicalRechargePlans":true,
  "supportsLocalAmounts":false,
  "denominationType":"FIXED",
  "senderCurrencyCode":"USD",
  "senderCurrencySymbol":"$",
  "destinationCurrencyCode":"INR",
  "destinationCurrencySymbol":"₹",
  "commission":17.0,
  "internationalDiscount":17.0,
  "localDiscount":0.5,
  "mostPopularAmount":null,
  "mostPopularLocalAmount":null,
  "minAmount":null,
  "maxAmount":null,
  "localMinAmount":null,
  "localMaxAmount":null,
  "country":{
    "isoName":"IN",
    "name":"India"
  },
  "fx":{
    "rate":59,
    "currencyCode":"INR"
  },
  "logoUrls":[
    "https://s3.amazonaws.com/rld-operator/3f4a8bcd3268-size-1.png",
    "https://s3.amazonaws.com/rld-operator/3f4a8bcd3268-size-2.png",
    "https://s3.amazonaws.com/rld-operator/3f4a8bcd3268-size-3.png"
  ],
  "fixedAmounts":[
    
  ],
  "fixedAmountsDescriptions":[
    
  ],
  "localFixedAmounts":[
    
  ],
  "localFixedAmountsDescriptions":[
    
  ],
  "suggestedAmounts":[
    
  ],
  "suggestedAmountsMap":{
    
  },
  "additionalPlans":null,
  "geographicalRechargePlans":[
    {
      "locationCode":"AP",
      "locationName":"Andhra Pradesh",
      "fixedAmounts":[
        0.17,
        8.47,
        84.75
      ],
      "localAmounts":[
        20.00,
        500.00,
        5000.00
      ],
      "fixedAmountsDescriptions":{
        "0.31":"Get ISD Calling at discounted rates for 28 Days.",
        "8.47":"Get Talktime of Rs. 423.73",
        "84.75":"Get Talktime of Rs. 4237.29"
      },
      "localFixedAmountsDescriptions":{
        "18.00":"Get ISD Calling at discounted rates for 28 Days.",
        "100.00":"Get Talktime of Rs. 81.75",
        "5000.00":"Get Talktime of Rs. 4237.29"
      }
    },
    "locationCode":"DEL",
    "locationName":"Delhi",
    "fixedAmounts":[
      0.60,
      1.63,
      8.35
    ],
    "localAmounts":[
      26.00,
      51.00,
      501.00
    ],
    "fixedAmountsDescriptions":{
      "0.20":"Get 120 local/national SMS",
      "0.85":"Get 500 local/national SMS",
      "8.35":"Get 75 GB 4G/3G/2G Data"
    },
    "localFixedAmountsDescriptions":{
      "26.00":"Get 250 local/national SMS",
      "251.00":"Get 50 GB 4G/3G/2G Data",
      "501.00":"Get 75 GB 4G/3G/2G Data"
    }
  },
  "promotions":[
    
  ]

{
   "id":200,
   "operatorId":200,
   "name":"Airtel India",
   "bundle":false,
   "data":false,
   "pin":false,
   "supportsLocalAmounts":false,
   "supportsGeographicalRechargePlans":true,
   "denominationType":"FIXED",
   "senderCurrencyCode":"NGN",
   "senderCurrencySymbol":"₦",
   "destinationCurrencyCode":"INR",
   "destinationCurrencySymbol":"₹",
   "commission":17.0,
   "internationalDiscount":17.0,
   "localDiscount":0.5,
   "mostPopularAmount":null,
   "mostPopularLocalAmount":null,
   "minAmount":null,
   "maxAmount":null,
   "localMinAmount":null,
   "localMaxAmount":null,
   "country":{
      "isoName":"IN",
      "name":"India"
   },
   "fx":{
      "rate":0.14094,
      "currencyCode":"INR"
   },
   "logoUrls":[
      "https://s3.amazonaws.com/rld-operator/48a34cc8-a395-43b2-848d-8caa7af71649-size-1.png",
      "https://s3.amazonaws.com/rld-operator/48a34cc8-a395-43b2-848d-8caa7af71649-size-2.png",
      "https://s3.amazonaws.com/rld-operator/48a34cc8-a395-43b2-848d-8caa7af71649-size-3.png"
   ],
   "fixedAmounts":[
      
   ],
   "fixedAmountsDescriptions":{
      
   },
   "localFixedAmounts":[
      
   ],
   "localFixedAmountsDescriptions":{
      
   },
   "suggestedAmounts":[
      
   ],
   "suggestedAmountsMap":{
      
   },
   "geographicalRechargePlans":[
      {
         "locationCode":"ASM",
         "locationName":"Assam",
         "fixedAmounts":[
            69.87,
            139.74,
            706.92,
            3542.82,
            7085.64,
            35432.31
         ],
         "localAmounts":[
            10.00,
            20.00,
            100.00,
            500.00,
            1000.00,
            5000.00
         ],
         "fixedAmountsPlanNames":{
            "0.17":"Topup Plan",
            "0.34":"Topup Plan",
            "1.72":"Topup Plan",
            "8.62":"Topup Plan",
            "17.24":"Topup Plan",
            "86.21":"Topup Plan"
         },
         "fixedAmountsDescriptions":{
            "69.87":"Get Talktime of Rs. 7.47. Validity : 0 Days. Talk time : 7.47",
            "139.74":"Get Talktime of Rs. 14.95. Validity : 0 Days. Talk time : 14.95",
            "706.92":"Get Talktime of Rs. 81.75. Validity : 0 Days. Talk time : 81.75",
            "3542.82":"Get Talktime of Rs. 423.73. Validity : 0 Days. Talk time : 423.73",
            "7085.64":"Get Talktime of Rs. 847.46. Validity : 0 Days. Talk time : 847.46",
            "35432.31":"Get Talktime of Rs. 4237.29. Validity : 0 Days. Talk time : 4237.29"
         },
         "localFixedAmountsPlanNames":{
            "10.00":"Topup Plan",
            "20.00":"Topup Plan",
            "100.00":"Topup Plan",
            "500.00":"Topup Plan",
            "1000.00":"Topup Plan",
            "5000.00":"Topup Plan"
         },
         "localFixedAmountsDescriptions":{
            "10.00":"Get Talktime of Rs. 7.47. Validity : 0 Days. Talk time : 7.47",
            "20.00":"Get Talktime of Rs. 14.95. Validity : 0 Days. Talk time : 14.95",
            "100.00":"Get Talktime of Rs. 81.75. Validity : 0 Days. Talk time : 81.75",
            "500.00":"Get Talktime of Rs. 423.73. Validity : 0 Days. Talk time : 423.73",
            "1000.00":"Get Talktime of Rs. 847.46. Validity : 0 Days. Talk time : 847.46",
            "5000.00":"Get Talktime of Rs. 4237.29. Validity : 0 Days. Talk time : 4237.29"
         }
      },
      {
         "locationCode":"PUN",
         "locationName":"Punjab",
         "fixedAmounts":[
            69.87,
            139.74,
            706.92,
            3542.82,
            7085.64,
            35432.31
         ],
         "localAmounts":[
            10.00,
            20.00,
            100.00,
            500.00,
            1000.00,
            5000.00
         ],
         "fixedAmountsPlanNames":{
            "0.17":"Topup Plan",
            "0.34":"Topup Plan",
            "1.72":"Topup Plan",
            "8.62":"Topup Plan",
            "17.24":"Topup Plan",
            "86.21":"Topup Plan"
         },
         "fixedAmountsDescriptions":{
            "69.87":"Get Talktime of Rs. 7.47. Validity : 0 Days. Talk time : 7.47",
            "139.74":"Get Talktime of Rs. 14.95. Validity : 0 Days. Talk time : 14.95",
            "706.92":"Get Talktime of Rs. 81.75. Validity : 0 Days. Talk time : 81.75",
            "3542.82":"Get Talktime of Rs. 423.73. Validity : 0 Days. Talk time : 423.73",
            "7085.64":"Get Talktime of Rs. 847.46. Validity : 0 Days. Talk time : 847.46",
            "35432.31":"Get Talktime of Rs. 4237.29. Validity : 0 Days. Talk time : 4237.29"
         },
         "localFixedAmountsPlanNames":{
            "10.00":"Topup Plan",
            "20.00":"Topup Plan",
            "100.00":"Topup Plan",
            "500.00":"Topup Plan",
            "1000.00":"Topup Plan",
            "5000.00":"Topup Plan"
         },
         "localFixedAmountsDescriptions":{
            "10.00":"Get Talktime of Rs. 7.47. Validity : 0 Days. Talk time : 7.47",
            "20.00":"Get Talktime of Rs. 14.95. Validity : 0 Days. Talk time : 14.95",
            "100.00":"Get Talktime of Rs. 81.75. Validity : 0 Days. Talk time : 81.75",
            "500.00":"Get Talktime of Rs. 423.73. Validity : 0 Days. Talk time : 423.73",
            "1000.00":"Get Talktime of Rs. 847.46. Validity : 0 Days. Talk time : 847.46",
            "5000.00":"Get Talktime of Rs. 4237.29. Validity : 0 Days. Talk time : 4237.29"
         }
      }
   ],
   "promotions":[
      
   ]
}

{
  "timeStamp":"2021-05-13 23:07:04",
  "message":"Could not retrieve/update resources at the moment, please try again later",
  "path":"/operators/1288",
  "errorCode":null,
  "infoLink":null,
  "details":[
    
  ]
}

{
  "timeStamp":"2021-05-12 07:17:42",
  "message":"Full authentication is required to access this resource",
  "path":"/operators/128",
  "errorCode":"INVALID_TOKEN",
  "infoLink":null,
  "details":[
    
  ]
}

{
  "timestamp":"2021-05-13T23:15:31.837+0000",
  "status":404,
  "error":"Not Found",
  "message":"No message available",
  "path":"/operator/128"
}

Request samples

curl --location --request GET 'https://topups.reloadly.com/operators/128?suggestedAmounts=true&suggestedAmountsMap=true' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN_HERE' \
--header 'Accept: application/com.reloadly.topups-v1+json'

using System;
using System.Threading.Tasks;
using System.Net.Http;
using System.Text;
using Newtonsoft.Json;

namespace WebAPIClient {
  class Program {

    static async Task Main(string[] args) {
      await ApiCall();
    }

    private static async Task ApiCall() {

      var message = new HttpRequestMessage(HttpMethod.Get, "https://topups.reloadly.com/operators/128?suggestedAmounts=true&suggestedAmountsMap=true");

      message.Headers.TryAddWithoutValidation("Authorization", "Bearer YOUR_ACCESS_TOKEN_HERE");
      message.Headers.TryAddWithoutValidation("Accept", "application/com.reloadly.topups-v1+json");

      using
      var httpClient = new HttpClient();
      var response = await httpClient.SendAsync(message);
      var responseBody = await response.Content.ReadAsStringAsync();
      var result = JsonConvert.DeserializeObject < dynamic > (responseBody);

      Console.WriteLine(result);
    }

  }
}

package main

import (
  "fmt"
  "net/http"
  "io/ioutil"
)

func main() {

  url := "https://topups.reloadly.com/operators/128?suggestedAmounts=true&suggestedAmountsMap=true"
  method := "GET"

  client := &http.Client {
  }
  req, err := http.NewRequest(method, url, nil)

  if err != nil {
    fmt.Println(err)
    return
  }
  req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN_HERE")
  req.Header.Add("Accept", "application/com.reloadly.topups-v1+json")

  res, err := client.Do(req)
  if err != nil {
    fmt.Println(err)
    return
  }
  defer res.Body.Close()

  body, err := ioutil.ReadAll(res.Body)
  if err != nil {
    fmt.Println(err)
    return
  }
  fmt.Println(string(body))
}

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
Request request = new Request.Builder()
  .url("https://topups.reloadly.com/operators/128?suggestedAmounts=true&suggestedAmountsMap=true")
  .method("GET", null)
  .addHeader("Authorization", "Bearer YOUR_ACCESS_TOKEN_HERE")
  .addHeader("Accept", "application/com.reloadly.topups-v1+json")
  .build();
Response response = client.newCall(request).execute();

var request = require('request');
var options = {
  'method': 'GET',
  'url': 'https://topups.reloadly.com/operators/128?suggestedAmounts=true&suggestedAmountsMap=true',
  'headers': {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN_HERE',
    'Accept': 'application/com.reloadly.topups-v1+json'
  }
};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://topups.reloadly.com/operators/128?suggestedAmounts=true&suggestedAmountsMap=true',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => array(
    'Authorization: Bearer YOUR_ACCESS_TOKEN_HERE',
    'Accept: application/com.reloadly.topups-v1+json'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

import requests
import json

url = "https://topups.reloadly.com/operators/128?suggestedAmounts=true&suggestedAmountsMap=true"

payload={}
headers = {
  'Authorization': 'Bearer YOUR_ACCESS_TOKEN_HERE',
  'Accept': 'application/com.reloadly.topups-v1+json'
}

Response parameters

Parameter

Type

Description

id/operatorId

integer

This indicates the operator's ID

name

string

This indicates the operator's name

bundle

boolean

Indicates if the operator has any existing bundle plans

data

boolean

Indicates if the operator has any existing data plans

pin

boolean

Indicates if the operator supports PIN transactions

supports

LocalAmounts

boolean

Indicates if the operator can make top-ups in local amounts

denominationType

string

Indicates if the operator makes top-ups through a fixed amount or a range of amounts. Options include FIXED and RANGE

senderCurrencyCode

string

Indicates the currency code of the account where the top-up is being made from

senderCurrency

Symbol

string

Indicates the currency symbol of the account where the top-up is being made from

destination

CurrencyCode

string

Indicates the currency code of the mobile number where the top-up is being sent to

destination

CurrencySymbol

string

Indicates the currency symbol of the mobile number where the top-up is being sent to

commission

integer

Indicates if the operator offers a commission or discount

international

Discount

integer

Indicates if the operator offers a discount for top-ups made to foreign numbers

localDiscount

integer

Indicates if the operator offers a discount for top-ups made to local numbers

mostPopularAmount

integer

Indicates the amount that is often used to make a top-up

mostPopular

LocalAmount

integer

Indicates the amount that is often used to make a top-up locally

minAmount

integer

Indicates the minimum amount that can be used to make a top-up

maxAmount

integer

Indicates the maximum amount that can be used to make a top-up

localMinAmount

integer

Indicates the minimum amount that can be used to make a top-up locally

localMaxAmount

integer

Indicates the maximum amount that can be used to make a top-up locally

isoName

string

Indicates the country's ISO code

name

string

Indicates the country's name

rate

integer

Indicates the FX rate at which the top-up will be made

currencyCode

string

Indicates the code of the currency at which the top-up will be made

logoURLs

string

These are links to SVG images of the operator's logos

fixedAmounts

integer

Indicates the fixed amounts that a top-up can be made in with the operator

fixedAmounts

Description

string

Indicates the descriptions for the operator's fixed amounts

localFixedAmounts

integer

Indicates the local fixed amounts that a top-up can be made in with the operator

localFixed

AmountsDescription

string

Indicates the descriptions for the operator's local fixed amounts

suggestedAmounts

integer

Indicates the suggested amounts that can be used to make a top-up with the operator

suggested

AmountsMap

string

Indicates the suggested amounts that can be mapped through

promotions

string

Indicates the promotions currently offered by the operator

Response parameters (for operators in India)

Parameter

Type

Description

geographical

RechargePlans

object

Indicates an object that contains the details of each geographical plan owned by the operator within a country

locationCode

string

This is an abbreviation for the geographical location that has a different recharge plan. Examples include “AP” for “Andhra Pradesh” or “DEL” for “Delhi”

locationName

string

This is the name of a geographical location that has a different recharge plan

fixedAmounts

integer

Indicates the fixed amounts that a top-up can be made in with the operator

localAmounts

integer

Indicates the local amounts that a top-up can be made in with the operator

fixedAmounts

PlanNames

string

Indicates the plan name (top-up, data, or bundle) for each fixed amount provided by the operator

fixedAmounts

Descriptions

string

Indicates the plan description (top-up, data, or bundle) for each fixed amount provided by the operator

localFixedAmounts

PlanNames

string

Indicates the plan name (top-up, data, or bundle) for each local fixed amount provided by the operator

localFixedAmounts

PlanDescriptions

string

Indicates the plan description (top-up, data, or bundle) for each local fixed amount provided by the operator

Auto-detect an operator

With the /operators/auto-detect/phone/{phone}/countries/{iso} endpoint, a user can retrieve the operator details of a mobile number and the ISO code of the country where the mobile number is registered

Auto-detect operator

GET https://topups.reloadly.com/operators/auto-detect/phone/{phone}/countries/{countryisocode}

Path Parameters

Query Parameters

Headers

Request samples

Response parameters

Get operator by ISO Code

Using the /operators/countries/{countrycode} endpoint, developers can retrieve an operator's details using the ISO code of the country where it is registered

Operator by ISO

GET https://topups.reloadly.com/operators/countries/{countrycode}

Path Parameters

Name

Type

Description

countryCode*

string

The ISO code of the country where the operator is registered

Query Parameters

Name

Type

Description

suggested AmountsMap

boolean

Indicates if the suggestedAmountsMap field should be returned. Default value is false

suggested Amounts

boolean

Indicates if the suggestedAmounts field should be returned. Default value is false

includePin

boolean

Indicates if PIN details for the operator should be included in the API response. Default value is True

includeData

boolean

Indicates if any airtime or data plans being offered by the operator should be included in the API response. Default value is true

includesBundles

boolean

Indicates if any airtime and data bundles being offered by the operator should be included in the API response. Default value is true

Headers

Name

Type

Description

Authorization*

string

Your access token is required as a bearer token in the request's header

{
  "operatorId":88,
  "name":"Movistar Colombia",
  "bundle":false,
  "data":false,
  "pin":false,
  "supportsLocalAmounts":false,
  "denominationType":"RANGE",
  "senderCurrencyCode":"USD",
  "senderCurrencySymbol":"$",
  "destinationCurrencyCode":"COP",
  "destinationCurrencySymbol":"$",
  "commission":4.42,
  "internationalDiscount":4.42,
  "localDiscount":0.00,
  "mostPopularAmount":null,
  "minAmount":5.00,
  "maxAmount":50,
  "localMinAmount":null,
  "localMaxAmount":null,
  "country":{
    "isoName":"CO",
    "name":"Colombia"
  },
  "fx":{
    "rate":2192.1867,
    "currencyCode":"COP"
  },
  "logoUrls":[
    "https://s3.amazonaws.com/rld-operator/3f4a8bcd3268-size-1.png",
    "https://s3.amazonaws.com/rld-operator/3f4a8bcd3268-size-2.png",
    "https://s3.amazonaws.com/rld-operator/3f4a8bcd3268-size-3.png"
  ],
  "fixedAmounts":[
    
  ],
  "fixedAmountsDescriptions":[
    
  ],
  "localFixedAmounts":[
    
  ],
  "localFixedAmountsDescriptions":[
    
  ],
  "suggestedAmounts":[
    7,
    10,
    15,
    20,
    25,
    30,
    35,
    40,
    45,
    50,
    55,
    60,
    65
  ],
  "suggestedAmountsMap":{
    "7":19482.51,
    "10":27832.16,
    "15":41748.23,
    "20":55664.31,
    "25":69580.39,
    "30":83496.46,
    "35":97412.54,
    "40":111328.61,
    "45":125244.69,
    "50":139160.77,
    "55":153076.84,
    "60":166992.92,
    "65":180909.00
  },
  "promotions":[
    
  ]
}

{
   "id":200,
   "operatorId":200,
   "name":"Airtel India",
   "bundle":false,
   "data":false,
   "pin":false,
   "supportsLocalAmounts":false,
   "supportsGeographicalRechargePlans":true,
   "denominationType":"FIXED",
   "senderCurrencyCode":"NGN",
   "senderCurrencySymbol":"₦",
   "destinationCurrencyCode":"INR",
   "destinationCurrencySymbol":"₹",
   "commission":17.0,
   "internationalDiscount":17.0,
   "localDiscount":0.5,
   "mostPopularAmount":null,
   "mostPopularLocalAmount":null,
   "minAmount":null,
   "maxAmount":null,
   "localMinAmount":null,
   "localMaxAmount":null,
   "country":{
      "isoName":"IN",
      "name":"India"
   },
   "fx":{
      "rate":0.14094,
      "currencyCode":"INR"
   },
   "logoUrls":[
      "https://s3.amazonaws.com/rld-operator/48a34cc8-a395-43b2-848d-8caa7af71649-size-1.png",
      "https://s3.amazonaws.com/rld-operator/48a34cc8-a395-43b2-848d-8caa7af71649-size-2.png",
      "https://s3.amazonaws.com/rld-operator/48a34cc8-a395-43b2-848d-8caa7af71649-size-3.png"
   ],
   "fixedAmounts":[
      
   ],
   "fixedAmountsDescriptions":{
      
   },
   "localFixedAmounts":[
      
   ],
   "localFixedAmountsDescriptions":{
      
   },
   "suggestedAmounts":[
      
   ],
   "suggestedAmountsMap":{
      
   },
   "geographicalRechargePlans":[
      {
         "locationCode":"ASM",
         "locationName":"Assam",
         "fixedAmounts":[
            69.87,
            139.74,
            706.92,
            3542.82,
            7085.64,
            35432.31
         ],
         "localAmounts":[
            10.00,
            20.00,
            100.00,
            500.00,
            1000.00,
            5000.00
         ],
         "fixedAmountsPlanNames":{
            "0.17":"Topup Plan",
            "0.34":"Topup Plan",
            "1.72":"Topup Plan",
            "8.62":"Topup Plan",
            "17.24":"Topup Plan",
            "86.21":"Topup Plan"
         },
         "fixedAmountsDescriptions":{
            "69.87":"Get Talktime of Rs. 7.47. Validity : 0 Days. Talk time : 7.47",
            "139.74":"Get Talktime of Rs. 14.95. Validity : 0 Days. Talk time : 14.95",
            "706.92":"Get Talktime of Rs. 81.75. Validity : 0 Days. Talk time : 81.75",
            "3542.82":"Get Talktime of Rs. 423.73. Validity : 0 Days. Talk time : 423.73",
            "7085.64":"Get Talktime of Rs. 847.46. Validity : 0 Days. Talk time : 847.46",
            "35432.31":"Get Talktime of Rs. 4237.29. Validity : 0 Days. Talk time : 4237.29"
         },
         "localFixedAmountsPlanNames":{
            "10.00":"Topup Plan",
            "20.00":"Topup Plan",
            "100.00":"Topup Plan",
            "500.00":"Topup Plan",
            "1000.00":"Topup Plan",
            "5000.00":"Topup Plan"
         },
         "localFixedAmountsDescriptions":{
            "10.00":"Get Talktime of Rs. 7.47. Validity : 0 Days. Talk time : 7.47",
            "20.00":"Get Talktime of Rs. 14.95. Validity : 0 Days. Talk time : 14.95",
            "100.00":"Get Talktime of Rs. 81.75. Validity : 0 Days. Talk time : 81.75",
            "500.00":"Get Talktime of Rs. 423.73. Validity : 0 Days. Talk time : 423.73",
            "1000.00":"Get Talktime of Rs. 847.46. Validity : 0 Days. Talk time : 847.46",
            "5000.00":"Get Talktime of Rs. 4237.29. Validity : 0 Days. Talk time : 4237.29"
         }
      },
      {
         "locationCode":"PUN",
         "locationName":"Punjab",
         "fixedAmounts":[
            69.87,
            139.74,
            706.92,
            3542.82,
            7085.64,
            35432.31
         ],
         "localAmounts":[
            10.00,
            20.00,
            100.00,
            500.00,
            1000.00,
            5000.00
         ],
         "fixedAmountsPlanNames":{
            "0.17":"Topup Plan",
            "0.34":"Topup Plan",
            "1.72":"Topup Plan",
            "8.62":"Topup Plan",
            "17.24":"Topup Plan",
            "86.21":"Topup Plan"
         },
         "fixedAmountsDescriptions":{
            "69.87":"Get Talktime of Rs. 7.47. Validity : 0 Days. Talk time : 7.47",
            "139.74":"Get Talktime of Rs. 14.95. Validity : 0 Days. Talk time : 14.95",
            "706.92":"Get Talktime of Rs. 81.75. Validity : 0 Days. Talk time : 81.75",
            "3542.82":"Get Talktime of Rs. 423.73. Validity : 0 Days. Talk time : 423.73",
            "7085.64":"Get Talktime of Rs. 847.46. Validity : 0 Days. Talk time : 847.46",
            "35432.31":"Get Talktime of Rs. 4237.29. Validity : 0 Days. Talk time : 4237.29"
         },
         "localFixedAmountsPlanNames":{
            "10.00":"Topup Plan",
            "20.00":"Topup Plan",
            "100.00":"Topup Plan",
            "500.00":"Topup Plan",
            "1000.00":"Topup Plan",
            "5000.00":"Topup Plan"
         },
         "localFixedAmountsDescriptions":{
            "10.00":"Get Talktime of Rs. 7.47. Validity : 0 Days. Talk time : 7.47",
            "20.00":"Get Talktime of Rs. 14.95. Validity : 0 Days. Talk time : 14.95",
            "100.00":"Get Talktime of Rs. 81.75. Validity : 0 Days. Talk time : 81.75",
            "500.00":"Get Talktime of Rs. 423.73. Validity : 0 Days. Talk time : 423.73",
            "1000.00":"Get Talktime of Rs. 847.46. Validity : 0 Days. Talk time : 847.46",
            "5000.00":"Get Talktime of Rs. 4237.29. Validity : 0 Days. Talk time : 4237.29"
         }
      }
   ],
   "promotions":[
      
   ]
}

{
  "timeStamp":"2021-05-17 15:51:26",
  "message":"Invalid country code, see https://www.iban.com/country-codes",
  "path":"/operators/countries/COT",
  "errorCode":null,
  "infoLink":null,
  "details":[
    
  ]
}

{
  "timeStamp":"2021-05-12 07:17:42",
  "message":"Full authentication is required to access this resource",
  "path":"/operators/countries/SV",
  "errorCode":"INVALID_TOKEN",
  "infoLink":null,
  "details":[
    
  ]
}

{
  "timestamp":"2021-05-17T15:37:28.104+0000",
  "status":404,
  "error":"Not Found",
  "message":"No message available",
  "path":"/operator/countries/CO"
}

Request samples

curl --location --request GET 'https://topups.reloadly.com/operators/countries/PK?includeBundles=true&includeData=true&includePin=true&suggestedAmounts=true&suggestedAmountsMap=true' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN_HERE' \
--header 'Accept: application/com.reloadly.topups-v1+json' \

using System;
using System.Threading.Tasks;
using System.Net.Http;
using System.Text;
using Newtonsoft.Json;

namespace WebAPIClient {
  class Program {

    static async Task Main(string[] args) {
      await ApiCall();
    }

    private static async Task ApiCall() {

      var message = new HttpRequestMessage(HttpMethod.Get, "https://topups.reloadly.com/operators/countries/PK?includeBundles=true&includeData=true&includePin=true&suggestedAmounts=true&suggestedAmountsMap=true");

      message.Headers.TryAddWithoutValidation("Authorization", "Bearer YOUR_ACCESS_TOKEN_HERE");
      message.Headers.TryAddWithoutValidation("Accept", "application/com.reloadly.topups-v1+json");
    
      using
      var httpClient = new HttpClient();
      var response = await httpClient.SendAsync(message);
      var responseBody = await response.Content.ReadAsStringAsync();
      var result = JsonConvert.DeserializeObject < dynamic > (responseBody);

      Console.WriteLine(result);
    }

  }
}

package main

import (
  "fmt"
  "net/http"
  "io/ioutil"
)

func main() {

  url := "https://topups.reloadly.com/operators/countries/PK?includeBundles=true&includeData=true&includePin=true&suggestedAmounts=true&suggestedAmountsMap=true"
  method := "GET"

  client := &http.Client {
  }
  req, err := http.NewRequest(method, url, nil)

  if err != nil {
    fmt.Println(err)
    return
  }
  req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN_HERE")
  req.Header.Add("Accept", "application/com.reloadly.topups-v1+json")

  res, err := client.Do(req)
  if err != nil {
    fmt.Println(err)
    return
  }
  defer res.Body.Close()

  body, err := ioutil.ReadAll(res.Body)
  if err != nil {
    fmt.Println(err)
    return
  }
  fmt.Println(string(body))
}

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
Request request = new Request.Builder()
  .url("https://topups.reloadly.com/operators/countries/PK?includeBundles=true&includeData=true&includePin=true&suggestedAmounts=true&suggestedAmountsMap=true")
  .method("GET", null)
  .addHeader("Authorization", "Bearer YOUR_ACCESS_TOKEN_HERE")
  .addHeader("Accept", "application/com.reloadly.topups-v1+json")
  .addHeader("Content-Type", "application/json")
  .build();
Response response = client.newCall(request).execute();

var request = require('request');
var options = {
  'method': 'GET',
  'url': 'https://topups.reloadly.com/operators/countries/PK?includeBundles=true&includeData=true&includePin=true&suggestedAmounts=true&suggestedAmountsMap=true',
  'headers': {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN_HERE',
    'Accept': 'application/com.reloadly.topups-v1+json',
    'Content-Type': 'application/json'
  }
};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://topups.reloadly.com/operators/countries/PK?includeBundles=true&includeData=true&includePin=true&suggestedAmounts=true&suggestedAmountsMap=true',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => array(
    'Authorization: Bearer YOUR_ACCESS_TOKEN_HERE',
    'Accept: application/com.reloadly.topups-v1+json',
    'Content-Type: application/json'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

import requests
import json

url = "https://topups.reloadly.com/operators/countries/PK?includeBundles=true&includeData=true&includePin=true&suggestedAmounts=true&suggestedAmountsMap=true"

payload={}
headers = {
  'Authorization': 'Bearer YOUR_ACCESS_TOKEN_HERE',
  'Accept': 'application/com.reloadly.topups-v1+json',
  'Content-Type': 'application/json'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

Response parameters

Parameter

Type

Description

id/operatorId

integer

The ID of the operator

name

string

The operator's name

bundle

boolean

Indicates if the operator has any existing bundle plans

data

boolean

Indicates if the operator has any existing data plans.

pin

boolean

Indicates if the operator supports PIN transactions

supportsLocal

Amounts

boolean

Indicates if the operator can make top-ups in local amounts

denominationType

string

Indicates if the operator makes top-ups through a fixed amount or a range of amounts. Options include FIXED and RANGE

senderCurrencyCode

string

Indicates the currency code of the account where the top-up is being made from

senderCurrency

Symbol

string

Indicates the currency symbol of the account where the top-up is being made from

destinationCurrencyCode

string

Indicates the currency code of the mobile number where the top-up is being sent to

destinationCurrencySymbol

string

Indicates the currency symbol of the mobile number where the top-up is being sent to

commission

integer

Indicates if the operator offers a commission or discount

international

Discount

integer

Indicates if the operator offers a discount for top-ups made to foreign numbers

localDiscount

integer

Indicates if the operator offers a discount for top-ups made to local numbers

mostPopularAmount

integer

Indicates the amount that is often used to make a top-up

mostPopular

LocalAmount

integer

Indicates the amount that is often used to make a top-up locally

minAmount

integer

Indicates the minimum amount that can be used to make a top-up

maxAmount

integer

Indicates the maximum amount that can be used to make a top-up

localMinAmount

integer

Indicates the minimum amount that can be used to make a top-up locally

localMaxAmount

integer

Indicates the maximum amount that can be used to make a top-up locally

isoName

string

Indicates the country's ISO code

name

string

Indicates the country's name

rate

integer

Indicates the FX rate at which the top-up will be made

currencyCode

string

Indicates the code of the currency at which the top-up will be made

logoURLs

string

These are links to SVG images of the operator's logos

fixedAmounts

integer

Indicates the fixed amounts that a top-up can be made in with the operator

fixedAmounts

Description

string

Indicates the descriptions for the operator's fixed amounts

localFixedAmounts

integer

Indicates the local fixed amounts that a top-up can be made in with the operator

localFixedAmounts

Description

string

Indicates the descriptions for the operator's local fixed amounts

suggestedAmounts

integer

Indicates the suggested amounts that can be used to make a top-up with the operator

suggested

AmountsMap

string

Indicates the suggested amounts that can be mapped through

promotions

string

Indicates the promotions currently offered by the operator

Response parameters (for operators in India)

Parameter

Type

Description

geographical

RechargePlans

object

Indicates an object that contains the details of each geographical plan owned by the operator within a country

locationCode

string

This is an abbreviation for the geographical location that has a different recharge plan. Examples include “AP” for “Andhra Pradesh” or “DEL” for “Delhi”

locationName

string

This is the name of a geographical location that has a different recharge plan

fixedAmounts

integer

Indicates the fixed amounts that a top-up can be made in with the operator

localAmounts

integer

Indicates the local amounts that a top-up can be made in with the operator

fixedAmounts

PlanNames

string

Indicates the plan name (top-up, data, or bundle) for each fixed amount provided by the operator

fixedAmounts

Descriptions

string

Indicates the plan description (top-up, data, or bundle) for each fixed amount provided by the operator

localFixedAmounts

PlanNames

string

Indicates the plan name (top-up, data, or bundle) for each local fixed amount provided by the operator

localFixedAmounts

PlanDescriptions

string

Indicates the plan description (top-up, data, or bundle) for each local fixed amount provided by the operator

FX Rates

Fetch FX Rate by operator ID

The /operators/fx-rate endpoint allows you to fetch an operator's foreign exchange rate for international top-ups

FX Rate

POST https://topups.reloadly.com/operators/fx-rate

Headers

Request Body

Request samples

Response parameters

Commissions

Get all commissions

With the /operators/commissions endpoint, developers can get a list of all operators who are running active discounts on top-ups

Commissions

GET https://topups.reloadly.com/operators/commissions

Query Parameters

Name

Type

Description

size

integer

The number of operators offering discounts to be retrieved on a page. Default value is 200

page

integer

The page of the list of operators offering discounts. Default value is 1

Headers

Name

Type

Description

Authorization*

string

Your access token is required as a bearer token in the request's header

{
  "content":[
    {
      "operator":{
        "operatorId":1,
        "name":"Afghan Wireless Afghanistan",
        "countryCode":"AF",
        "status":true,
        "bundle":false
      },
      "percentage":10,
      "internationalPercentage":10,
      "localPercentage":0,
      "updatedAt":"2018-06-26 03:36:16"
    },
    {
      "operator":{
        "operatorId":2,
        "name":"MTN Afghanistan",
        "countryCode":"AF",
        "status":true,
        "bundle":false
      },
      "percentage":10,
      "internationalPercentage":10,
      "localPercentage":0,
      "updatedAt":"2018-06-26 03:36:16"
    },
    {
      "operator":{
        "operatorId":3,
        "name":"Etisalat Afghanistan",
        "countryCode":"AF",
        "status":true,
        "bundle":false
      },
      "percentage":10,
      "internationalPercentage":10,
      "localPercentage":0,
      "updatedAt":"2018-06-26 03:36:16"
    }
  ],
  "pageable":{
    "sort":{
      "unsorted":true,
      "sorted":false
    },
    "pageSize":3,
    "pageNumber":0,
    "offset":0,
    "paged":true,
    "unpaged":false
  },
  "totalPages":204,
  "totalElements":611,
  "last":false,
  "sort":{
    "unsorted":true,
    "sorted":false
  },
  "first":true,
  "numberOfElements":3,
  "size":3,
  "number":0
}

{
  "timeStamp":"2021-06-09 23:24:30",
  "message":"Full authentication is required to access this resource",
  "path":"/operators/commissions",
  "errorCode":"INVALID_TOKEN",
  "infoLink":null,
  "details":[
    
  ]
}

{
  "timestamp":"2021-06-09T23:22:56.125+0000",
  "status":404,
  "error":"Not Found",
  "message":"No message available",
  "path":"/operator/commissions"
}

Request samples

curl --location --request GET 'https://topups.reloadly.com/operators/commissions' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN_HERE' \
--header 'Accept: application/com.reloadly.topups-v1+json'

using System;
using System.Threading.Tasks;
using System.Net.Http;
using System.Text;
using Newtonsoft.Json;

namespace WebAPIClient {
  class Program {

    static async Task Main(string[] args) {
      await ApiCall();
    }

    private static async Task ApiCall() {

      var message = new HttpRequestMessage(HttpMethod.Get, "https://topups.reloadly.com/operators/commissions");

      message.Headers.TryAddWithoutValidation("Authorization", "Bearer YOUR_ACCESS_TOKEN_HERE");
      message.Headers.TryAddWithoutValidation("Accept", "application/com.reloadly.topups-v1+json");

      using
      var httpClient = new HttpClient();
      var response = await httpClient.SendAsync(message);
      var responseBody = await response.Content.ReadAsStringAsync();
      var result = JsonConvert.DeserializeObject < dynamic > (responseBody);

      Console.WriteLine(result);
    }

  }
}

package main

import (
  "fmt"
  "net/http"
  "io/ioutil"
)

func main() {

  url := "https://topups.reloadly.com/operators/commissions"
  method := "GET"

  client := &http.Client {
  }
  req, err := http.NewRequest(method, url, nil)

  if err != nil {
    fmt.Println(err)
    return
  }
  req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN_HERE")
  req.Header.Add("Accept", "application/com.reloadly.topups-v1+json")

  res, err := client.Do(req)
  if err != nil {
    fmt.Println(err)
    return
  }
  defer res.Body.Close()

  body, err := ioutil.ReadAll(res.Body)
  if err != nil {
    fmt.Println(err)
    return
  }
  fmt.Println(string(body))
}

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
Request request = new Request.Builder()
  .url("https://topups.reloadly.com/operators/commissions")
  .method("GET", null)
  .addHeader("Authorization", "Bearer YOUR_ACCESS_TOKEN_HERE")
  .addHeader("Accept", "application/com.reloadly.topups-v1+json")
  .build();
Response response = client.newCall(request).execute();

var request = require('request');
var options = {
  'method': 'GET',
  'url': 'https://topups.reloadly.com/operators/commissions',
  'headers': {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN_HERE',
    'Accept': 'application/com.reloadly.topups-v1+json',
  }
};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://topups.reloadly.com/operators/commissions',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => array(
    'Authorization: Bearer YOUR_ACCESS_TOKEN_HERE',
    'Accept: application/com.reloadly.topups-v1+json',
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

import requests
import json

url = "https://topups.reloadly.com/operators/commissions"

payload={}
headers = {
  'Authorization': 'Bearer YOUR_ACCESS_TOKEN_HERE',
  'Accept': 'application/com.reloadly.topups-v1+json',
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

Response Parameters

Parameter

Type

Description

percentage

integer

Indicates the percentage discount for every top-up

international

Percentage

integer

Indicates the percentage discount for international top-ups

localPercentage

integer

Indicates the percentage discount for local top-ups

updatedAt

integer

Indicates the time the discount was first created by the operator

operatorId

string

Indicates the operator's ID

name

string

Indicates the operator's name

countryCode

string

Indicates the ISO code of the country where the operator is registered

data

boolean

Indicates if the operator has any existing data discounts

bundle

boolean

Indicates if the operator has any existing bundle discounts

status

boolean

Indicates if the operator has any existing discounts

Get commissions by operator ID

With the /operators/{operatorid}/commissions endpoint, you can retrieve the details of an active discount being carried out by an operator by making a request with the operator's ID

Commissions by operator ID

GET https://topups.reloadly.com/operators/{operatorid}/commissions

Path Parameters

Name

Type

Description

operatorId*

integer

The ID of the operator whose discount information is being retrieved

Headers

Name

Type

Description

Authorization*

string

Your access token is required as a bearer token in the request's header

{
  "operator":{
    "operatorId":173,
    "name":"Digicel Haiti",
    "countryCode":"HT",
    "status":true,
    "bundle":false,
    "data":false
  },
  "percentage":13,
  "internationalPercentage":13,
  "localPercentage":0.00,
  "updatedAt":"2020-02-08 19:32:43"
}

{
    "timeStamp": "2021-05-11 22:34:35",
    "message": "Full authentication is required to access this resource",
    "path": "/operators/173/commissions",
    "errorCode": "INVALID_TOKEN",
    "infoLink": null,
    "details": []
}

{
    "timestamp": "2021-05-11T22:33:12.101+0000",
    "status": 404,
    "error": "Not Found",
    "message": "No message available",
    "path": "/operators/173/commission"
}

Request samples

curl --location --request GET 'https://topups.reloadly.com/operators/173/commissions' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN_HERE' \
--header 'Accept: application/com.reloadly.topups-v1+json'

using System;
using System.Threading.Tasks;
using System.Net.Http;
using System.Text;
using Newtonsoft.Json;

namespace WebAPIClient {
  class Program {

    static async Task Main(string[] args) {
      await ApiCall();
    }

    private static async Task ApiCall() {

      var message = new HttpRequestMessage(HttpMethod.Get, "https://topups.reloadly.com/operators/173/commissions");

      message.Headers.TryAddWithoutValidation("Authorization", "Bearer YOUR_ACCESS_TOKEN_HERE");
      message.Headers.TryAddWithoutValidation("Accept", "application/com.reloadly.topups-v1+json");

      using
      var httpClient = new HttpClient();
      var response = await httpClient.SendAsync(message);
      var responseBody = await response.Content.ReadAsStringAsync();
      var result = JsonConvert.DeserializeObject < dynamic > (responseBody);

      Console.WriteLine(result);
    }

  }
}

package main

import (
  "fmt"
  "net/http"
  "io/ioutil"
)

func main() {

  url := "https://topups.reloadly.com/operators/173/commissions"
  method := "GET"

  client := &http.Client {
  }
  req, err := http.NewRequest(method, url, nil)

  if err != nil {
    fmt.Println(err)
    return
  }
  req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN_HERE")
  req.Header.Add("Accept", "application/com.reloadly.topups-v1+json")

  res, err := client.Do(req)
  if err != nil {
    fmt.Println(err)
    return
  }
  defer res.Body.Close()

  body, err := ioutil.ReadAll(res.Body)
  if err != nil {
    fmt.Println(err)
    return
  }
  fmt.Println(string(body))
}

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
Request request = new Request.Builder()
  .url("https://topups.reloadly.com/operators/173/commissions")
  .method("GET", null)
  .addHeader("Authorization", "Bearer YOUR_ACCESS_TOKEN_HERE")
  .addHeader("Accept", "application/com.reloadly.topups-v1+json")
  .build();
Response response = client.newCall(request).execute();

var myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer YOUR_ACCESS_TOKEN_HERE");
myHeaders.append("Accept", "application/com.reloadly.topups-v1+json");

var requestOptions = {
  method: 'GET',
  headers: myHeaders,
  redirect: 'follow'
};

fetch("https://topups.reloadly.com/operators/173/commissions", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://topups.reloadly.com/operators/173/commissions',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => array(
    'Authorization: Bearer YOUR_ACCESS_TOKEN_HERE',
    'Accept: application/com.reloadly.topups-v1+json'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

import requests
import json

url = "https://topups.reloadly.com/operators/173/commissions"

payload={}
headers = {
  'Authorization': 'Bearer YOUR_ACCESS_TOKEN_HERE',
  'Accept': 'application/com.reloadly.topups-v1+json'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

Response Parameters

Parameter

Type

Description

percentage

integer

Indicates the percentage discount for every top-up

international

Percentage

integer

Indicates the percentage discount for international top-ups

localPercentage

integer

Indicates the percentage discount for local top-ups

updatedAt

integer

Indicates the time the discount was first created by the operator

operatorId

string

Indicates the operator's ID

name

string

Indicates the operator's name

countryCode

string

Indicates the ISO code of the country where the operator is registered

data

boolean

Indicates if the operator has any existing data discounts

bundle

boolean

Indicates if the operator has any existing bundle discounts

status

boolean

Indicates if the operator has any existing discounts

Promotions

Get all promotions

Using the /promotions endpoint, you can get information on every operator running an active promotion on any of their products — airtime or data

Promotions

GET https://topups.reloadly.com/promotions

Query Parameters

Name

Type

Description

size

integer

The number of operators offering discounts to be retrieved on a page. Default value is 200

page

integer

The page of the list of operators offering promotions. Default value is 1

Headers

Name

Type

Description

Authorization*

string

Your access token is required as a bearer token in the request's header

{
  "content":[
    {
      "promotionId":1,
      "operatorId":129,
      "title":"Tigo El Salvador From 25 Jun 2018 00:00 To 25 July...",
      "title2":"Get 500 MB and 150 minutes for USA or Canada",
      "description":"For top ups of $10 or more, customer...",
      "startDate":"Mon, 25 Jun 2018 06:00:00 +0000",
      "endDate":"Tue, 26 Jun 2018 05:59:00 +0000",
      "denominations":"USD 10 and up",
      "localDenominations":null
    },
    {
      "promotionId":2,
      "operatorId":158,
      "title":"Tigo Guatemala From 30 Jun 2018 00:00 To 30 Jun",
      "title2":"Bonus 3x",
      "description":"Calls and SMS to USA, OnNet an...",
      "startDate":"Sat, 30 Jun 2018 06:00:00 +0000",
      "endDate":"Sun, 01 Jul 2018 05:59:00 +0000",
      "denominations":"USD 14 and up",
      "localDenominations":"GTQ 100.80 and up"
    }
  ],
  "pageable":{
    "sort":{
      "unsorted":true,
      "sorted":false
    },
    "pageSize":3,
    "pageNumber":0,
    "offset":0,
    "paged":true,
    "unpaged":false
  },
  "totalPages":15,
  "totalElements":44,
  "last":false,
  "sort":{
    "unsorted":true,
    "sorted":false
  },
  "first":true,
  "numberOfElements":3,
  "size":3,
  "number":0
}

{
  "timeStamp":"2021-05-11 21:14:00",
  "message":"Full authentication is required to access this resource",
  "path":"/promotions",
  "errorCode":"INVALID_TOKEN",
  "infoLink":null,
  "details":[
    
  ]
}

{
  "timestamp":"2021-05-18T11:35:57.291+0000",
  "status":404,
  "error":"Not Found",
  "message":"No message available",
  "path":"/promotion"
}

Request samples

curl --location --request GET 'https://topups.reloadly.com/promotions' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN_HERE' \
--header 'Accept: application/com.reloadly.topups-v1+json'

using System;
using System.Threading.Tasks;
using System.Net.Http;
using System.Text;
using Newtonsoft.Json;

namespace WebAPIClient {
  class Program {

    static async Task Main(string[] args) {
      await ApiCall();
    }

    private static async Task ApiCall() {

      var message = new HttpRequestMessage(HttpMethod.Get, "https://topups.reloadly.com/promotions");

      message.Headers.TryAddWithoutValidation("Authorization", "Bearer YOUR_ACCESS_TOKEN_HERE");
      message.Headers.TryAddWithoutValidation("Accept", "application/com.reloadly.topups-v1+json");

      using
      var httpClient = new HttpClient();
      var response = await httpClient.SendAsync(message);
      var responseBody = await response.Content.ReadAsStringAsync();
      var result = JsonConvert.DeserializeObject < dynamic > (responseBody);

      Console.WriteLine(result);
    }

  }
}

package main

import (
  "fmt"
  "net/http"
  "io/ioutil"
)

func main() {

  url := "https://topups.reloadly.com/promotions"
  method := "GET"

  client := &http.Client {
  }
  req, err := http.NewRequest(method, url, nil)

  if err != nil {
    fmt.Println(err)
    return
  }
  req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN_HERE")
  req.Header.Add("Accept", "application/com.reloadly.topups-v1+json")

  res, err := client.Do(req)
  if err != nil {
    fmt.Println(err)
    return
  }
  defer res.Body.Close()

  body, err := ioutil.ReadAll(res.Body)
  if err != nil {
    fmt.Println(err)
    return
  }
  fmt.Println(string(body))
}

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
Request request = new Request.Builder()
  .url("https://topups.reloadly.com/promotions")
  .method("GET", null)
  .addHeader("Authorization", "Bearer YOUR_ACCESS_TOKEN_HERE")
  .addHeader("Accept", "application/com.reloadly.topups-v1+json")
  .build();
Response response = client.newCall(request).execute();

var request = require('request');
var options = {
  'method': 'GET',
  'url': 'https://topups.reloadly.com/promotions',
  'headers': {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN_HERE',
    'Accept': 'application/com.reloadly.topups-v1+json',
  }
};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://topups.reloadly.com/promotions',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => array(
    'Authorization: Bearer YOUR_ACCESS_TOKEN_HERE',
    'Accept: application/com.reloadly.topups-v1+json'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

import requests
import json

url = "https://topups.reloadly.com/promotions"

payload={}
headers = {
  'Authorization': 'Bearer YOUR_ACCESS_TOKEN_HERE',
  'Accept': 'application/com.reloadly.topups-v1+json'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

Response parameters

Parameter

Type

Description

promotionId

integer

This is a unique identifier for the ongoing promotion

operatorId

integer

Indicates the ID of the operator offering the promotion

title1

string

Indicates the duration of the promotion and the name of the operator offering it

title2

string

Indicates additional information on the promotion

description

string

This indicates a summary of what the promotion is about

startDate

string

The date the promotion begins

endDate

string

The date the promotion ends

denominations

string

Indicates the top-up amounts that are eligible for the promotion

localDenominations

string

Indicates the local top-up amounts in the destination's currency that are eligible for the promotion

Get promotions by ID

With the /promotions/{promotionid} endpoint, you can fetch the details of a promotion by making a request with its ID

Promotions by ID

GET https://topups.reloadly.com/promotions/{promotionid}

Path Parameters

Name

Type

Description

promotionId

integer

The promotion's ID

Headers

Name

Type

Description

Authorization

string

Your access token is required as a bearer token in the request's header

{
  "promotionId":5,
  "operatorId":114,
  "title":"Movistar Ecuador From 01 Jan 2018 00:00 To 01 Jul 20",
  "title2":"Bonus 2x",
  "description":"For top ups of USD$2.00 (EUR 5) or more",
  "startDate":"Mon, 01 Jan 2018 05:00:00 +0000",
  "endDate":"Mon, 02 Jul 2018 04:59:00 +0000",
  "denominations":"USD 2 and up",
  "localDenominations":null
}

{
  "timeStamp":"2021-05-18 14:27:36",
  "message":"Full authentication is required to access this resource",
  "path":"/promotions/6984",
  "errorCode":"INVALID_TOKEN",
  "infoLink":null,
  "details":[
    
  ]
}

{
  "timestamp":"2021-05-18T15:29:50.022+0000",
  "status":404,
  "error":"Not Found",
  "message":"No message available",
  "path":"/promotion/6984"
}

Request samples

curl --location --request GET 'https://topups.reloadly.com/promotions/8652' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN_HERE' \
--header 'Accept: application/com.reloadly.topups-v1+json'

using System;
using System.Threading.Tasks;
using System.Net.Http;
using System.Text;
using Newtonsoft.Json;

namespace WebAPIClient {
  class Program {

    static async Task Main(string[] args) {
      await ApiCall();
    }

    private static async Task ApiCall() {

      var message = new HttpRequestMessage(HttpMethod.Get, "https://topups.reloadly.com/promotions/8652");

      message.Headers.TryAddWithoutValidation("Authorization", "Bearer YOUR_ACCESS_TOKEN_HERE");
      message.Headers.TryAddWithoutValidation("Accept", "application/com.reloadly.topups-v1+json");

      using
      var httpClient = new HttpClient();
      var response = await httpClient.SendAsync(message);
      var responseBody = await response.Content.ReadAsStringAsync();
      var result = JsonConvert.DeserializeObject < dynamic > (responseBody);

      Console.WriteLine(result);
    }

  }
}

package main

import (
  "fmt"
  "net/http"
  "io/ioutil"
)

func main() {

  url := "https://topups.reloadly.com/promotions/8652"
  method := "GET"

  client := &http.Client {
  }
  req, err := http.NewRequest(method, url, nil)

  if err != nil {
    fmt.Println(err)
    return
  }
  req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN_HERE")
  req.Header.Add("Accept", "application/com.reloadly.topups-v1+json")

  res, err := client.Do(req)
  if err != nil {
    fmt.Println(err)
    return
  }
  defer res.Body.Close()

  body, err := ioutil.ReadAll(res.Body)
  if err != nil {
    fmt.Println(err)
    return
  }
  fmt.Println(string(body))
}

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
Request request = new Request.Builder()
  .url("https://topups.reloadly.com/promotions/8652")
  .method("GET", null)
  .addHeader("Authorization", "Bearer YOUR_ACCESS_TOKEN_HERE")
  .addHeader("Accept", "application/com.reloadly.topups-v1+json")
  .build();
Response response = client.newCall(request).execute();

var request = require('request');
var options = {
  'method': 'GET',
  'url': 'https://topups.reloadly.com/promotions/8652',
  'headers': {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN_HERE',
    'Accept': 'application/com.reloadly.topups-v1+json',
  }
};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://topups.reloadly.com/promotions/8652',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => array(
    'Authorization: Bearer YOUR_ACCESS_TOKEN_HERE',
    'Accept: application/com.reloadly.topups-v1+json',
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

import requests
import json

url = "https://topups.reloadly.com/promotions/8652"

payload={}
headers = {
  'Authorization': 'Bearer YOUR_ACCESS_TOKEN_HERE',
  'Accept': 'application/com.reloadly.topups-v1+json'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

Response parameters

Parameter

Type

Description

promotionId

integer

The promotion ID. This is a unique identifier for the ongoing promotion

operatorId

integer

Indicates the ID of the operator offering the promotion

title1

string

Indicates the duration of the promotion and the name of the operator offering it

title2

string

Indicates additional information on the promotion

description

string

This indicates a summary of what the promotion is about

startDate

string

The date the promotion begins

endDate

string

The date the promotion ends

denominations

string

Indicates the top-up amounts that are eligible for the promotion

localDenominations

string

Indicates the local top-up amounts in the destination's currency that are eligible for the promotion

Get promotions by ISO code

With the /promotions/country-codes/{countrycode} endpoint, you can retrieve the promotions going on in a country by using its ISO code

Promotions by ISO code

GET https://topups.reloadly.com/promotions/country-codes/{countrycode}

Path Parameters

Name

Type

Description

countryCode

string

Indicates the ISO code of the country whose promotions need to be retrieved

Headers

Name

Type

Description

Authorization

string

Your access token is required as a bearer token in the request's header

[
  {
    "promotionId":7016,
    "operatorId":121,
    "title":"Digicel El Salvador From 07 Feb 2020 00:00 To 31 Dec 2020 23:59 (GMT-06:00)",
    "title2":"Bonus 5x",
    "description":"Imparable $7.00: 4 GB (from April 11th) + WhatsApp",
    "startDate":"Fri, 05 Apr 2019 06:00:00 +0000",
    "endDate":"Fri, 01 May 2020 05:59:00 +0000",
    "denominations":"USD 7, 10, 15 and 20",
    "localDenominations":null
  },
  {
    "promotionId":5462,
    "operatorId":128,
    "title":"Tigo El Salvador From 05 Apr 2019 00:00 To 30 Apr 2020 23:59",
    "title2":"Paquetigos Imparables",
    "description":"Imparable $7.00: 4 GB (from April 11th) + WhatsApp",
    "startDate":"Fri, 05 Apr 2019 06:00:00 +0000",
    "endDate":"Fri, 01 May 2020 05:59:00 +0000",
    "denominations":"USD 7, 10, 15 and 20",
    "localDenominations":null
  }
]

{
  "timeStamp":"2021-06-09 19:23:18",
  "message":"Full authentication is required to access this resource",
  "path":"/promotions/country-codes/NG",
  "errorCode":"INVALID_TOKEN",
  "infoLink":null,
  "details":[
    
  ]
}

{
  "timestamp":"2021-06-09T20:19:59.418+0000",
  "status":404,
  "error":"Not Found",
  "message":"No message available",
  "path":"/promotion/country-code/NG"
}

Request samples

curl --location --request GET 'https://topups.reloadly.com/promotions/country-codes/SV' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN_HERE' \
--header 'Accept: application/com.reloadly.topups-v1+json'

using System;
using System.Threading.Tasks;
using System.Net.Http;
using System.Text;
using Newtonsoft.Json;

namespace WebAPIClient {
  class Program {

    static async Task Main(string[] args) {
      await ApiCall();
    }

    private static async Task ApiCall() {

      var message = new HttpRequestMessage(HttpMethod.Get, "https://topups.reloadly.com/promotions/country-codes/SV");

      message.Headers.TryAddWithoutValidation("Authorization", "Bearer YOUR_ACCESS_TOKEN_HERE");
      message.Headers.TryAddWithoutValidation("Accept", "application/com.reloadly.topups-v1+json");

      using
      var httpClient = new HttpClient();
      var response = await httpClient.SendAsync(message);
      var responseBody = await response.Content.ReadAsStringAsync();
      var result = JsonConvert.DeserializeObject < dynamic > (responseBody);

      Console.WriteLine(result);
    }

  }
}

package main

import (
  "fmt"
  "net/http"
  "io/ioutil"
)

func main() {

  url := "https://topups.reloadly.com/promotions/country-codes/SV"
  method := "GET"

  client := &http.Client {
  }
  req, err := http.NewRequest(method, url, nil)

  if err != nil {
    fmt.Println(err)
    return
  }
  req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN_HERE")
  req.Header.Add("Accept", "application/com.reloadly.topups-v1+json")

  res, err := client.Do(req)
  if err != nil {
    fmt.Println(err)
    return
  }
  defer res.Body.Close()

  body, err := ioutil.ReadAll(res.Body)
  if err != nil {
    fmt.Println(err)
    return
  }
  fmt.Println(string(body))
}

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
Request request = new Request.Builder()
  .url("https://topups.reloadly.com/promotions/country-codes/SV")
  .method("GET", null)
  .addHeader("Authorization", "Bearer YOUR_ACCESS_TOKEN_HERE")
  .addHeader("Accept", "application/com.reloadly.topups-v1+json")
  .build();
Response response = client.newCall(request).execute();

var request = require('request');
var options = {
  'method': 'GET',
  'url': 'https://topups.reloadly.com/promotions/country-codes/SV',
  'headers': {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN_HERE',
    'Accept': 'application/com.reloadly.topups-v1+json',
  }
};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://topups.reloadly.com/promotions/country-codes/SV',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => array(
    'Authorization: Bearer YOUR_ACCESS_TOKEN_HERE',
    'Accept: application/com.reloadly.topups-v1+json'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

import requests
import json

url = "https://topups.reloadly.com/promotions/country-codes/SV"

payload={}
headers = {
  'Authorization': 'Bearer YOUR_ACCESS_TOKEN_HERE',
  'Accept': 'application/com.reloadly.topups-v1+json'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

Response parameters

Parameter

Type

Description

promotionId

integer

The promotion ID. This is a unique identifier for the ongoing promotion

operatorId

integer

Indicates the ID of the operator offering the promotion

title1

string

Indicates the duration of the promotion and the name of the operator offering it

title2

string

Indicates additional information on the promotion

description

string

This indicates a summary of what the promotion is about

startDate

string

The date the promotion begins

endDate

string

The date the promotion ends

denominations

string

Indicates the top-up amounts that are eligible for the promotion

localDenominations

string

Indicates the local top-up amounts in the destination's currency that are eligible for the promotion

Get promotion by operator ID

Using the /promotions/operators/{operatorid} endpoint, you can get the details of every promotion on an operator

Promotion by operator ID

GET https://topups.reloadly.com/promotions/operators/{operatorid}

Path Parameters

Name

Type

Description

operatorId

integer

The ID of the operator whose promotion information is being retrieved

Headers

Name

Type

Description

Authorization

string

Your access token is required as a bearer token in the request's header

[
  {
    "id":8934,
    "promotionId":8934,
    "operatorId":344,
    "title":"Glo Mobile Nigeria From 06 Jun 2021 00:00 To 31 Jul 2021 23:59 (GMT+01:00)",
    "title2":"Bonus 400% and 500%",
    "description":"<u><strong>Glo Nigeria Promotions!</strong></u><br /><strong>400% and 500% bonus for International top Ups today!&nbsp;</strong><br /><br /><strong>How it works</strong><br />If a customer wants to get 4X bonus, the customer will recharge N125 (N100 +25) to get N500, or recharge N1025 (N1000 + 25) to get N4100<br />&nbsp;<br />If a customer wants to get 5X bonus, the customer will recharge N120 (N100 +20) to get N600, or recharge N2020 (N2000 + 20) to get N10,100<br />&nbsp;<br />The addition of N25 or N20 to the original amount (N100 or N500 or N2000) is what triggers the application of the bonus to the recipient.<br /><br /><strong>Terms and Conditions</strong><br />* Bonus is valid for 14 and 30 days on specific denominations (See table below)<br />*&nbsp;Bonus Airtime can only be used to make local calls to all network, but not subscribe for data bundles.<br />* To check your 4X Bonus account dial #122*30#<br />&nbsp;* To check your 5X Bonus account dial #555*5#<br /><br /><img alt=\"\" src=\"https://i.postimg.cc/5NF3gKps/Glo-Voice-Bonus-Products.png\" style=\"height:423px; width:752px\" />",
    "startDate":"2021-06-06 03:00:00",
    "endDate":"2021-08-01 02:59:00",
    "denominations":null,
    "localDenominations":null
  }
]

{
  "timeStamp":"2021-06-09 20:13:16",
  "message":"Full authentication is required to access this resource",
  "path":"/promotions/operators/344",
  "errorCode":"INVALID_TOKEN",
  "infoLink":null,
  "details":[
    
  ]
}

{
  "timestamp":"2021-06-09T20:17:45.467+0000",
  "status":404,
  "error":"Not Found",
  "message":"No message available",
  "path":"/promotions/operator/344"
}

Request samples

curl --location --request GET 'https://topups.reloadly.com/promotions/operators/129' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN_HERE' \
--header 'Accept: application/com.reloadly.topups-v1+json'

using System;
using System.Threading.Tasks;
using System.Net.Http;
using System.Text;
using Newtonsoft.Json;

namespace WebAPIClient {
  class Program {

    static async Task Main(string[] args) {
      await ApiCall();
    }

    private static async Task ApiCall() {

      var message = new HttpRequestMessage(HttpMethod.Get, "https://topups.reloadly.com/promotions/operators/129");

      message.Headers.TryAddWithoutValidation("Authorization", "Bearer YOUR_ACCESS_TOKEN_HERE");
      message.Headers.TryAddWithoutValidation("Accept", "application/com.reloadly.topups-v1+json");

      using
      var httpClient = new HttpClient();
      var response = await httpClient.SendAsync(message);
      var responseBody = await response.Content.ReadAsStringAsync();
      var result = JsonConvert.DeserializeObject < dynamic > (responseBody);

      Console.WriteLine(result);
    }

  }
}

package main

import (
  "fmt"
  "net/http"
  "io/ioutil"
)

func main() {

  url := "https://topups.reloadly.com/promotions/operators/129"
  method := "GET"

  client := &http.Client {
  }
  req, err := http.NewRequest(method, url, nil)

  if err != nil {
    fmt.Println(err)
    return
  }
  req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN_HERE")
  req.Header.Add("Accept", "application/com.reloadly.topups-v1+json")

  res, err := client.Do(req)
  if err != nil {
    fmt.Println(err)
    return
  }
  defer res.Body.Close()

  body, err := ioutil.ReadAll(res.Body)
  if err != nil {
    fmt.Println(err)
    return
  }
  fmt.Println(string(body))
}

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
Request request = new Request.Builder()
  .url("https://topups.reloadly.com/promotions/operators/129")
  .method("GET", null)
  .addHeader("Authorization", "Bearer YOUR_ACCESS_TOKEN_HERE")
  .addHeader("Accept", "application/com.reloadly.topups-v1+json")
  .build();
Response response = client.newCall(request).execute();

var request = require('request');
var options = {
  'method': 'GET',
  'url': 'https://topups.reloadly.com/promotions/operators/129',
  'headers': {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN_HERE',
    'Accept': 'application/com.reloadly.topups-v1+json',
  }
};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://topups.reloadly.com/promotions/operators/129',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => array(
    'Authorization: Bearer YOUR_ACCESS_TOKEN_HERE',
    'Accept: application/com.reloadly.topups-v1+json'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

import requests
import json

url = "https://topups.reloadly.com/promotions/operators/129"

payload={}
headers = {
  'Authorization': 'Bearer YOUR_ACCESS_TOKEN_HERE',
  'Accept': 'application/com.reloadly.topups-v1+json'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

Response parameters

Parameter

Type

Description

promotionId

integer

The promotion ID. This is a unique identifier for the ongoing promotion

operatorId

integer

Indicates the ID of the operator offering the promotion

title1

string

Indicates the duration of the promotion and the name of the operator offering it

title2

string

Indicates additional information on the promotion

description

string

Indicates a summary of what the promotion is about

startDate

string

The date the promotion begins

endDate

string

The date the promotion ends

denominations

string

Indicates the top-up amounts that are eligible for the promotion

localDenominations

string

Indicates the local top-up amounts in the destination's currency that are eligible for the promotion

Top-ups

Make a top-up

With the /topups endpoint, developers can make an airtime recharge to any mobile number within the operators covered by Reloadly

Top-up

POST https://topups.reloadly.com/topups

Headers

Name

Type

Description

Authorization*

string

Your access token is required as a bearer token in the request's header

Request Body

Name

Type

Description

operatorId*

integer

Indicates the operator's ID

amount*

integer

Indicates the amount of airtime or data that is to be recharged

useLocalAmount

boolean

Indicates if the recharge is to be made in the operator's local currency. Default is false.

customIdentifier

string

Indicates the transaction reference of the recharge. Note: Each transaction reference is to be unique. Once a reference has been used for a top-up transaction, it cannot be reused.

recipientEmail

string

This is the recipient's email address. It is required when the operator is Nauta Cuba. It supports only two email domains: 1. @nauta.com.cu 2. @nauta.co.cu

recipientPhone*

object

Indicates an object containing the receiver's country code and mobile number

senderPhone

object

Indicates an object containing the sender's country code and mobile number

countryCode*

string

Indicates the ISO code of the receiver's or sender's country

number*

string

Indicates the mobile number of the top-up receiver or sender

{
    "transactionId": 26523,
    "status": "SUCCESSFUL",
    "operatorTransactionId": null,
    "customIdentifier": "This is example identifier",
    "recipientPhone": "447951631337",
    "recipientEmail": null,
    "senderPhone": "11231231231",
    "countryCode": "GB",
    "operatorId": 535,
    "operatorName": "EE PIN England",
    "discount": 63.37,
    "discountCurrencyCode": "NGN",
    "requestedAmount": 3168.4,
    "requestedAmountCurrencyCode": "NGN",
    "deliveredAmount": 5,
    "deliveredAmountCurrencyCode": "GBP",
    "transactionDate": "2022-01-26 03:19:16",
    "pinDetail": {
        "serial": "558111",
        "info1": "DIAL *611",
        "info2": "DIAL *611",
        "info3": "Dial *233* and PIN #",
        "value": null,
        "code": "773709733097662",
        "ivr": "1-888-888-8888",
        "validity": "30 days"
    },
    "balanceInfo": {
        "oldBalance": 60387.41,
        "newBalance": 57282.38,
        "cost": 3105.03,
        "currencyCode": "NGN",
        "currencyName": "Nigerian Naira",
        "updatedAt": "2022-01-26 08:19:16"
    }
}

{
  "timeStamp":"2021-05-31 18:38:03",
  "message":"Recipient phone number is not valid",
  "path":"/topups",
  "errorCode":"INVALID_RECIPIENT_PHONE",
  "infoLink":null,
  "details":[
    
  ]
}

{
  "timeStamp":"2021-05-31 17:48:18",
  "message":"Full authentication is required to access this resource",
  "path":"/topup",
  "errorCode":"INVALID_TOKEN",
  "infoLink":null,
  "details":[
    
  ]
}

Request samples

curl --location --request POST 'https://topups.reloadly.com/topups' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN_HERE' \
--header 'Accept: application/com.reloadly.topups-v1+json' \
--header 'Content-Type: application/json' \
--data-raw '{
	"operatorId":"341",
	"amount":"10",
	"useLocalAmount": false,
	"customIdentifier": "This is example identifier 092",
	"recipientPhone": {
		"countryCode": "NG",
		"number": "08147658721"
	},
	"senderPhone": {
		"countryCode": "CA",
		"number": "1231231231"
	}
}'

using System;
using System.Threading.Tasks;
using System.Net.Http;
using System.Text;
using Newtonsoft.Json;

namespace WebAPIClient {
  class Program {

    static async Task Main(string[] args) {
      await ApiCall();
    }

    private static async Task ApiCall() {

      var json = JsonConvert.SerializeObject(new {
          operatorId = "341",
          amount = "10",
          useLocalAmount = false,
          customIdentifier = "This is a sample",
          recipientPhone = new {
            countryCode = "NG", 
            number = "08147658721"
          }
      });

      var message = new HttpRequestMessage(HttpMethod.Post, "https://topups.reloadly.com/topups"){
        Content = new StringContent(json, Encoding.UTF8, "application/json")
      };

      message.Headers.TryAddWithoutValidation("Authorization", "Bearer YOUR_ACCESS_TOKEN_HERE");
      message.Headers.TryAddWithoutValidation("Accept", "application/com.reloadly.topups-v1+json");

      using
      var httpClient = new HttpClient();
      var response = await httpClient.SendAsync(message);
      var responseBody = await response.Content.ReadAsStringAsync();
      var result = JsonConvert.DeserializeObject < dynamic > (responseBody);

      Console.WriteLine(result);
    }

  }
}

package main

import (
  "fmt"
  "strings"
  "net/http"
  "io/ioutil"
)

func main() {

  url := "https://topups.reloadly.com/topups"
  method := "POST"

  payload := strings.NewReader(`{
	"operatorId":"341",
	"amount":"10",
	"useLocalAmount": false,
	"customIdentifier": "This is example identifier 092",
	"recipientPhone": {
		"countryCode": "NG",
		"number": "08147658721"
	},
	"senderPhone": {
		"countryCode": "CA",
		"number": "1231231231"
	}
}`)

  client := &http.Client {
  }
  req, err := http.NewRequest(method, url, payload)

  if err != nil {
    fmt.Println(err)
    return
  }
  req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN_HERE")
  req.Header.Add("Accept", "application/com.reloadly.topups-v1+json")
  req.Header.Add("Content-Type", "application/json")

  res, err := client.Do(req)
  if err != nil {
    fmt.Println(err)
    return
  }
  defer res.Body.Close()

  body, err := ioutil.ReadAll(res.Body)
  if err != nil {
    fmt.Println(err)
    return
  }
  fmt.Println(string(body))
}

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n\t\"operatorId\":\"685\",\n\t\"amount\":\"10\",\n\t\"customIdentifier\": \"This is example identifier 092\",\n\t\"recipientPhone\": {\n\t\t\"countryCode\": \"NG\",\n\t\t\"number\": \"08147658721\"\n\t},\n\t\"senderPhone\": {\n\t\t\"countryCode\": \"CA\",\n\t\t\"number\": \"1231231231\"\n\t}\n}");
Request request = new Request.Builder()
  .url("https://topups.reloadly.com/topups")
  .method("POST", body)
  .addHeader("Authorization", "Bearer YOUR_ACCESS_TOKEN_HERE")
  .addHeader("Accept", "application/com.reloadly.topups-v1+json")
  .addHeader("Content-Type", "application/json")
  .build();
Response response = client.newCall(request).execute();

var request = require('request');
var options = {
  'method': 'POST',
  'url': 'https://topups.reloadly.com/topups',
  'headers': {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN_HERE',
    'Accept': 'application/com.reloadly.topups-v1+json',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "operatorId": "341",
    "amount": "10",
    "useLocalAmount": false,
    "customIdentifier": "This is example identifier 092",
    "recipientPhone": {
      "countryCode": "NG",
      "number": "08147658721"
    },
    "senderPhone": {
      "countryCode": "CA",
      "number": "1231231231"
    }
  })

};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://topups.reloadly.com/topups',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
	"operatorId":"341",
	"amount":"10",
	"useLocalAmount": false,
	"customIdentifier": "This is example identifier 092",
	"recipientPhone": {
		"countryCode": "NG",
		"number": "08147658721"
	},
	"senderPhone": {
		"countryCode": "CA",
		"number": "1231231231"
	}
}',
  CURLOPT_HTTPHEADER => array(
    'Authorization: Bearer YOUR_ACCESS_TOKEN_HERE',
    'Accept: application/com.reloadly.topups-v1+json',
    'Content-Type: application/json'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

import requests
import json

url = "https://topups.reloadly.com/topups"

payload = json.dumps({
  "operatorId": "341",
  "amount": "10",
  "useLocalAmount": False,
  "customIdentifier": "This is example identifier 092",
  "recipientPhone": {
    "countryCode": "NG",
    "number": "08147658721"
  },
  "senderPhone": {
    "countryCode": "CA",
    "number": "1231231231"
  }
})
headers = {
  'Authorization': 'Bearer YOUR_ACCESS_TOKEN_HERE',
  'Accept': 'application/com.reloadly.topups-v1+json',
  'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

Request samples for Nauta Cuba top-ups

curl --location --request POST 'https://topups.reloadly.com/topups' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN_HERE' \
--header 'Accept: application/com.reloadly.topups-v1+json' \
--header 'Content-Type: application/json' \
--data-raw '{
	"operatorId":"685",
	"amount":"10",
	"customIdentifier": "This is example identifier 092",
	"recipientEmail": "anyone@nauta.com.cu",
	"senderPhone": {
		"countryCode": "CA",
		"number": "1231231231"
	}
}'

using System;
using System.Threading.Tasks;
using System.Net.Http;
using System.Text;
using Newtonsoft.Json;

namespace WebAPIClient {
  class Program {

    static async Task Main(string[] args) {
      await ApiCall();
    }

    private static async Task ApiCall() {

      var json = JsonConvert.SerializeObject(new {
        operatorId = "685",
          amount = "10",
          customIdentifier = "This is a sample",
          recipientEmail = "peter@nauta.com.cu"
          senderPhone = new {
            countryCode = "CA", 
            number = "1231231231"
          }
      });

      var message = new HttpRequestMessage(HttpMethod.Post, "https://topups.reloadly.com/topups"){
        Content = new StringContent(json, Encoding.UTF8, "application/json")
      };

      message.Headers.TryAddWithoutValidation("Authorization", "Bearer YOUR_ACCESS_TOKEN_HERE");
      message.Headers.TryAddWithoutValidation("Accept", "application/com.reloadly.topups-v1+json");

      using
      var httpClient = new HttpClient();
      var response = await httpClient.SendAsync(message);
      var responseBody = await response.Content.ReadAsStringAsync();
      var result = JsonConvert.DeserializeObject < dynamic > (responseBody);

      Console.WriteLine(result);
    }

  }
}

package main

import (
  "fmt"
  "strings"
  "net/http"
  "io/ioutil"
)

func main() {

  url := "https://topups.reloadly.com/topups"
  method := "POST"

  payload := strings.NewReader(`{
	"operatorId":"685",
	"amount":"10",
	"customIdentifier": "This is example identifier 092",
	"recipientEmail": "peter@nauta.com.cu",
	"senderPhone": {
		"countryCode": "CA",
		"number": "1231231231"
	}
}`)

  client := &http.Client {
  }
  req, err := http.NewRequest(method, url, payload)

  if err != nil {
    fmt.Println(err)
    return
  }
  req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN_HERE")
  req.Header.Add("Accept", "application/com.reloadly.topups-v1+json")
  req.Header.Add("Content-Type", "application/json")

  res, err := client.Do(req)
  if err != nil {
    fmt.Println(err)
    return
  }
  defer res.Body.Close()

  body, err := ioutil.ReadAll(res.Body)
  if err != nil {
    fmt.Println(err)
    return
  }
  fmt.Println(string(body))
}

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n\t\"operatorId\":\"685\",\n\t\"amount\":\"10\",\n\t\"customIdentifier\": \"This is example identifier 092\",\n\t\"recipientEmail\": \"peter@nauta.com.cu\",\n\t\"senderPhone\": {\n\t\t\"countryCode\": \"CA\",\n\t\t\"number\": \"1231231231\"\n\t}\n}");
Request request = new Request.Builder()
  .url("https://topups.reloadly.com/topups")
  .method("POST", body)
  .addHeader("Authorization", "Bearer YOUR_ACCESS_TOKEN_HERE")
  .addHeader("Accept", "application/com.reloadly.topups-v1+json")
  .addHeader("Content-Type", "application/json")
  .build();
Response response = client.newCall(request).execute();

var request = require('request');
var options = {
  'method': 'POST',
  'url': 'https://topups.reloadly.com/topups',
  'headers': {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN_HERE',
    'Accept': 'application/com.reloadly.topups-v1+json',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "operatorId": "685",
    "amount": "10",
    "customIdentifier": "This is example identifier 092",
    "recipientEmail": "peter@nauta.com.cu",
    "senderPhone": {
      "countryCode": "CA",
      "number": "1231231231"
    }
  })

};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://topups.reloadly.com/topups',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
	"operatorId":"685",
	"amount":"10",
	"customIdentifier": "This is example identifier 092",
	"recipientEmail": "peter@nauta.com.cu",
	"senderPhone": {
		"countryCode": "CA",
		"number": "1231231231"
	}
}',
  CURLOPT_HTTPHEADER => array(
    'Authorization: Bearer YOUR_ACCESS_TOKEN_HERE',
    'Accept: application/com.reloadly.topups-v1+json',
    'Content-Type: application/json'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

import requests
import json

url = "https://topups.reloadly.com/topups"

payload = json.dumps({
  "operatorId": "685",
  "amount": "10",
  "customIdentifier": "This is example identifier 092",
  "recipientEmail": "peter@nauta.com.cu",
  "senderPhone": {
    "countryCode": "CA",
    "number": "1231231231"
  }
})
headers = {
  'Authorization': 'Bearer YOUR_ACCESS_TOKEN_HERE',
  'Accept': 'application/com.reloadly.topups-v1+json',
  'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

Response parameters

Parameter

Type

Description

transactionId

integer

Indicates the unique ID of a top-up

status

string

Indicates the status of a top-up. Note: SUCCESSFUL: This applies when the top up is successfully made. PROCESSING: This applies while the top up is still being verified from the operator's end. REFUNDED: This applies once the top up is not processed successfully from the airtime operator's end. In this instance, any funds debited from a user's wallet while attempting to make the top-up are automatically refunded.

operator

TransactionId

string

Indicates the transaction ID assigned by the operator of the receiving mobile number

customIdentifier

string

This is the top-up's reference that is to be assigned by the sender

recipientPhone

string

This indicates the top-up receiver's mobile number

recipientEmail

string

This indicates the top-up receiver's email (only applicable to Nauta Cuba top-ups)

senderPhone

string

This indicates the sender's mobile number

countryCode

string

Indicates the ISO code of the country where the operator is registered

operatorId

integer

The ID of the receiving mobile number's operator

operatorName

string

The name of the receiving mobile number's operator

discount

integer

Indicates if there was a discount on the top-up made and at what rate

discountCurrency

Code

string

Indicates the currency code of the receiving mobile number

requestedAmount

integer

Indicates the top-up amount sent by the originating account

requestedAmount

CurrencyCode

string

Indicates the currency code of the originating account

deliveredAmount

integer

Indicates the top-up amount received by the receiving mobile number

deliveredAmount

CurrencyCode

string

Indicates the currency in which the top-up was delivered

transactionDate

string

Indicates the date and time the top-up was made

pinDetail

object

This contains information on how to process the PIN on the physical SIM. Note that this is only for operators that support PIN Top-up

serial

string

Indicates the serial code of the PIN top-up

info

string

Indicates information on how to utilize the top-up

value

string

Indicates additional information on the PIN

code

string

Indicates the code that is to be used to activate the top-up

ivr

string

Indicates the number to call for an interactive voice response

validity

string

Indicates the validity of the PIN

balanceInfo

object

Contains information of the top-up sender's account balance

oldBalance

integer

Indicates the balance of the sender's account before the top-up was made

newBalance

integer

Indicates the balance of the sender's account after the top-up was made

cost

integer

Indicates the amount deducted from your account for the top-up.

currencyCode

string

Indicates the currency code of the sender's account

currencyName

string

Indicates the currency denomination of the sender's account

updatedAt

string

Indicates the time the account's balance was updated to reflect the last top-up made

Make an asynchronous top-up

Using the /topup-async endpoint, developers have a faster way to view the status of every top-up that they make in real-time

For every asynchronous top-up that is made, a transaction ID is the only parameter returned as a response. This transaction ID can be used to confirm if the top-up request is successful, still processing, or failed

Async top-up

POST https://topups.reloadly.com/topups-async

Headers

Name

Type

Description

Authorization*

string

Your access token is required as a bearer token in the request's header

Request Body

Name

Type

Description

operatorId*

integer

Indicates the operator's ID

amount*

integer

Indicates the amount of airtime or data that is to be recharged

useLocalAmount

boolean

Indicates if the recharge is to be made in the operator's local currency. Default is false. This option is only available for operators that support local top-ups

customIdentifier

string

Indicates the transaction reference of the recharge Note: Each transaction reference is to be unique. Once a reference has been used for a top-up transaction, it cannot be reused.

recipientEmail

string

This is the recipient's email address. It is required when the operator is Nauta Cuba It supports only two email domains: 1. @nauta.com.cu 2. @nauta.co.cu

receiverPhone*

object

Indicates an object containing the receiver's country code and mobile number

senderPhone*

object

Indicates an object containing the sender's country code and mobile number

countryCode*

string

Indicates the ISO code of the receiver's or sender's country. For top-up senders, this parameter is optional

number*

string

Indicates the mobile number of the top-up receiver or sender. For top-up senders, this parameter is optional

{
  "transactionId": 282571
}

{
  "timeStamp":"2021-06-08 12:00:54",
  "message":"Full authentication is required to access this resource",
  "path":"/topups-async",
  "errorCode":"INVALID_TOKEN",
  "infoLink":null,
  "details":[
    
  ]
}

{
  "timestamp":"2021-06-08T12:20:51.818+0000",
  "status":404,
  "error":"Not Found",
  "message":"No message available",
  "path":"/topups-asyn"
}

Request samples

curl --location --request POST 'https://topups.reloadly.com/topups-async' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN_HERE' \
--header 'Accept: application/com.reloadly.topups-v1+json' \
--header 'Content-Type: application/json' \
--data-raw '{
	"operatorId":"341",
	"amount":"10",
	"useLocalAmount": false,
	"customIdentifier": "This is example identifier 092",
	"recipientPhone": {
		"countryCode": "NG",
		"number": "08147658721"
	},
	"senderPhone": {
		"countryCode": "CA",
		"number": "1231231231"
	}
}'

using System;
using System.Threading.Tasks;
using System.Net.Http;
using System.Text;
using Newtonsoft.Json;

namespace WebAPIClient {
  class Program {

    static async Task Main(string[] args) {
      await ApiCall();
    }

    private static async Task ApiCall() {

      var json = JsonConvert.SerializeObject(new {
          operatorId = "341",
          amount = "10",
          useLocalAmount = false,
          customIdentifier = "This is a sample",
          recipientPhone = new {
            countryCode = "NG", 
            number = "08147658721"
          }
      });

      var message = new HttpRequestMessage(HttpMethod.Post, "https://topups.reloadly.com/topups-async"){
        Content = new StringContent(json, Encoding.UTF8, "application/json")
      };

      message.Headers.TryAddWithoutValidation("Authorization", "Bearer YOUR_ACCESS_TOKEN_HERE");
      message.Headers.TryAddWithoutValidation("Accept", "application/com.reloadly.topups-v1+json");

      using
      var httpClient = new HttpClient();
      var response = await httpClient.SendAsync(message);
      var responseBody = await response.Content.ReadAsStringAsync();
      var result = JsonConvert.DeserializeObject < dynamic > (responseBody);

      Console.WriteLine(result);
    }

  }
}

package main

import (
  "fmt"
  "strings"
  "net/http"
  "io/ioutil"
)

func main() {

  url := "https://topups.reloadly.com/topups-async"
  method := "POST"

  payload := strings.NewReader(`{
	"operatorId":"341",
	"amount":"10",
	"useLocalAmount": false,
	"customIdentifier": "This is example identifier 092",
	"recipientPhone": {
		"countryCode": "NG",
		"number": "08147658721"
	},
	"senderPhone": {
		"countryCode": "CA",
		"number": "1231231231"
	}
}`)

  client := &http.Client {
  }
  req, err := http.NewRequest(method, url, payload)

  if err != nil {
    fmt.Println(err)
    return
  }
  req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN_HERE")
  req.Header.Add("Accept", "application/com.reloadly.topups-v1+json")
  req.Header.Add("Content-Type", "application/json")

  res, err := client.Do(req)
  if err != nil {
    fmt.Println(err)
    return
  }
  defer res.Body.Close()

  body, err := ioutil.ReadAll(res.Body)
  if err != nil {
    fmt.Println(err)
    return
  }
  fmt.Println(string(body))
}

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n\t\"operatorId\":\"685\",\n\t\"amount\":\"10\",\n\t\"customIdentifier\": \"This is example identifier 092\",\n\t\"recipientPhone\": {\n\t\t\"countryCode\": \"NG\",\n\t\t\"number\": \"08147658721\"\n\t},\n\t\"senderPhone\": {\n\t\t\"countryCode\": \"CA\",\n\t\t\"number\": \"1231231231\"\n\t}\n}");
Request request = new Request.Builder()
  .url("https://topups.reloadly.com/topups-async")
  .method("POST", body)
  .addHeader("Authorization", "Bearer YOUR_ACCESS_TOKEN_HERE")
  .addHeader("Accept", "application/com.reloadly.topups-v1+json")
  .addHeader("Content-Type", "application/json")
  .build();
Response response = client.newCall(request).execute();

var request = require('request');
var options = {
  'method': 'POST',
  'url': 'https://topups.reloadly.com/topups-async',
  'headers': {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN_HERE',
    'Accept': 'application/com.reloadly.topups-v1+json',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "operatorId": "341",
    "amount": "10",
    "useLocalAmount": false,
    "customIdentifier": "This is example identifier 092",
    "recipientPhone": {
      "countryCode": "NG",
      "number": "08147658721"
    },
    "senderPhone": {
      "countryCode": "CA",
      "number": "1231231231"
    }
  })

};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://topups.reloadly.com/topups-async',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
	"operatorId":"341",
	"amount":"10",
	"useLocalAmount": false,
	"customIdentifier": "This is example identifier 092",
	"recipientPhone": {
		"countryCode": "NG",
		"number": "08147658721"
	},
	"senderPhone": {
		"countryCode": "CA",
		"number": "1231231231"
	}
}',
  CURLOPT_HTTPHEADER => array(
    'Authorization: Bearer YOUR_ACCESS_TOKEN_HERE',
    'Accept: application/com.reloadly.topups-v1+json',
    'Content-Type: application/json'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

import requests
import json

url = "https://topups.reloadly.com/topups-async"

payload = json.dumps({
  "operatorId": "341",
  "amount": "10",
  "useLocalAmount": False,
  "customIdentifier": "This is example identifier 092",
  "recipientPhone": {
    "countryCode": "NG",
    "number": "08147658721"
  },
  "senderPhone": {
    "countryCode": "CA",
    "number": "1231231231"
  }
})
headers = {
  'Authorization': 'Bearer YOUR_ACCESS_TOKEN_HERE',
  'Accept': 'application/com.reloadly.topups-v1+json',
  'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

Request samples for Nauta Cuba top-ups

curl --location --request POST 'https://topups.reloadly.com/topups-async' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN_HERE' \
--header 'Accept: application/com.reloadly.topups-v1+json' \
--header 'Content-Type: application/json' \
--data-raw '{
	"operatorId":"685",
	"amount":"10",
	"customIdentifier": "This is example identifier 092",
	"recipientEmail": "peter@nauta.com.cu",
	"senderPhone": {
		"countryCode": "CA",
		"number": "1231231231"
	}
}'

using System;
using System.Threading.Tasks;
using System.Net.Http;
using System.Text;
using Newtonsoft.Json;

namespace WebAPIClient {
  class Program {

    static async Task Main(string[] args) {
      await ApiCall();
    }

    private static async Task ApiCall() {

      var json = JsonConvert.SerializeObject(new {
        operatorId = "685",
          amount = "10",
          customIdentifier = "This is a sample",
          recipientEmail = "peter@nauta.com.cu"
          senderPhone = new {
            countryCode = "CA", 
            number = "1231231231"
          }
      });

      var message = new HttpRequestMessage(HttpMethod.Post, "https://topups.reloadly.com/topups-async"){
        Content = new StringContent(json, Encoding.UTF8, "application/json")
      };

      message.Headers.TryAddWithoutValidation("Authorization", "Bearer YOUR_ACCESS_TOKEN_HERE");
      message.Headers.TryAddWithoutValidation("Accept", "application/com.reloadly.topups-v1+json");

      using
      var httpClient = new HttpClient();
      var response = await httpClient.SendAsync(message);
      var responseBody = await response.Content.ReadAsStringAsync();
      var result = JsonConvert.DeserializeObject < dynamic > (responseBody);

      Console.WriteLine(result);
    }

  }
}

package main

import (
  "fmt"
  "strings"
  "net/http"
  "io/ioutil"
)

func main() {

  url := "https://topups.reloadly.com/topups-async"
  method := "POST"

  payload := strings.NewReader(`{
	"operatorId":"685",
	"amount":"10",
	"customIdentifier": "This is example identifier 092",
	"recipientEmail": "peter@nauta.com.cu",
	"senderPhone": {
		"countryCode": "CA",
		"number": "1231231231"
	}
}`)

  client := &http.Client {
  }
  req, err := http.NewRequest(method, url, payload)

  if err != nil {
    fmt.Println(err)
    return
  }
  req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN_HERE")
  req.Header.Add("Accept", "application/com.reloadly.topups-v1+json")
  req.Header.Add("Content-Type", "application/json")

  res, err := client.Do(req)
  if err != nil {
    fmt.Println(err)
    return
  }
  defer res.Body.Close()

  body, err := ioutil.ReadAll(res.Body)
  if err != nil {
    fmt.Println(err)
    return
  }
  fmt.Println(string(body))
}

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n\t\"operatorId\":\"685\",\n\t\"amount\":\"10\",\n\t\"customIdentifier\": \"This is example identifier 092\",\n\t\"recipientEmail\": \"peter@nauta.com.cu\",\n\t\"senderPhone\": {\n\t\t\"countryCode\": \"CA\",\n\t\t\"number\": \"1231231231\"\n\t}\n}");
Request request = new Request.Builder()
  .url("https://topups.reloadly.com/topups-async")
  .method("POST", body)
  .addHeader("Authorization", "Bearer YOUR_ACCESS_TOKEN_HERE")
  .addHeader("Accept", "application/com.reloadly.topups-v1+json")
  .addHeader("Content-Type", "application/json")
  .build();
Response response = client.newCall(request).execute();

var request = require('request');
var options = {
  'method': 'POST',
  'url': 'https://topups.reloadly.com/topups-async',
  'headers': {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN_HERE',
    'Accept': 'application/com.reloadly.topups-v1+json',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "operatorId": "685",
    "amount": "10",
    "customIdentifier": "This is example identifier 092",
    "recipientEmail": "peter@nauta.com.cu",
    "senderPhone": {
      "countryCode": "CA",
      "number": "1231231231"
    }
  })

};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://topups.reloadly.com/topups-async',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
	"operatorId":"685",
	"amount":"10",
	"customIdentifier": "This is example identifier 092",
	"recipientEmail": "peter@nauta.com.cu",
	"senderPhone": {
		"countryCode": "CA",
		"number": "1231231231"
	}
}',
  CURLOPT_HTTPHEADER => array(
    'Authorization: Bearer YOUR_ACCESS_TOKEN_HERE',
    'Accept: application/com.reloadly.topups-v1+json',
    'Content-Type: application/json'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

import requests
import json

url = "https://topups.reloadly.com/topups-async"

payload = json.dumps({
  "operatorId": "685",
  "amount": "10",
  "customIdentifier": "This is example identifier 092",
  "recipientEmail": "peter@nauta.com.cu",
  "senderPhone": {
    "countryCode": "CA",
    "number": "1231231231"
  }
})
headers = {
  'Authorization': 'Bearer YOUR_ACCESS_TOKEN_HERE',
  'Accept': 'application/com.reloadly.topups-v1+json',
  'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

Response parameters

Parameter

Type

Description

transactionId

integer

Indicates the unique ID of an asynchronous top-up which is used to confirm its status

Get the status of a top-up

With the /{{transactionId}}/status endpoint, the status of a top-up can be determined in real-time

Top-up status

GET https://topups.reloadly.com/topups/{{transactionId}}/status

Path Parameters

Name

Type

Description

transactionId*

integer

Indicates the transaction ID retrieved from an asynchronous top-up request

Headers

Name

Type

Description

Authorization*

string

Your access token is required as a bearer token in the request's header

{
    "transactionId": 26523,
    "status": "SUCCESSFUL",
    "operatorTransactionId": null,
    "customIdentifier": "This is example identifier",
    "recipientPhone": "447951631337",
    "recipientEmail": null,
    "senderPhone": "11231231231",
    "countryCode": "GB",
    "operatorId": 535,
    "operatorName": "EE PIN England",
    "discount": 63.37,
    "discountCurrencyCode": "NGN",
    "requestedAmount": 3168.4,
    "requestedAmountCurrencyCode": "NGN",
    "deliveredAmount": 5,
    "deliveredAmountCurrencyCode": "GBP",
    "transactionDate": "2022-01-26 03:19:16",
    "pinDetail": {
        "serial": "558111",
        "info1": "DIAL *611",
        "info2": "DIAL *611",
        "info3": "Dial *233* and PIN #",
        "value": null,
        "code": "773709733097662",
        "ivr": "1-888-888-8888",
        "validity": "30 days"
    },
    "balanceInfo": {
        "oldBalance": 60387.41,
        "newBalance": 57282.38,
        "cost": 3105.03,
        "currencyCode": "NGN",
        "currencyName": "Nigerian Naira",
        "updatedAt": "2022-01-26 08:19:16"
    }
}

{
  "code":null,
  "message":null,
  "status":"PROCESSING",
  "transaction":null
}

{
  "code": "SERVICE_TO_OPERATOR_TEMPORARILY_UNAVAILABLE",
  "message": "The transaction failed due to an outage and / or connection issue with the operator",
  "status": "REFUNDED",
  "transaction": null
}

{
   "code":"PROVIDER_INTERNAL_ERROR",
   "message":"Please wait 30 minutes to purchase same product",
   "status":"FAILED",
   "transaction":null
}

{
  "timeStamp":"2021-06-08 12:00:54",
  "message":"Full authentication is required to access this resource",
  "path":"/topups/2/status",
  "errorCode":"INVALID_TOKEN",
  "infoLink":null,
  "details":[
    
  ]
}

{
  "timeStamp":"2021-06-08 16:03:24",
  "message":"Transaction not found for given id",
  "path":"/topups/238746/status",
  "errorCode":"TRANSACTION_NOT_FOUND",
  "in4foLink":null,
  "details":[
    
  ]
}

Request samples

curl --location -g --request GET 'https://topups.reloadly.com/topups/{{transactionId}}/status' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN_HERE' \
--header 'Accept: application/com.reloadly.topups-v1+json'

using System;
using System.Threading.Tasks;
using System.Net.Http;
using System.Text;
using Newtonsoft.Json;

namespace WebAPIClient {
  class Program {

    static async Task Main(string[] args) {
      await ApiCall();
    }

    private static async Task ApiCall() {

      var message = new HttpRequestMessage(HttpMethod.Get, "https://topups.reloadly.com/topups/{{transactionId}}/status");

      message.Headers.TryAddWithoutValidation("Authorization", "Bearer YOUR_ACCESS_TOKEN_HERE");
      message.Headers.TryAddWithoutValidation("Accept", "application/com.reloadly.topups-v1+json");

      using
      var httpClient = new HttpClient();
      var response = await httpClient.SendAsync(message);
      var responseBody = await response.Content.ReadAsStringAsync();
      var result = JsonConvert.DeserializeObject < dynamic > (responseBody);

      Console.WriteLine(result);
    }

  }
}

package main

import (
  "fmt"
  "net/http"
  "io/ioutil"
)

func main() {

  url := "https://topups.reloadly.com/topups/{{transactionId}}/status"
  method := "GET"

  client := &http.Client {
  }
  req, err := http.NewRequest(method, url, nil)

  if err != nil {
    fmt.Println(err)
    return
  }
  req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN_HERE")
  req.Header.Add("Accept", "application/com.reloadly.topups-v1+json")

  res, err := client.Do(req)
  if err != nil {
    fmt.Println(err)
    return
  }
  defer res.Body.Close()

  body, err := ioutil.ReadAll(res.Body)
  if err != nil {
    fmt.Println(err)
    return
  }
  fmt.Println(string(body))
}

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
Request request = new Request.Builder()
  .url("https://topups.reloadly.com/topups/{{transactionId}}/status")
  .method("GET", null)
  .addHeader("Authorization", "Bearer YOUR_ACCESS_TOKEN_HERE")
  .addHeader("Accept", "application/com.reloadly.topups-v1+json")
  .build();
Response response = client.newCall(request).execute();

var request = require('request');
var options = {
  'method': 'GET',
  'url': 'https://topups.reloadly.com/topups/{{transactionId}}/status',
  'headers': {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN_HERE',
    'Accept': 'application/com.reloadly.topups-v1+json'
  }
};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://topups.reloadly.com/topups/%7B%7BtransactionId%7D%7D/status',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => array(
    'Authorization: Bearer YOUR_ACCESS_TOKEN_HERE',
    'Accept: application/com.reloadly.topups-v1+json'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

import requests
import json

url = "https://topups.reloadly.com/topups/{{transactionId}}/status"

payload={}
headers = {
  'Authorization': 'Bearer YOUR_ACCESS_TOKEN_HERE',
  'Accept': 'application/com.reloadly.topups-v1+json'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

Response parameters

Parameter

Type

Description

transactionId

integer

Indicates the unique ID of a top-up

status

string

Indicates the status of a top-up.

Note:

SUCCESSFUL: This applies when the top up is successfully made.

PROCESSING: This applies while the top up is still being verified from the operator's end.

REFUNDED: This applies once the top up is not processed successfully from the airtime operator's end. In this instance, any funds debited from a user's wallet while attempting to make the top-up are automatically refunded. FAILED: This applies when the top-up attempt fails due to an internal error from the operator's end. In this instance, you should wait 30 minutes before reinitiating the top-up. Funds are not debited for a failed top-up attempt.

operator

TransactionId

string

Indicates the transaction ID assigned by the operator of the receiving mobile number

customIdentifier

string

This is the top-up's reference that is to be assigned by the sender

recipientPhone

string

This indicates the top-up receiver's mobile number

recipientEmail

string

This indicates the top-up receiver's email (only applicable to Nauta Cuba top-ups)

senderPhone

string

This indicates the sender's mobile number

countryCode

string

Indicates the ISO code of the country where the operator is registered.

operatorId

integer

The ID of the receiving mobile number's operator

operatorName

string

The name of the receiving mobile number's operator

discount

integer

Indicates if there was a discount on the top-up made and at what rate

discountCurrency

Code

string

Indicates the currency code of the receiving mobile number

requestedAmount

integer

Indicates the top-up amount sent by the originating account

requestedAmount

CurrencyCode

string

Indicates the currency code of the originating account

deliveredAmount

integer

Indicates the top-up amount received by the receiving mobile number

deliveredAmount

CurrencyCode

string

Indicates the currency in which the top-up was delivered

transactionDate

string

Indicates the date and time the top-up was made

pinDetail

object

This contains information on how to process the PIN on the physical SIM. Note that this is only for operators that support PIN Top-up

serial

string

Indicates the serial code of the PIN top-up

info

string

Indicates information on how to utilize the top-up

value

string

Indicates additional information on the PIN

code

string

Indicates the code that is to be used to activate the top-up

ivr

string

Indicates the number to call for an interactive voice response

validity

string

Indicates the validity of the PIN

balanceInfo

object

Contains information of the top-up sender's account balance

oldBalance

integer

Indicates the balance of the sender's account before the top-up was made

newBalance

integer

Indicates the balance of the sender's account after the top-up was made

cost

integer

Indicates the amount deducted from your account for the top-up.

currencyCode

string

Indicates the currency code of the sender's account

currencyName

string

Indcates the currency denomination of the sender's account

updatedAt

string

Indicates the time the account's balance was updated to reflect the last top-up made

Transactions

Get all transactions

Using the /topups/reports/transactions endpoint, developers can get information on every top-up transaction made on a Reloadly account

Transactions

GET https://topups.reloadly.com/topups/reports/transactions

Query Parameters

Name

Type

Description

page

integer

The page of the operator list being retrieved. Default is 1

size

integer

The number of transactions to be retrieved on a page. Default is 100

countryCode

string

Indicates the ISO code of the country where the operator is registered

customIdentifier

string

The unique reference assigned to the transaction

startDate

string

Indicates the beginning of the timeframe range for the transactions to be searched for. Format is YYYY-MM-DD HH:mm:ss

endDate

string

Indicates the end of the timeframe range for the transactions to be searched for Format is YYYY-MM-DD HH:mm:ss

operatorId

string

Indicates the ID of the operator whose transaction history is being searched for

operatorName

string

Indicates the name of the operator whose transaction history is being searched for

Headers

Name

Type

Description

Authorization*

string

Your access token is required as a bearer token in the request's header

{
  "content": [
    {
      "transactionId": 27623,
      "status": "SUCCESSFUL",
      "operatorTransactionId": null,
      "customIdentifier": null,
      "recipientPhone": "2348147658720",
      "recipientEmail": null,
      "senderPhone": "2341231231231",
      "countryCode": "NG",
      "operatorId": 341,
      "operatorName": "MTN Nigeria",
      "discount": 0,
      "discountCurrencyCode": "NGN",
      "requestedAmount": 100,
      "requestedAmountCurrencyCode": "NGN",
      "deliveredAmount": 100,
      "deliveredAmountCurrencyCode": "NGN",
      "transactionDate": "2022-02-21 04:19:26",
      "pinDetail": null,
      "balanceInfo": {
        "oldBalance": 969849.49,
        "newBalance": 969749.49,
        "cost": 100,
        "currencyCode": "NGN",
        "currencyName": "Nigerian Naira",
        "updatedAt": "2022-02-21 09:19:26"
      }
    },
    {...},
    {...}
  ]
}

{
  "timeStamp":"2021-06-09 22:43:05",
  "message":"Full authentication is required to access this resource",
  "path":"/topups/reports/transactions",
  "errorCode":"INVALID_TOKEN",
  "infoLink":null,
  "details":[
    
  ]
}

{
  "timestamp":"2021-06-09T22:45:07.750+0000",
  "status":404,
  "error":"Not Found",
  "message":"No message available",
  "path":"/topups/reports/transaction"
}

Request samples

curl --location --request GET 'https://topups.reloadly.com/topups/reports/transactions' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN_HERE' \
--header 'Accept: application/com.reloadly.topups-v1+json'

using System;
using System.Threading.Tasks;
using System.Net.Http;
using System.Text;
using Newtonsoft.Json;

namespace WebAPIClient {
  class Program {

    static async Task Main(string[] args) {
      await ApiCall();
    }

    private static async Task ApiCall() {

      var message = new HttpRequestMessage(HttpMethod.Post, "https://topups.reloadly.com/topups/reports/transactions");

      message.Headers.TryAddWithoutValidation("Authorization", "Bearer YOUR_ACCESS_TOKEN_HERE");
      message.Headers.TryAddWithoutValidation("Accept", "application/com.reloadly.topups-v1+json");

      using
      var httpClient = new HttpClient();
      var response = await httpClient.SendAsync(message);
      var responseBody = await response.Content.ReadAsStringAsync();
      var result = JsonConvert.DeserializeObject < dynamic > (responseBody);

      Console.WriteLine(result);
    }

  }
}

package main

import (
  "fmt"
  "net/http"
  "io/ioutil"
)

func main() {

  url := "https://topups.reloadly.com/topups/reports/transactions"
  method := "GET"

  client := &http.Client {
  }
  req, err := http.NewRequest(method, url, nil)

  if err != nil {
    fmt.Println(err)
    return
  }
  req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN_HERE")
  req.Header.Add("Accept", "application/com.reloadly.topups-v1+json")

  res, err := client.Do(req)
  if err != nil {
    fmt.Println(err)
    return
  }
  defer res.Body.Close()

  body, err := ioutil.ReadAll(res.Body)
  if err != nil {
    fmt.Println(err)
    return
  }
  fmt.Println(string(body))
}

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
Request request = new Request.Builder()
  .url("https://topups.reloadly.com/topups/reports/transactions")
  .method("GET", null)
  .addHeader("Authorization", "Bearer YOUR_ACCESS_TOKEN_HERE")
  .addHeader("Accept", "application/com.reloadly.topups-v1+json")
  .build();
Response response = client.newCall(request).execute();

var request = require('request');
var options = {
  'method': 'GET',
  'url': 'https://topups.reloadly.com/topups/reports/transactions',
  'headers': {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN_HERE',
    'Accept': 'application/com.reloadly.topups-v1+json',
  }
};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://topups.reloadly.com/topups/reports/transactions',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => array(
    'Authorization: Bearer YOUR_ACCESS_TOKEN_HERE',
    'Accept: application/com.reloadly.topups-v1+json'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

import requests
import json

url = "https://topups.reloadly.com/topups/reports/transactions"

payload={}
headers = {
  'Authorization': 'Bearer YOUR_ACCESS_TOKEN_HERE',
  'Accept': 'application/com.reloadly.topups-v1+json'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

Response parameters

Parameter

Type

Description

transactionId

integer

Indicates the unique ID of a top-up

status

string

Indicates the status of a transaction.

operator

TransactionId

string

Indicates the transaction ID assigned by the operator of the receiving mobile number

customIdentifier

string

This is the top-up's reference that is to be assigned by the sender

senderPhone

string

This indicates the sender's mobile number

countryCode

string

Indicates the ISO code of the country where the operator is registered

operatorId

integer

The ID of the receiving mobile number's operator

operatorName

string

The name of the receiving mobile number's operator

requestedAmount

integer

Indicates the top-up amount sent by the originating account

discount

integer

Indicates if there was a discount on the top-up made and at what rate

discountCurrency

Code

string

Indicates the currency code of the receiving mobile number

requestedAmount

CurrencyCode

string

Indicates the currency code of the originating account

deliveredAmount

integer

Indicates the top-up amount received by the receiving mobile number

deliveredAmount

CurrencyCode

string

Indicates the currency in which the top-up was delivered

transactionDate

string

Indicates the date and time the top-up was made

pinDetail

object

This contains information on how to process the PIN on the physical SIM. Note that this is only for operators that support PIN Top-up.

balanceInfo

object

Contains information of the top-up sender's account balance.

oldBalance

integer

Indicates the balance of the sender's account before the top-up was made

newBalance

integer

Indicates the balance of the sender's account after the top-up was made

cost

integer

Indicates the amount deducted from your account for the top-up.

currencyCode

string

Indicates the currency code of the sender's account

currencyName

string

Indicates the currency denomination of the sender's account

updatedAt

string

Indicates the time the account's balance was updated to reflect the last top-up made

Get transaction by ID

With the topups/reports/transactions/{transactionid} endpoint, you can retrieve information on a top-up transaction by making a request with the transaction's ID

Transaction by ID

GET https://topups.reloadly.com/topups/reports/transactions/{transactionid}

Path Parameters

Name

Type

Description

transactionId*

integer

The ID of the transaction to be retrieved

Headers

Name

Type

Description

Authorization*

string

Your access token is required as a bearer token in the request's header

{
  "transactionId": 27623,
  "status": "SUCCESSFUL",
  "operatorTransactionId": null,
  "customIdentifier": null,
  "recipientPhone": "2348147658720",
  "recipientEmail": null,
  "senderPhone": "2341231231231",
  "countryCode": "NG",
  "operatorId": 341,
  "operatorName": "MTN Nigeria",
  "discount": 0,
  "discountCurrencyCode": "NGN",
  "requestedAmount": 100,
  "requestedAmountCurrencyCode": "NGN",
  "deliveredAmount": 100,
  "deliveredAmountCurrencyCode": "NGN",
  "transactionDate": "2022-02-21 04:19:26",
  "pinDetail": null,
  "balanceInfo": {
    "oldBalance": 969849.49,
    "newBalance": 969749.49,
    "cost": 100,
    "currencyCode": "NGN",
    "currencyName": "Nigerian Naira",
    "updatedAt": "2022-02-21 09:19:26"
  }
}

{
  "timeStamp":"2021-06-09 20:59:35",
  "message":"Full authentication is required to access this resource",
  "path":"/topups/reports/transactions/270395",
  "errorCode":"INVALID_TOKEN",
  "infoLink":null,
  "details":[
    
  ]
}

{
  "timeStamp":"2021-06-09 20:51:40",
  "message":"Airtime transaction not found",
  "path":"/topups/reports/transactions/270395111",
  "errorCode":null,
  "infoLink":null,
  "details":[
    
  ]
}

Request samples

curl --location --request GET 'https://topups.reloadly.com/topups/reports/transactions/1' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN_HERE' \
--header 'Accept: application/com.reloadly.topups-v1+json'

using System;
using System.Threading.Tasks;
using System.Net.Http;
using System.Text;
using Newtonsoft.Json;

namespace WebAPIClient {
  class Program {

    static async Task Main(string[] args) {
      await ApiCall();
    }

    private static async Task ApiCall() {

      var message = new HttpRequestMessage(HttpMethod.Post, "https://topups.reloadly.com/topups/reports/transactions/1");

      message.Headers.TryAddWithoutValidation("Authorization", "Bearer YOUR_ACCESS_TOKEN_HERE");
      message.Headers.TryAddWithoutValidation("Accept", "application/com.reloadly.topups-v1+json");

      using
      var httpClient = new HttpClient();
      var response = await httpClient.SendAsync(message);
      var responseBody = await response.Content.ReadAsStringAsync();
      var result = JsonConvert.DeserializeObject < dynamic > (responseBody);

      Console.WriteLine(result);
    }

  }
}

package main

import (
  "fmt"
  "net/http"
  "io/ioutil"
)

func main() {

  url := "https://topups.reloadly.com/topups/reports/transactions/1"
  method := "GET"

  client := &http.Client {
  }
  req, err := http.NewRequest(method, url, nil)

  if err != nil {
    fmt.Println(err)
    return
  }
  req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN_HERE")
  req.Header.Add("Accept", "application/com.reloadly.topups-v1+json")

  res, err := client.Do(req)
  if err != nil {
    fmt.Println(err)
    return
  }
  defer res.Body.Close()

  body, err := ioutil.ReadAll(res.Body)
  if err != nil {
    fmt.Println(err)
    return
  }
  fmt.Println(string(body))
}

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
Request request = new Request.Builder()
  .url("https://topups.reloadly.com/topups/reports/transactions/1")
  .method("GET", null)
  .addHeader("Authorization", "Bearer YOUR_ACCESS_TOKEN_HERE")
  .addHeader("Accept", "application/com.reloadly.topups-v1+json")
  .build();
Response response = client.newCall(request).execute();

var request = require('request');
var options = {
  'method': 'GET',
  'url': 'https://topups.reloadly.com/topups/reports/transactions/1',
  'headers': {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN_HERE',
    'Accept': 'application/com.reloadly.topups-v1+json'
  }
};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://topups.reloadly.com/topups/reports/transactions/1',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => array(
    'Authorization: Bearer YOUR_ACCESS_TOKEN_HERE',
    'Accept: application/com.reloadly.topups-v1+json'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

import requests
import json

url = "https://topups.reloadly.com/topups/reports/transactions/1"

payload={}
headers = {
  'Authorization': 'Bearer YOUR_ACCESS_TOKEN_HERE',
  'Accept': 'application/com.reloadly.topups-v1+json'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

Response parameters

Parameter

Type

Description

transactionId

integer

Indicates the unique ID of a top-up

status

string

Indicates the status of a transaction.

operator

TransactionId

string

Indicates the transaction ID assigned by the operator of the receiving mobile number

customIdentifier

string

This is the top-up's reference that is to be assigned by the sender

senderPhone

string

This indicates the sender's mobile number

countryCode

string

Indicates the ISO code of the country where the operator is registered

operatorId

integer

The ID of the receiving mobile number's operator

operatorName

string

The name of the receiving mobile number's operator

requestedAmount

integer

Indicates the top-up amount sent by the originating account

discount

integer

Indicates if there was a discount on the top-up made and at what rate

discountCurrency

Code

string

Indicates the currency code of the receiving mobile number

requestedAmount

CurrencyCode

string

Indicates the currency code of the originating account

deliveredAmount

integer

Indicates the top-up amount received by the receiving mobile number

deliveredAmount

CurrencyCode

string

Indicates the currency in which the top-up was delivered

transactionDate

string

Indicates the date and time the top-up was made

pinDetail

object

This contains information on how to process the PIN on the physical SIM. Note that this is only for operators that support PIN Top-up.

balanceInfo

object

Balance information before and after the top-up

Airtime Errors

Error Codes

Here is a comprehensive breakdown of all client and server-side errors that can occur during usage of the Airtime API.

Error Code

Description

COUNTRY_NOT_SUPPORTED

The specified country in the request is currently disabled or not supported.

OPERATOR_UNAVAILABLE_OR_

CURRENTLY INACTIVE

The specified operator is currently disabled or inactive on the platform.

COULD_NOT_AUTO_DETECT_OPERATOR

INVALID_AMOUNT_FOR_OPERATOR

The specified top-up amount is not valid for the given operator in the request.

TOKEN_EXPIRED

Access tokens have a finite lifetime which is indicated whenever they are issued.

To track an access token's lifetime, you can either:

Keep track of the expires_in value in the response gotten when a request is made for an access token. The value is expressed in seconds.
Handle the HTTP 401 Unauthorized status code and the TOKEN_EXPIRED error code in the error response message. The API endpoint issues this status code when it detects an expired token.

INSUFFICIENT_BALANCE

The user's account balance is not sufficient enough to carry out their intended request.

MAX_DAILY_TRANSACTION_AMOUNT_

REACHED

MAX_DAILY_TRANSACTION_COUNT_

REACHED

ACCOUNT_NOT_FOUND

INVALID_AMOUNT

The amount requested by the user is incorrect — either a wrong data type or an invalid amount specification (for operators with fixed ranges).

INVALID_RECIPIENT_PHONE

The specified recipientPhone parameter in the request is not valid for the specified country.

INVALID_SENDER_PHONE

The specified senderPhone parameter in the request is not valid for the specified country.

INVALID_PHONE_NUMBER

The specified phone number is not valid.

PHONE_RECENTLY_RECHARGED

A second recharge was attempted on a mobile number before the default waiting time of two minutes could elapse.

INACTIVE_ACCOUNT

TOPUP_TRANSACTION_FAILED

TRANSACTION_CANNOT_BE_PROCESSED_AT_THE_MOMENT

OPERATOR_NOT_IN_SERVICE

The specified operator in the request is currently disabled, inactive, or not in service on the platform.