top up
Sign in
Find anything...Home
Airtime API
Gift Cards API
Utility Payments API
Airtime
Test mode
Test Mode On
Download Open API documentation
Check out our no-code plugin
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.
BASE URL
https://topups.reloadly.com
BASE URL SANDBOX
https://topups-sandbox.reloadly.com
Reloadly uses access tokens ( or bearer tokens ) to authenticate requests and grant access to our APIs. Access tokens differ across our various products. This means that you can only use an access token generated for the airtime service on the Airtime API, the same goes for other products.
Also, Reloadly has two operating environments - Production which allows you work with live credentials while building real world applications and Sandbox which helps you access our APIs in test mode and simulate real-like scenarios.
Reloadly employs the OAuth 2.0 standard.Note that all API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.
To get an access token, first obtain your client id and client secret from the Reloadly dashboard. Remember to toggle between LIVE mode and TEST mode on the dashboard sidebar to select the appropriate client id and client secret.
After selecting the appropriate client credentials for the environment you want to work with, make a POST request with the payload format provided in the code sample section.
Request 
REQUEST BODY SCHEMA: application/json
PAYLOAD DESCRIPTION
audience
string
The product which the access token is to be used for.
Example: https://topups.reloadly.com
client_id
string
Your account's client ID.
Example: qwcLzXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
client_secret
string
Your account's client secret.
Example: 7kscVxQZ32-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
grant_type
string
The access type being specified.
Example: client_credentials
Response
200
Successfully created an access token.
401
Failed due to an unauthorized request.
POST /oauth/token
https://auth.reloadly.com/oauth/token
REQUEST SAMPLES
cURL
Node
Python
C#
JAVA
Go
PHP
R
Ruby
Swift
RESPONSE SAMPLES
200
401
{
"access_token": "eyJraWQiOiJjNGE1ZWU1Zi0xYmE2LTQ1N2UtOTI3Yi1lYzdiODliNzcxZTIiLCJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiI2NzkzIiwiaXNzIjoiaHR0cHM6Ly9yZWxvYWRseS1zYW5kYm94LmF1dGgwLmNvbS8iLCJodHRwczovL3JlbG9hZGx5LmNvbS9zYW5kYm94Ijp0cnVlLCJodHRwczovL3JlbG9hZGx5LmNvbS9wcmVwYWlkVXNlcklkIjoiNjc5MyIsImd0eSI6ImNsaWVudC1jcmVkZW50aWFscyIsImF1ZCI6Imh0dHBzOi8vZ2lmdGNhcmRzLXNhbmRib3gucmVsb2FkbHkuY29tIiwibmJmIjoxNjU4MDY2NDkxLCJhenAiOiI2NzkzIiwic2NvcGUiOiJkZXZlbG9wZXIiLCJleHAiOjE2NTgxNTI4OTEsImh0dHBzOi8vcmVsb2FkbHkuY29tL2p0aSI6ImIyMmY3MDRmLTJkMWEtNDZjMC1hYjUxLWZkMzAwNWQxNWM0MiIsImlhdCI6MTY1ODA2NjQdjwfbianRpIjoiMWM1ZmY5YTItNzJhMC00ZDg2LWFjZmYtZmU1NDMxNGU0OGQ4In0.P3f-eNbrjFuGHuDKNGjskzifPARaJPRMVS4gGisp0ZA",
"scope": "developer",
"expires_in": 5184000,
"token_type": "Bearer"
}
The Balance feature lets you view the details of your account balance in real-time. Information provided by the Balance feature includes an account's balance, the currency name and denomination of the account, and the last time funds were used from the account.
Retrieve the details of your account's balance.
Security BearerToken
HTTP: BearerToken
HTTP Authorization Scheme: bearer
Response
200
Successfully retrieved balance details
401
Failed due to an unauthorized request
404
Failed because the request was made to an incorrect URL path
Production URL
Sandbox URL
GET https://topups.reloadly.com/accounts/balance
REQUEST SAMPLES
cURL
Node
Python
C#
JAVA
Go
PHP
R
Ruby
Swift
RESPONSE SAMPLES
200
401
404
{
"balance": 5000,
"currencyCode": "USD",
"currencyName": "US Dollar",
"updatedAt": "2021-12-04 08:45:51"
}
Information on countries can be handy when making decisions about what countries should be accessed and what regions should be used when making an airtime recharge. The Airtime Countries feature allows you to get details on over 140 countries where airtime top-ups can be made.
Data included in the details are the country's name, currency code, currency name, currency symbol, country's flag, and calling code. The country's ISO code which is a two-letter country code that serves as a personal identifier for each country is also included.
Retrieve the details of every country where a top-up can be made.
Security BearerToken
HTTP: BearerToken
HTTP Authorization Scheme: bearer
Response
200
Successfully retrieved details of all countries
401
Failed due to an unauthorized request
404
Failed because the request was made to an incorrect URL path
Production URL
Sandbox URL
GET https://topups.reloadly.com/countries
REQUEST SAMPLES
cURL
Node
Python
C#
JAVA
Go
PHP
R
Ruby
Swift
RESPONSE SAMPLES
200
401
404
[
{
"isoName": "AF",
"name": "Afghanistan",
"continent": "Asia",
"currencyCode": "AFN",
"currencyName": "Afghan Afghani",
"currencySymbol": "؋",
"flag": "https://s3.amazonaws.com/rld-flags/af.svg",
"callingCodes": [
"+93"
]
},
{},
{}
]
Retrieve the details of a country by making a request with its ISO code.
Security BearerToken
HTTP: BearerToken
HTTP Authorization Scheme: bearer
Request
PATH PARAMETERS
countrycode
requiredString
The country's ISO Code.
Example: US
Response
200
Successfully retrieved details of a country
401
Failed due to an unauthorized request
404
Failed because the request was made to an incorrect URL path
Production URL
Sandbox URL
GET https://topups.reloadly.com/countries/{countrycode}
REQUEST SAMPLES
cURL
Node
Python
C#
JAVA
Go
PHP
R
Ruby
Swift
RESPONSE SAMPLES
200
401
404
[
{
"isoName": "AG",
"name": "Antigua and Barbuda",
"continent": "North America",
"currencyCode": "XCD",
"currencyName": "East Caribbean Dollar",
"currencySymbol": "XCD",
"flag": "https://s3.amazonaws.com/rld-flags/ag.svg",
"callingCodes": [
"+1268"
]
}
]
The data on Operators provides insight into the mobile operators that can be used to make an international or local airtime recharge. With the Operators feature, you can get details of over 700 operators located in different regions. You can also automatically detect the details of a mobile phone number's operator.
Some of the information included in the operator's details are the operator's name, denomination type, FX rate where applicable, discount, country's details, and operator ID. The operator's FX rate is calculated against the currency of the airtime sender's account.
Retrieve the details of every operator that can be used to send or receive a top-up.
Security BearerToken
HTTP: BearerToken
HTTP Authorization Scheme: bearer
Request
QUERY PARAMETERS
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.
Example: 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.
Example: true
suggestedAmountsMap
Boolean
Indicates if this field should be returned as a response. Default value is false.
Example: false
size
Integer
This indicates the number of operators to be retrieved on a page. Default value is 200.
Example: 10
page
Integer
This indicates the page of the operator list being retrieved. Default value is 1.
Example: 2
includeCombo
Boolean
Indicates if any combo products being offered by the operator should be returned as a response. Default value is true.
Example: false
comboOnly
Boolean
This adds a filter that only returns the available combo operators. Default value is false.
Example: false
bundlesOnly
Boolean
This adds a filter that only returns the available bundle operators. Default value is false.
Example: false
dataOnly
Boolean
This adds a filter that only returns the available data operators. Default value is false
Example: false
pinOnly
Boolean
This adds a filter that only returns the available pin operators. Default value is false
Example: false
Response
200
Successfully retrieved details of all operators
401
Failed due to an unauthorized request
404
Failed because the request was made to an incorrect URL path
Production URL
Sandbox URL
GET https://topups.reloadly.com/operators
REQUEST SAMPLES
cURL
Node
Python
C#
JAVA
Go
PHP
R
Ruby
Swift
RESPONSE SAMPLES
200
401
404
{
"content": [
{
"id": 88,
"operatorId": 88,
"name": "Movistar Colombia",
"bundle": false,
"data": false,
"comboProduct": false,
"pin": false,
"supportsLocalAmounts": false,
"denominationType": "RANGE",
"senderCurrencyCode": "USD",
"senderCurrencySymbol": "$",
"destinationCurrencyCode": "COP",
"destinationCurrencySymbol": "$",
"commission": 4.42,
"internationalDiscount": 4.42,
"localDiscount": 0,
"mostPopularAmount": null,
"minAmount": 5,
"maxAmount": 5,
"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
],
"suggestedAmountsMap": {
"7": 19482.51,
"10": 27832.16,
"15": 41748.23
},
"promotions": [],
"fees": {
"international": 0.943054,
"internationalPercentage": 0,
"local": 300,
"localPercentage": 0
}
},
{},
{}
]
}
Retrieve the details of an operator by making a request with its identification number
Security BearerToken
HTTP: BearerToken
HTTP Authorization Scheme: bearer
Request
PATH PARAMETERS
operatorid
requiredInteger
The operator's identification number.
Example: 341
Response
200
Successfully retrieved details of an operator
401
Failed due to an unauthorized request
404
Failed because the request was made to an incorrect URL path
Production URL
Sandbox URL
GET https://topups.reloadly.com/operators/{operatorid}
REQUEST SAMPLES
cURL
Node
Python
C#
JAVA
Go
PHP
R
Ruby
Swift
RESPONSE SAMPLES
200
401
404
{
"id": 88,
"operatorId": 88,
"name": "Movistar Colombia",
"bundle": false,
"data": false,
"comboProduct": false,
"pin": false,
"supportsLocalAmounts": false,
"denominationType": "RANGE",
"senderCurrencyCode": "USD",
"senderCurrencySymbol": "$",
"destinationCurrencyCode": "COP",
"destinationCurrencySymbol": "$",
"commission": 4.42,
"internationalDiscount": 4.42,
"localDiscount": 0,
"mostPopularAmount": null,
"minAmount": 5,
"maxAmount": 5,
"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
],
"suggestedAmountsMap": {
"7": 19482.51,
"10": 27832.16,
"15": 41748.23
},
"promotions": [],
"fees": {
"international": 0.943054,
"internationalPercentage": 0,
"local": 300,
"localPercentage": 0
}
}
Retrieve the details of a mobile number by making a request using the mobile number and the ISO code of the country where it is registered.
Security BearerToken
HTTP: BearerToken
HTTP Authorization Scheme: bearer
Request
PATH PARAMETERS
phone
requiredInteger
The mobile number whose details are to be retrieved.
Example: 8147658721
countryisocode
requiredString
The ISO code of the country where the mobile number is registered.
Example: NG
QUERY PARAMETERS
suggestedAmountsMap
Boolean
Indicates if this field should be returned as a response. Default value is false.
Example: true
suggestedAmounts
Boolean
Indicates if this field should be returned as a response. Default value is false.
Example: false
Response
200
Successfully retrieved details of a mobile number
401
Failed due to an unauthorized request
404
Failed because the request was made to an incorrect URL path
Production URL
Sandbox URL
GET https://topups.reloadly.com/operators/auto-detect/phone/{phone}/countries/{countryisocode}
REQUEST SAMPLES
cURL
Node
Python
C#
JAVA
Go
PHP
R
Ruby
Swift
RESPONSE SAMPLES
200
401
404
{
"id": 88,
"operatorId": 88,
"name": "Movistar Colombia",
"bundle": false,
"data": false,
"comboProduct": false,
"pin": false,
"supportsLocalAmounts": false,
"denominationType": "RANGE",
"senderCurrencyCode": "USD",
"senderCurrencySymbol": "$",
"destinationCurrencyCode": "COP",
"destinationCurrencySymbol": "$",
"commission": 4.42,
"internationalDiscount": 4.42,
"localDiscount": 0,
"mostPopularAmount": null,
"minAmount": 5,
"maxAmount": 5,
"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
],
"suggestedAmountsMap": {
"7": 19482.51,
"10": 27832.16,
"15": 41748.23
},
"promotions": [],
"fees": {
"international": 0.943054,
"internationalPercentage": 0,
"local": 300,
"localPercentage": 0
}
}
Retrieve the details of all the operators within a particular country by making a request with the country's ISO code.
Security BearerToken
HTTP: BearerToken
HTTP Authorization Scheme: bearer
Request
PATH PARAMETERS
countrycode
requiredString
The ISO code of the country where the operator is registered.
Example: CO
QUERY PARAMETERS
suggestedAmountsMap
Boolean
Indicates if this field should be returned as a response. Default value is false.
Example: false
suggestedAmounts
Boolean
Indicates if this field should be returned as a response. Default value is false.
Example: false
includePin
Boolean
Indicates if PIN details if applicable to the operator, should be returned as a response. Default value is true.
Example: false
includeData
Boolean
Indicates if any data plans being offered by the operator should be returned as a response. Default value is true.
Example: false
includeBundles
Boolean
Indicates if any airtime and data bundles being offered by the operator should be returned as a response. Default value is true.
Example: false
includeCombo
Boolean
Indicates if any combo products being offered by the operator should be returned as a response. Default value is true.
Example: false
comboOnly
Boolean
This adds a filter that only returns the available combo operators. Default value is false.
Example: false
bundlesOnly
Boolean
This adds a filter that only returns the available bundle operators. Default value is false.
Example: false
dataOnly
Boolean
This adds a filter that only returns the available data operators. Default value is false
Example: false
pinOnly
Boolean
This adds a filter that only returns the available pin operators. Default value is false
Example: false
Response
200
Successfully retrieved details of an operator
401
Failed due to an unauthorized request
404
Failed because the request was made to an incorrect URL path
Production URL
Sandbox URL
GET https://topups.reloadly.com/operators/countries/{countrycode}
REQUEST SAMPLES
cURL
Node
Python
C#
JAVA
Go
PHP
R
Ruby
Swift
RESPONSE SAMPLES
200
401
404
{
"example": {
"id": 88,
"operatorId": 88,
"name": "Movistar Colombia",
"bundle": false,
"data": false,
"comboProduct": false,
"pin": false,
"supportsLocalAmounts": false,
"denominationType": "RANGE",
"senderCurrencyCode": "USD",
"senderCurrencySymbol": "$",
"destinationCurrencyCode": "COP",
"destinationCurrencySymbol": "$",
"commission": 4.42,
"internationalDiscount": 4.42,
"localDiscount": 0,
"mostPopularAmount": null,
"minAmount": 5,
"maxAmount": 5,
"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
],
"suggestedAmountsMap": {
"7": 19482.51,
"10": 27832.16,
"15": 41748.23
},
"promotions": [],
"fees": {
"international": 0.943054,
"internationalPercentage": 0,
"local": 300,
"localPercentage": 0
}
}
}
Airtime FX Rates provide details on the exchange rate of an operator at which an airtime recharge will be made. This is helpful for the following use cases
Retrieve the foreign exchange rate details of an operator by making a request with its identification number.
Security BearerToken
HTTP: BearerToken
HTTP Authorization Scheme: bearer
Request
REQUEST BODY SCHEMA: application/json
PAYLOAD DESCRIPTION
amount
requiredinteger
The amount to be converted.
Example: 10
operatorId
requiredinteger
The operator's identification number.
Example: 341
Response
200
Successfully retrieved details of an operator's foreign exchange rate.
401
Failed due to an unauthorized request.
404
Failed because the request was made to an incorrect URL path.
500
Failed because the request was made to an operator without a foreign exchange rate.
Production URL
Sandbox URL
POST https://topups.reloadly.com/operators/fx-rate
REQUEST SAMPLES
cURL
Node
Python
C#
JAVA
Go
PHP
R
Ruby
Swift
RESPONSE SAMPLES
200
401
404
500
{
"id": 174,
"name": "Natcom Haiti",
"fxRate": 465,
"currencyCode": "HTG"
}
The data on Commissions provides you with details of operators that offer a percentage discount for every airtime recharge. This is useful in getting the best value when making top-ups across various operators. You can also view discount information for a particular operator. Information made accessible via the Commissions feature includes the operator ID, discount percentage, discount status, and operator's country code while working with the discount.
Retrieve the details of every discount being issued by all the airtime and data operators available on Reloadly.
Security BearerToken
HTTP: BearerToken
HTTP Authorization Scheme: bearer
Request
QUERY PARAMETERS
size
Integer
This indicates the number of operators offering discounts to be retrieved on a page. Default value is 200.
Example: 10
page
Integer
This indicates the page of the discounts list being retrieved. Default value is 1.
Example: 1
Response
200
Successfully retrieved details of all discounts
401
Failed due to an unauthorized request
404
Failed because the request was made to an incorrect URL path
Production URL
Sandbox URL
GET https://topups.reloadly.com/operators/commissions
REQUEST SAMPLES
cURL
Node
Python
C#
JAVA
Go
PHP
R
Ruby
Swift
RESPONSE SAMPLES
200
401
404
{
"content": [
{
"operator": {
"operatorId": 1,
"name": "Afghan Wireless Afghanistan",
"countryCode": "AF",
"status": true,
"bundle": false
},
"percentage": 10,
"internationalPercentage": 10,
"localPercentage": 0,
"updatedAt": "2021-06-26 03:36:16"
},
{},
{}
]
}
Retrieve the details of a discount being offered by an operator by making a request with the operator's identification number.
Security BearerToken
HTTP: BearerToken
HTTP Authorization Scheme: bearer
Request
PATH PARAMETERS
operatorid
requiredInteger
The operator's identification number.
Example: 341
Response
200
Successfully retrieved details of an operator's discount(s)
401
Failed due to an unauthorized request
404
Failed because the request was made to an incorrect URL path
Production URL
Sandbox URL
GET https://topups.reloadly.com/operators/{operatorid}/commissions
REQUEST SAMPLES
cURL
Node
Python
C#
JAVA
Go
PHP
R
Ruby
Swift
RESPONSE SAMPLES
200
401
404
{
"operator": {
"operatorId": 1,
"name": "Afghan Wireless Afghanistan",
"countryCode": "AF",
"status": true,
"bundle": false
},
"percentage": 10,
"internationalPercentage": 10,
"localPercentage": 0,
"updatedAt": "2021-06-26 03:36:16"
}
The Promotions feature allows you to view details of ongoing promotions being carried out by operators in various regions. This provides top-up services such as special airtime and bundle offers to mobile numbers located in various regions.
Information that can be accessed while working with Promotions includes the promotion's ID, extensive details of the promotion, the promotion's timeframe, and the currency denomination(s) in which the promotion is being carried out.
Retrieve the details of every promotion being issued by any operator available on Reloadly.
Security BearerToken
HTTP: BearerToken
HTTP Authorization Scheme: bearer
Request
QUERY PARAMETERS
size
Integer
This indicates the number of promotions to be retrieved on a page. Default value is 200.
Example: 10
page
Integer
This indicates the page of the promotions list being retrieved. Default value is 1.
Example: 1
languageCode
String
This indicates the language you want the promotion information to be displayed in. The language code is to be specified in the ISO 639-1 format. Choices are 'EN', 'ES', 'FR', 'IT', 'PT', 'ZH', 'AR', 'HI', 'HT', 'JA' and 'DE'. Default is 'EN'. This is a case-insensitive field. The promotion information is returned in your requested language irrespective of the original language in which the promotion was launched.
Example: EN
Response
200
Successfully retrieved details of all promotions.
401
Failed due to an unauthorized request.
404
Failed because the request was made to an incorrect URL path.
Production URL
Sandbox URL
GET https://topups.reloadly.com/promotions
REQUEST SAMPLES
cURL
Node
Python
C#
JAVA
Go
PHP
R
Ruby
Swift
RESPONSE SAMPLES
200
401
404
{
"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
},
{},
{}
]
}
Retrieve the details of a promotion by making a request with its identification number.
Security BearerToken
HTTP: BearerToken
HTTP Authorization Scheme: bearer
Request
PATH PARAMETERS
promotionid
requiredInteger
The promotion's identification number.
Example: 5583
QUERY PARAMETERS
languageCode
String
This indicates the language you want the promotion information to be displayed in. The language code is to be specified in the ISO 639-1 format. Choices are 'EN', 'ES', 'FR', 'IT', 'PT', 'ZH', 'AR', 'HI', 'HT', 'JA' and 'DE'. Default is 'EN'. This is a case-insensitive field. The promotion information is returned in your requested language irrespective of the original language in which the promotion was launched.
Example: EN
Response
200
Successfully retrieved details of a promotion.
401
Failed due to an unauthorized request.
404
Failed because the request was made to an incorrect URL path.
Production URL
Sandbox URL
GET https://topups.reloadly.com/promotions/{promotionid}
REQUEST SAMPLES
cURL
Node
Python
C#
JAVA
Go
PHP
R
Ruby
Swift
RESPONSE SAMPLES
200
401
404
{
"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
}
}
Retrieve the details of every promotion going on in a country by making a request with its ISO code.
Security BearerToken
HTTP: BearerToken
HTTP Authorization Scheme: bearer
Request
PATH PARAMETERS
countrycode
requiredString
The ISO code of the country whose promotions are to be retrieved.
Example: US
QUERY PARAMETERS
languageCode
String
This indicates the language you want the promotion information to be displayed in. The language code is to be specified in the ISO 639-1 format. Choices are 'EN', 'ES', 'FR', 'IT', 'PT', 'ZH', 'AR', 'HI', 'HT', 'JA' and 'DE'. Default is 'EN'. This is a case-insensitive field. The promotion information is returned in your requested language irrespective of the original language in which the promotion was launched.
Example: EN
Response
200
Successfully retrieved details of all the promotions being offered in a country.
401
Failed due to an unauthorized request.
404
Failed because the request was made to an incorrect URL path.
Production URL
Sandbox URL
GET https://topups.reloadly.com/promotions/country-codes/{countrycode}
REQUEST SAMPLES
cURL
Node
Python
C#
JAVA
Go
PHP
R
Ruby
Swift
RESPONSE SAMPLES
200
401
404
{
"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
},
{},
{}
]
}
Retrieve the details of every promotion being ofered by an operator by making a request with the operator's identification number.
Security BearerToken
HTTP: BearerToken
HTTP Authorization Scheme: bearer
Request
PATH PARAMETERS
operatorid
requiredInteger
The identification number of the operator whose promotions are to be retrieved.
Example: 341
QUERY PARAMETERS
languageCode
String
This indicates the language you want the promotion information to be displayed in. The language code is to be specified in the ISO 639-1 format. Choices are 'EN', 'ES', 'FR', 'IT', 'PT', 'ZH', 'AR', 'HI', 'HT', 'JA' and 'DE'. Default is 'EN'. This is a case-insensitive field. The promotion information is returned in your requested language irrespective of the original language in which the promotion was launched.
Example: EN
Response
200
Successfully retrieved details of all the promotions being offered by an operator.
401
Failed due to an unauthorized request.
404
Failed because the request was made to an incorrect URL path.
Production URL
Sandbox URL
GET https://topups.reloadly.com/promotions/operators/{operatorid}
REQUEST SAMPLES
cURL
Node
Python
C#
JAVA
Go
PHP
R
Ruby
Swift
RESPONSE SAMPLES
200
401
404
{
"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
},
{},
{}
]
}
The Top-ups feature works with other features in the Airtime product to make recharges to a mobile number. Actions you can carry out include making an instant airtime recharge to both local and international mobile numbers as well as making an asynchronous recharge that enables you to monitor and receive notifications about its status.
Some of the information you can view includes the transaction ID, the custom identifier for each top-up, the discount applied to each top-up, and the amount sent via the top-up.
Local top-ups are top-ups made to mobile numbers located within the same country as your Reloadly account. For instance, if you specified South Africa as your country when creating your Reloadly account, any top-up you make to a South African number is a local top-up.
International top-ups are top-ups made to mobile numbers located outside the country specified on your Reloadly account during registration. For example, if you specified Germany as your country when creating your Reloadly account, any top-up you make to numbers registered in a different country like France - is an international top-up.
Recharge a mobile number with airtime or data by making a request with its operator details.
Security BearerToken
HTTP: BearerToken
HTTP Authorization Scheme: bearer
Request
REQUEST BODY SCHEMA: application/json
PAYLOAD DESCRIPTION
amount
requiredstring
This indicates the amount of airtime or data that is to be recharged.
Example: 5.00
customIdentifier
string
This indicates the transaction reference of the recharge. Note that each transaction reference is to be unique. Once a reference has been used for a top-up, it cannot be reused.
Ensure you change the sample custom identifier in the payload before making a request so as to avoid any errors.
Example: This is example identifier 130
operatorId
requiredstring
This indicates the operator's identification number.
Example: 535
recipientEmail
string
This indicates the top-up receiver's email (only applicable to Nauta Cuba top-ups).
Example: peter@nauta.com.cu
recipientPhone
object
This contains information on the top-up recipient's phone details.
countryCode
string
This indicates the ISO code of the receiving mobile number's country.
Example: GB
number
string
This indicates the mobile number receiving the top-up.
Example: 447951731337
senderPhone
object
This contains information on the top-up sender's phone details.
countryCode
string
This indicates the ISO code of the sender's country.
Example: CA
number
string
This indicates the mobile number of the top-up's sender.
Example: 11231231231
useLocalAmount
boolean
This indicates if the recharge is to be made in the operator's local currency. Default is false.
Example: true
Response
200
Successfully made a top-up to a mobile number.
400
Failed because the request was made with an incorrect parameter in the payload.
401
Failed due to an unauthorized request.
404
Failed because the request was made to an incorrect URL path.
Production URL
Sandbox URL
POST https://topups.reloadly.com/topups
REQUEST SAMPLES
cURL
Node
Python
C#
JAVA
Go
PHP
R
Ruby
Swift
RESPONSE SAMPLES
200
400
401
404
{
"transactionId": 4602843,
"status": "SUCCESSFUL",
"operatorTransactionId": "7297929551:OrderConfirmed",
"customIdentifier": "This is example identifier 130",
"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": 4.9985,
"deliveredAmountCurrencyCode": "GBP",
"transactionDate": "2021-12-06 08:13:39",
"fee": 2.99891,
"pinDetail": {
"serial": 558111,
"info1": "DIAL *611",
"info2": "DIAL *611",
"info3": "DIAL *611",
"value": null,
"code": 773709733097662,
"ivr": "1-888-888-8888",
"validity": "30 days"
},
"balanceInfo": {
"oldBalance": 5109.53732,
"newBalance": 2004.50532,
"currencyCode": "NGN",
"currencyName": "Nigerian Naira",
"updatedAt": "2021-12-06 13:13:39"
}
}
This endpoint helps users by returning a transactionId for every top-up transaction made. This ID can then be used to requery the transaction and get its real-time status.
This guide provides more information on how to work with async top-ups.
Security BearerToken
HTTP: BearerToken
HTTP Authorization Scheme: bearer
Request
REQUEST BODY SCHEMA: application/json
PAYLOAD DESCRIPTION
amount
requiredstring
This indicates the amount of airtime or data that is to be recharged.
Example: 5.00
customIdentifier
string
This indicates the transaction reference of the recharge. Note that each transaction reference is to be unique. Once a reference has been used for a top-up, it cannot be reused.
Ensure you change the sample custom identifier in the payload before making a request so as to avoid any errors.
Example: This is example identifier 130
operatorId
requiredstring
This indicates the operator's identification number.
Example: 535
recipientEmail
string
This indicates the top-up receiver's email (only applicable to Nauta Cuba top-ups).
Example: peter@nauta.com.cu
recipientPhone
object
This contains information on the top-up recipient's phone details.
countryCode
string
This indicates the ISO code of the receiving mobile number's country.
Example: GB
number
string
This indicates the mobile number receiving the top-up.
Example: 447951731337
senderPhone
object
This contains information on the top-up sender's phone details.
countryCode
string
This indicates the ISO code of the sender's country.
Example: CA
number
string
This indicates the mobile number of the top-up's sender.
Example: 11231231231
useLocalAmount
boolean
This indicates if the recharge is to be made in the operator's local currency. Default is false.
Example: true
Response
200
Successfully retrieved a transaction identification number.
400
Failed because the request was made with an incorrect parameter in the payload.
401
Failed due to an unauthorized request.
404
Failed because the request was made to an incorrect URL path.
Production URL
Sandbox URL
POST https://topups.reloadly.com/topups-async
REQUEST SAMPLES
cURL
Node
Python
C#
JAVA
Go
PHP
R
Ruby
Swift
RESPONSE SAMPLES
200
400
401
404
{
"transactionId": 4602843
}
Retrieve the real-time status of a top-up by making a request with its identification number.
Security BearerToken
HTTP: BearerToken
HTTP Authorization Scheme: bearer
Request
PATH PARAMETERS
transactionId
requiredInteger
The transaction identification number of a top-up
Example: 13
Response
200
Successfully retrieved details of a top-up
401
Failed due to an unauthorized request
404
Failed because the request was made to an incorrect URL path
Production URL
Sandbox URL
GET https://topups.reloadly.com/topups/{transactionId}/status
REQUEST SAMPLES
cURL
Node
Python
C#
JAVA
Go
PHP
R
Ruby
Swift
RESPONSE SAMPLES
200
401
404
{
"code": null,
"message": null,
"status": "SUCCESSFUL",
"transaction": {
"transactionId": 17123515,
"status": "SUCCESSFUL",
"operatorTransactionId": null,
"customIdentifier": "11120958",
"recipientPhone": "971503971821",
"recipientEmail": null,
"senderPhone": "11231231231",
"countryCode": "AE",
"operatorId": 706,
"operatorName": "Salaam Afghanistan",
"discount": 0,
"discountCurrencyCode": "USD",
"requestedAmount": 1,
"requestedAmountCurrencyCode": "USD",
"deliveredAmount": 84,
"deliveredAmountCurrencyCode": "AFN",
"transactionDate": "2023-09-20 09:49:59",
"pinDetail": {
"serial": 558111,
"info1": "DIAL *611",
"info2": "DIAL *611",
"info3": "DIAL *611",
"value": null,
"code": 773709733097662,
"ivr": "1-888-888-8888",
"validity": "30 days"
},
"balanceInfo": {
"cost": 1,
"currencyCode": "USD",
"currencyName": "US Dollar",
"newBalance": 35082.72087,
"oldBalance": 35083.72087,
"updatedAt": "2023-09-20 13:49:40"
}
}
}
The Airtime Transactions feature serves as a ledger that enables you to access information on every top-up carried out on an account. Every transaction has two unique IDs — one is a serial ID for each transaction done by an account and the other is a transaction ID assigned by the operator where the top-up was made. Important data in the details of every airtime transaction include the transaction ID, transaction date, operator's name, recipient's mobile number, sender's mobile number, and the discount applied to the transaction — if there was any.
Retrieve the details of every top-up transaction carried out on your Reloadly account.
Security BearerToken
HTTP: BearerToken
HTTP Authorization Scheme: bearer
Request
QUERY PARAMETERS
size
Integer
This indicates the number of transactions to be retrieved on a page. Default value is 200.
Example: 10
page
Integer
This indicates the page of the transactions list being retrieved. Default value is 1.
Example: 1
countryCode
String
Indicates the ISO code of the country assigned to the top-up's receiver at the time the top-up transaction was made.
Example: US
operatorId
String
Indicates the operator identification number assigned to the top-up transaction at the time it was made.
Example: 341
operatorName
String
Indicates the operator name assigned to the top-up transaction at the time it was made.
Example: MTN Nigeria
customIdentifier
String
Indicates the unique reference assigned to the top-up transaction at the time it was made.
Example: april-top-up
startDate
String
Indicates the beginning of the timeframe range for the transactions to be retrieved.
Example: 2021-04-30 00:00:00
endDate
String
Indicates the end of the timeframe range for the transactions to be retrieved.
Example: 2021-07-30 00:00:00
Response
200
Successfully retrieved details of all transactions.
401
Failed due to an unauthorized request.
404
Failed because the request was made to an incorrect URL path.
Production URL
Sandbox URL
GET https://topups.reloadly.com/topups/reports/transactions
REQUEST SAMPLES
cURL
Node
Python
C#
JAVA
Go
PHP
R
Ruby
Swift
RESPONSE SAMPLES
200
401
404
{
"content": [
{
"transactionId": 4602843,
"status": "SUCCESSFUL",
"operatorTransactionId": "7297929551:OrderConfirmed",
"customIdentifier": "This is example identifier 130",
"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": 4.9985,
"deliveredAmountCurrencyCode": "GBP",
"transactionDate": "2021-12-06 08:13:39",
"pinDetail": {
"serial": 558111,
"info1": "DIAL *611",
"info2": "DIAL *611",
"info3": "DIAL *611",
"value": null,
"code": 773709733097662,
"ivr": "1-888-888-8888",
"validity": "30 days"
},
"balanceInfo": null
},
{},
{}
]
}
Retrieve the details of a top-up transaction by making a request with its identification number.
Security BearerToken
HTTP: BearerToken
HTTP Authorization Scheme: bearer
Request
PATH PARAMETERS
transactionId
requiredInteger
This indicates the identification number of the transaction to be retrieved.
Example: 101
Response
200
Successfully retrieved details of a transaction.
401
Failed due to an unauthorized request.
404
Failed because the request was made to an incorrect URL path.
Production URL
Sandbox URL
GET https://topups.reloadly.com/topups/reports/transactions/{transactionId}
REQUEST SAMPLES
cURL
Node
Python
C#
JAVA
Go
PHP
R
Ruby
Swift
RESPONSE SAMPLES
200
401
404
{
"transactionId": 4602843,
"status": "SUCCESSFUL",
"operatorTransactionId": "7297929551:OrderConfirmed",
"customIdentifier": "This is example identifier 130",
"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": 4.9985,
"deliveredAmountCurrencyCode": "GBP",
"transactionDate": "2021-12-06 08:13:39",
"pinDetail": {
"serial": 558111,
"info1": "DIAL *611",
"info2": "DIAL *611",
"info3": "DIAL *611",
"value": null,
"code": 773709733097662,
"ivr": "1-888-888-8888",
"validity": "30 days"
},
"balanceInfo": null
}
Reloadly offers a mobile number portability (MNP) lookup service that enables you to retrieve the network operator details of a mobile number.
There is a rising trend where mobile numbers are ported to a different network operator. The carrier lookup service reveals the current network operator of these numbers and optimizes their routes for actions like calls, SMS, and data bundles.
This service allows a user to retrieve details of a mobile number regardless of whether it has been ported. The user may make an HTTP GET or POST request to retrieve the details of the mobile number.
.
Reloadly has an open-source library used to format, parse, and validate the authenticity of an international phone number. You can check it out here on GitHub.
Do note that this is a PAID service. As such, there is a pricing schedule attached to this service. You can find more details on the pricing through your dashboard. Alternatively, if you have any questions, you can always reach out to us via our developer community
The GET method receives the mobile number and the given ISO code of the country where the mobile number is registered as path parameters to make this request. A developer may make use of the GET method when retrieving the details of a number under the following circumstances
● The number details to be retrieved need to be cached.
● The number details to be retrieved are not sensitive - this is determined by the use case involved.
● Details for a single mobile number are required.
Security BearerToken
HTTP: BearerToken
HTTP Authorization Scheme: bearer
Request
PATH PARAMETERS
phone
requiredNumber
This is the mobile number whose details are to be retrieved.
Example: 8147658721
countryCode
requiredQUERY PARAMETERS
suggestedAmountsMap
Boolean
Indicates if this field should be returned as a response. Default value is false.
Example: false
suggestedAmounts
Boolean
Indicates if this field should be returned as a response. Default value is false.
Example: false
Response
200
Successfully retrieved details of a mobile number
401
Failed due to an unauthorized request
404
Failed because the details of a mobile number's operator could not be retrieved.
Production URL
Sandbox URL
GET https://topups.reloadly.com/operators/mnp-lookup/phone/{phone}/countries/{countryCode}
REQUEST SAMPLES
cURL
Node
Python
C#
JAVA
Go
PHP
R
Ruby
Swift
RESPONSE SAMPLES
200
401
404
{
"id": 88,
"operatorId": 88,
"name": "Movistar Colombia",
"bundle": false,
"data": false,
"comboProduct": false,
"pin": false,
"supportsLocalAmounts": false,
"denominationType": "RANGE",
"senderCurrencyCode": "USD",
"senderCurrencySymbol": "$",
"destinationCurrencyCode": "COP",
"destinationCurrencySymbol": "$",
"commission": 4.42,
"internationalDiscount": 4.42,
"localDiscount": 0,
"mostPopularAmount": null,
"minAmount": 5,
"maxAmount": 5,
"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
],
"suggestedAmountsMap": {
"7": 19482.51,
"10": 27832.16,
"15": 41748.23
},
"promotions": []
}
The POST method receives the mobile number and the given ISO code of the country where the mobile number is registered as body parameters to make this request. A developer may make use of the POST method when retrieving the details of a number under the following conditions
● The number details to be retrieved are not to be stored or cached.
● The number details to be retrieved are sensitive and need to be protected.
● Details for multiple mobile numbers are required.
Security BearerToken
HTTP: BearerToken
HTTP Authorization Scheme: bearer
Request
REQUEST BODY SCHEMA: application/json
PAYLOAD DESCRIPTION
countryCode
number
string
This is the mobile number whose operator details are to be retrieved.
Example: 3238482221
Response
200
Successfully retrieved details of a mobile number
401
Failed due to an unauthorized request
404
Failed because the details of a mobile number's operator could not be retrieved.
Production URL
Sandbox URL
POST https://topups.reloadly.com/mnp-lookup/operators
REQUEST SAMPLES
cURL
Node
Python
C#
JAVA
Go
PHP
R
Ruby
Swift
RESPONSE SAMPLES
200
401
404
{
"id": 88,
"operatorId": 88,
"name": "Movistar Colombia",
"bundle": false,
"data": false,
"comboProduct": false,
"pin": false,
"supportsLocalAmounts": false,
"denominationType": "RANGE",
"senderCurrencyCode": "USD",
"senderCurrencySymbol": "$",
"destinationCurrencyCode": "COP",
"destinationCurrencySymbol": "$",
"commission": 4.42,
"internationalDiscount": 4.42,
"localDiscount": 0,
"mostPopularAmount": null,
"minAmount": 5,
"maxAmount": 5,
"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
],
"suggestedAmountsMap": {
"7": 19482.51,
"10": 27832.16,
"15": 41748.23
},
"promotions": []
}