Access Token

AIRTIME

Access Token

open

request parameters

Parameter Description Default
client_id
Your client ID.  
client_secret
Your client secret.  
audience
The API you're requesting the access token for.

Live : https://topups.reloadly.com

Sandbox : https://topups-sandbox.reloadly.com

 
grant_type
The grant type. Set to client_credentials.  
open

response parameters

Response 200 Headers content-type: application/json
Parameter Description
access_token
string required
Access token for the account to be used in other endpoints.
scope
string required
Scopes available under the access token.
expires_in
number required
The expiry of the access token generated.
token_type
string required
The type of the token.
open

Tutorial Video

open

Test With Postman

You can test this endpoint using Postman. We have a preconfigured collection that you can download and use. Simply click the button below.

endpoint oauth/token

POST https://auth.reloadly.com/oauth/token
open

request

copy
open

Response

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

Account Balance

open

request parameters

Parameter Description Default
Authorization
string required
Endpoint requires Authentication token in header.  
open

response parameters

Response 200 Headers content-type: application/json
Parameter Description
Balance
number required
Current account balance amount.
CurrencyCode
string required
Account ISO-4217 3 letter currency code.
CurrencyName
string required
Account currency name for the given currency code.
updatedAt
string required
When was the last balance updated on the account.
open

Tutorial Video

open

Test With Postman

You can test this endpoint using Postman. We have a preconfigured collection that you can download and use. Simply click the button below.

endpoint account/balance

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

request

copy
open

Response

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

Discounts

open

request parameters

Parameter Description Default
page
integer optional
Page number Default value : 1
size
integer optional
Size of each Default value : 200
Authorization
string required
Endpoint requires Authentication token in header.  
open

response parameters

Response 200 Headers content-type: application/json
Parameter Description
content
collection required
Collection of simplifiedOperators objects.
first
boolean
If this is the first page or not.
last
boolean
If this is the last page or not.
number
integer
Current page number.
numberOfElements
integer
Number of elements within this page's content.
pageable
object
A pagable object defining params to be used for paging.
sort
object
A Sort element to be used for sorting the collection.
totalElements
integer
Total number of elements available.
totalPages
integer
Total number of pages available.
open

Tutorial Video

open

Test With Postman

You can test this endpoint using Postman. We have a preconfigured collection that you can download and use. Simply click the button below.

endpoint operators/commissions

GET GET : https://topups.reloadly.com/operators/commissions?page=1&size=3
open

request

copy
open

Response

Body {   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 }

Discounts by operator id

open

request parameters

Parameter Description Default
Authorization
string required
Endpoint requires Authentication token in header.  
operatorId
integer required
Operator's Id for which to fetch the discounts for.  
open

response parameters

Response 200 Headers content-type: application/json
Parameter Description
Percentage
decimal
Total Commission percentage.
internationalPercentage
decimal
International discount for this operator. Available when you send money from a different country's account.
localPercentage
decimal
Local discount for this operator. Available when you send money from the same country's account as the operator.
UpdatedAt
string($date-time)
Commission last updated date. ISO-8601 without timezone (yyyy-MM-dd HH:mm:ss).
Operator
object
Operator Object containing operator details.
open

Tutorial Video

open

Test With Postman

You can test this endpoint using Postman. We have a preconfigured collection that you can download and use. Simply click the button below.

endpoint /operators/{operatorId}/commissions

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

request

copy
open

Response

Body     {       "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"     },

FX Rate

open

request parameters

Parameter Description Default
operatorId
integer required
Operator Id.
amount
integer required
The amount fx rate.
Authorization
string required
Endpoint requires Authentication token in header.  
open

response parameters

Response 200 Headers content-type: application/json
Parameter Description
id
integer
Operator Id.
Name
string
Operator name.
fxRate
integer
The FX Rate for the inputed amount.
currencyCode
string required
ISO-4217 3 letter currency code.
open

Tutorial Video

open

Test With Postman

You can test this endpoint using Postman. We have a preconfigured collection that you can download and use. Simply click the button below.

endpoint /operators/fx-rate

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

request

copy
open

Response

Body {       "id": 174,       "name": "Natcom Haiti",       "fxRate": 465.00,       "currencyCode": "HTG" }

Countries

open

request parameters

Parameter Description Default
open

response parameters

Response 200 Headers content-type: application/json
Parameter Description
Body
array
Complete List of all countries
open

Tutorial Video

open

Test With Postman

You can test this endpoint using Postman. We have a preconfigured collection that you can download and use. Simply click the button below.

endpoint /countries

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

request

copy
open

Response

Body {   [     {        "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"       ]     } ] }

Countries ISO code(ISO Alpha-2)

open

request parameters

Parameter Description Default
countryIsoCode
string required
The country's ISO Code.  
open

response parameters

Response 200 Headers content-type: application/json
Parameter Description
IsoName
string
ISO 3166-1 alpha-2 Country code.
Name
string
Full name of country.
CurrencyCode
string
Account ISO-4217 3 letter currency code for the given country.
CurrencyName
string
Full currency name.
currencySymbol
string
Symbol for the Currency.
Flag
string
Url of country flag image.
CallingCodes
array
Calling codes of country.
open

Tutorial Video

open

Test With Postman

You can test this endpoint using Postman. We have a preconfigured collection that you can download and use. Simply click the button below.

endpoint /countries/{countryIsoCode}

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

request

copy
open

Response

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

Operators

open

request parameters

Parameter Description Default
page
integer optional
Page number Default value : 1
size
integer optional
Size of each Default value : 200
suggestedAmounts
boolen optional
Whether to return the suggestedAmounts field on the Operator resource. False
suggestedAmounts Map
boolen optional
Whether to return the suggestedAmountsMap field on the Operator resource. False
simplified
boolen optional
Whether to return Simplified response or Detailed one. False
includePin
boolen optional
Whether to include PIN details in the operators resources list. True
includeData
boolen optional
Whether to include airtime/data bundles in the operators resources list. True
includeBundles
boolen optional
Whether to include airtime/data bundles in the operators resources list. True
Authorization
string required
Endpoint requires Authentication token in header.  
open

response parameters

Response 200 Headers content-type: application/json
Parameter Description
content
collection
Collection of Operators objects. See content details here
first
boolean
If this is the first page or not.
last
boolean
If this is the last page or not.
number
integer
Current page number.
numberOfElements
integer
Number of elements within this page's content.
pageable
boolean
A pagable object defining params to be used for paging.
sort
boolean
A Sort element to be used for sorting the collection.
totalElements
integer
Total number of elements available.
totalPages
integer
Total number of pages available.
open

Tutorial Video

open

Test With Postman

You can test this endpoint using Postman. We have a preconfigured collection that you can download and use. Simply click the button below.

endpoint operators

GET GET : https://topups.reloadly.com/operators?page=1&size=3&suggestedAmounts=true&suggestedAmountsMap=true&includeBundles=true
open

request

copy
open

Response

Body  {   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 }

Operators by id

open

request parameters

Parameter Description Default
operatorId
integer required
The Operator's Id.
suggestedAmounts
boolen optional
Whether to return the suggestedAmounts field on the Operator resource. False
suggestedAmountsMap
boolen optional
Whether to return the suggestedAmountsMap field on the Operator resource. False
Authorization
string required
Endpoint requires Authentication token in header.  
open

response parameters

Response 200 Headers content-type: application/json
Parameter Description
operatorId
integer
Unique identifier for the operator, positive integer
name
string
Name of the operator
bundle
boolean
Whether the operator is a prepaid data bundle. Prepaid bundles are a mixture of calls, data, SMS and social media access which the users can purchase other than airtime credits.
data
boolean
Whether the operator is a data operator.
pin
boolean
Whether the operator is a PIN based operator. These operators will return you with PIN details on topup. Each PIN detail will define how to make the topup on the physical sim card by entering the code on the given number.
supportsLocalAmounts
boolean
Whether the operator supports local amounts for top-up. When value is true, the fields localMinAmount, localMaxAmount and localFixedAmounts will be populated. Based on what denominationType the operator is off.
denominationType
string
The type of denomination supported by this operator, values can be FIXED or RANGE.
When value is RANGE, the fields minAmount and maxAmount will be populated. When the value is FIXED, the fixedAmounts field will be populated
senderCurrencyCode
string
ISO-3 currency code of user (you) account, example USD
senderCurrencySymbol
string
User account currency symbol, example $
destinationCurrencyCode
string
ISO-3 currency code of the country of the airtime recipient, example EUR
destinationCurrencySymbol
string
Recipient's country currency symbol, example
commission
decimal
Discount percentage assigned to user's account for this operator. Note: This field is identical to internationalDiscount. commission is being deprecated in favor of internationalDiscountand will be removed in future versions.
internationalDiscount
decimal
Discount percentage assigned to user's account for this operator. Note: This field is identical to commission. commission is being deprecated in favor of internationalDiscountand will be removed in future versions.
localDiscount
decimal
Discount percentage assigned to user's account for this operator for local topups (if available to user's account) Note: Local discount may not always be available for all operators, please contact sales for more details.
mostPopularAmount
decimal
Most popular amount of this operator.
mostPopularLocalAmount
decimal
Most popular amount (in local currency) of this operator. (Note : Only available when the operator supports local amounts)
minAmount
decimal
Minimum amount that must be used to send transactions for this operator. This field is populated when denominationType is RANGE, will be set to null/empty otherwise.
maxAmount
decimal
Maximum amount that must be used to send transactions for this operator. This field is populated when denominationType is RANGE, will be set to null/empty otherwise.
localMinAmount
decimal
Minimum amount (in local currency) that must be used to send transactions for this operator. This field is populated when denominationType is RANGE, will be set to null/empty otherwise. (Note : Only available when the operator supports local amounts)
localMaxAmount
decimal
Maximum amount (in local currency) that must be used to send transactions for this operator. This field is populated when denominationType is RANGE, will be set to null/empty otherwise. (Note : Only available when the operator supports local amounts)
country
object
Country of the world to which this operator belongs. This field is made up of 2 fields :
  1. isoName
    ISO 3166-1 alpha-2 Country code, ex : US. See more details here.
  2. name
    Name of the country
fx
object
FX-Rate of the operator (based on the account's currency) This field is made up of 2 fields :
  1. rate
    The rate for the operator.
  2. currencyCode
    Currency Code for the Operator
logoUrls
array
Array of 3 URLs of the mobile operators logo, 3 different size are provided.
fixedAmounts
array of decimals
Array of available amounts that can be used to send transactions to this operator. This field will be populated when denominationType is FIXED, it will be empty otherwise.
fixedAmountsDescriptions
object
Object with each fixed ammount and its descriptor.
localFixedAmounts
array of decimals
Array of available amounts (in local currency) that can be used to send transactions to this operator. This field will be populated when denominationType is FIXED, it will be empty otherwise. (Note : Only available when the operator supports local amounts)
localFixedAmountsDescriptions
object
Object with each fixed amount (in local currency) and its descriptor. (Note : Only available when the operator supports local amounts)
suggestedAmounts
array of decimals
Suggested amounts when denomination type is 'FIXED'. This field is populated when request parameter suggestedAmounts=true is passed in the operator request.
suggestedAmountsMap
object
Suggested amounts map containing (amount in sender currency, amount in recipient currency) when denomination type is 'FIXED'. This field is populated when request parameter suggestedAmountsMap=true is passed in the operator request.
promotions
array
Currently available promotions for this operator. See the Promotions end points.
open

Tutorial Video

open

Test With Postman

You can test this endpoint using Postman. We have a preconfigured collection that you can download and use. Simply click the button below.

endpoint /operators/{operatorId}

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

request

copy
open

Response

Body     {        "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": []     }

Operators for given phone number

open

request parameters

Parameter Description Default
Phone
string required
Phone number with country prefix.
countryCode
string required
ISO 3166-1 alpha-2 Country code. False
SuggestedAmounts
boolean optional
Whether to return the suggestedAmounts field on the Operator resource. False
suggestedAmountsMap
boolen optional
Whether to return the suggestedAmountsMap field on the Operator resource. False
Authorization
string required
Endpoint requires Authentication token in header.  
open

response parameters

Response 200 Headers content-type: application/json
Parameter Description
operatorId
integer
Unique identifier for the operator, positive integer
name
string
Name of the operator
bundle
boolean
Whether the operator is a prepaid data bundle. Prepaid bundles are a mixture of calls, data, SMS and social media access which the users can purchase other than airtime credits.
data
boolean
Whether the operator is a data operator.
pin
boolean
Whether the operator is a PIN based operator. These operators will return you with PIN details on topup. Each PIN detail will define how to make the topup on the physical sim card by entering the code on the given number.
supportsLocalAmounts
boolean
Whether the operator supports local amounts for top-up. When value is true, the fields localMinAmount, localMaxAmount and localFixedAmounts will be populated. Based on what denominationType the operator is off.
denominationType
string
The type of denomination supported by this operator, values can be FIXED or RANGE.
When value is RANGE, the fields minAmount and maxAmount will be populated. When the value is FIXED, the fixedAmounts field will be populated
senderCurrencyCode
string
ISO-3 currency code of user (you) account, example USD
senderCurrencySymbol
string
User account currency symbol, example $
destinationCurrencyCode
string
ISO-3 currency code of the country of the airtime recipient, example EUR
destinationCurrencySymbol
string
Recipient's country currency symbol, example
commission
decimal
Discount percentage assigned to user's account for this operator. Note: This field is identical to internationalDiscount. commission is being deprecated in favor of internationalDiscountand will be removed in future versions.
internationalDiscount
decimal
Discount percentage assigned to user's account for this operator. Note: This field is identical to commission. commission is being deprecated in favor of internationalDiscountand will be removed in future versions.
localDiscount
decimal
Discount percentage assigned to user's account for this operator for local topups (if available to user's account) Note: Local discount may not always be available for all operators, please contact sales for more details.
mostPopularAmount
decimal
Most popular amount of this operator.
mostPopularLocalAmount
decimal
Most popular amount (in local currency) of this operator. (Note : Only available when the operator supports local amounts)
minAmount
decimal
Minimum amount that must be used to send transactions for this operator. This field is populated when denominationType is RANGE, will be set to null/empty otherwise.
maxAmount
decimal
Maximum amount that must be used to send transactions for this operator. This field is populated when denominationType is RANGE, will be set to null/empty otherwise.
localMinAmount
decimal
Minimum amount (in local currency) that must be used to send transactions for this operator. This field is populated when denominationType is RANGE, will be set to null/empty otherwise. (Note : Only available when the operator supports local amounts)
localMaxAmount
decimal
Maximum amount (in local currency) that must be used to send transactions for this operator. This field is populated when denominationType is RANGE, will be set to null/empty otherwise. (Note : Only available when the operator supports local amounts)
country
object
Country of the world to which this operator belongs. This field is made up of 2 fields :
  1. isoName
    ISO 3166-1 alpha-2 Country code, ex : US. See more details here.
  2. name
    Name of the country
fx
object
FX-Rate of the operator (based on the account's currency) This field is made up of 2 fields :
  1. rate
    The rate for the operator.
  2. currencyCode
    Currency Code for the Operator
logoUrls
array
Array of 3 URLs of the mobile operators logo, 3 different size are provided.
fixedAmounts
array of decimals
Array of available amounts that can be used to send transactions to this operator. This field will be populated when denominationType is FIXED, it will be empty otherwise.
fixedAmountsDescriptions
object
Object with each fixed ammount and its descriptor.
localFixedAmounts
array of decimals
Array of available amounts (in local currency) that can be used to send transactions to this operator. This field will be populated when denominationType is FIXED, it will be empty otherwise. (Note : Only available when the operator supports local amounts)
localFixedAmountsDescriptions
object
Object with each fixed amount (in local currency) and its descriptor. (Note : Only available when the operator supports local amounts)
suggestedAmounts
array of decimals
Suggested amounts when denomination type is 'FIXED'. This field is populated when request parameter suggestedAmounts=true is passed in the operator request.
suggestedAmountsMap
object
Suggested amounts map containing (amount in sender currency, amount in recipient currency) when denomination type is 'FIXED'. This field is populated when request parameter suggestedAmountsMap=true is passed in the operator request.
promotions
array
Currently available promotions for this operator. See the Promotions end points.
open

Tutorial Video

open

Test With Postman

You can test this endpoint using Postman. We have a preconfigured collection that you can download and use. Simply click the button below.

endpoint operators/auto-detect/phone/{phone}/countries/{iso}

GET https://topups.reloadly.com/operators/auto-detect/phone/+50936377111/countries/HT?&includeBundles=true
open

request

copy
open

Response

Body     {        "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": []     }

Operators by (ISO)

open

request parameters

Parameter Description Default
countryCode
string required
ISO 3166-1 alpha-2 Country code.
includeBundles
boolen optional
If to include bundle details of the operator with the response True
includeData
boolen optional
If to include data details of the operator with the response True
includePin
boolen optional
If to include pin details of the operator with the response True
suggestedAmounts
boolen optional
Whether to return the suggestedAmounts fields on the Operator resource False
suggestedAmountsMap
boolen optional
Whether to return the suggestedAmountsMAP fields on the Operator resource False
Authorization
string required
Endpoint requires Authentication token in header.  
open

response parameters

Response 200 Headers content-type: application/json
Parameter Description
operatorId
integer
Unique identifier for the operator, positive integer
name
string
Name of the operator
bundle
boolean
Whether the operator is a prepaid data bundle. Prepaid bundles are a mixture of calls, data, SMS and social media access which the users can purchase other than airtime credits.
data
boolean
Whether the operator is a data operator.
pin
boolean
Whether the operator is a PIN based operator. These operators will return you with PIN details on topup. Each PIN detail will define how to make the topup on the physical sim card by entering the code on the given number.
supportsLocalAmounts
boolean
Whether the operator supports local amounts for top-up. When value is true, the fields localMinAmount, localMaxAmount and localFixedAmounts will be populated. Based on what denominationType the operator is off.
denominationType
string
The type of denomination supported by this operator, values can be FIXED or RANGE.
When value is RANGE, the fields minAmount and maxAmount will be populated. When the value is FIXED, the fixedAmounts field will be populated
senderCurrencyCode
string
ISO-3 currency code of user (you) account, example USD
senderCurrencySymbol
string
User account currency symbol, example $
destinationCurrencyCode
string
ISO-3 currency code of the country of the airtime recipient, example EUR
destinationCurrencySymbol
string
Recipient's country currency symbol, example
commission
decimal
Discount percentage assigned to user's account for this operator. Note: This field is identical to internationalDiscount. commission is being deprecated in favor of internationalDiscountand will be removed in future versions.
internationalDiscount
decimal
Discount percentage assigned to user's account for this operator. Note: This field is identical to commission. commission is being deprecated in favor of internationalDiscountand will be removed in future versions.
localDiscount
decimal
Discount percentage assigned to user's account for this operator for local topups (if available to user's account) Note: Local discount may not always be available for all operators, please contact sales for more details.
mostPopularAmount
decimal
Most popular amount of this operator.
mostPopularLocalAmount
decimal
Most popular amount (in local currency) of this operator. (Note : Only available when the operator supports local amounts)
minAmount
decimal
Minimum amount that must be used to send transactions for this operator. This field is populated when denominationType is RANGE, will be set to null/empty otherwise.
maxAmount
decimal
Maximum amount that must be used to send transactions for this operator. This field is populated when denominationType is RANGE, will be set to null/empty otherwise.
localMinAmount
decimal
Minimum amount (in local currency) that must be used to send transactions for this operator. This field is populated when denominationType is RANGE, will be set to null/empty otherwise. (Note : Only available when the operator supports local amounts)
localMaxAmount
decimal
Maximum amount (in local currency) that must be used to send transactions for this operator. This field is populated when denominationType is RANGE, will be set to null/empty otherwise. (Note : Only available when the operator supports local amounts)
country
object
Country of the world to which this operator belongs. This field is made up of 2 fields :
  1. isoName
    ISO 3166-1 alpha-2 Country code, ex : US. See more details here.
  2. name
    Name of the country
fx
object
FX-Rate of the operator (based on the account's currency) This field is made up of 2 fields :
  1. rate
    The rate for the operator.
  2. currencyCode
    Currency Code for the Operator
logoUrls
array
Array of 3 URLs of the mobile operators logo, 3 different size are provided.
fixedAmounts
array of decimals
Array of available amounts that can be used to send transactions to this operator. This field will be populated when denominationType is FIXED, it will be empty otherwise.
fixedAmountsDescriptions
object
Object with each fixed ammount and its descriptor.
localFixedAmounts
array of decimals
Array of available amounts (in local currency) that can be used to send transactions to this operator. This field will be populated when denominationType is FIXED, it will be empty otherwise. (Note : Only available when the operator supports local amounts)
localFixedAmountsDescriptions
object
Object with each fixed amount (in local currency) and its descriptor. (Note : Only available when the operator supports local amounts)
suggestedAmounts
array of decimals
Suggested amounts when denomination type is 'FIXED'. This field is populated when request parameter suggestedAmounts=true is passed in the operator request.
suggestedAmountsMap
object
Suggested amounts map containing (amount in sender currency, amount in recipient currency) when denomination type is 'FIXED'. This field is populated when request parameter suggestedAmountsMap=true is passed in the operator request.
promotions
array
Currently available promotions for this operator. See the Promotions end points.
open

Tutorial Video

open

Test With Postman

You can test this endpoint using Postman. We have a preconfigured collection that you can download and use. Simply click the button below.

endpoint /operators/countries/{countryIsoCode}

GET https://topups.reloadly.com/operators/countries/HT
open

request

copy
open

Response

Body [     {        "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": []     } ]

Promotions

open

request parameters

Parameter Description Default
page
integer optional
Page number Default value : 1
size
integer optional
Size of each Default value : 200
Authorization
string required
Endpoint requires Authentication token in header.  
open

response parameters

Response 200 Headers content-type: application/json
Parameter Description
content
collection
Collection of Operators objects.
first
boolean
If this is the first page or not.
last
boolean
If this is the last page or not.
number
integer
Current page number.
numberOfElements
integer
Number of elements within this page's content.
pageable
boolean
A pagable object defining params to be used for paging.
sort
boolean
A Sort element to be used for sorting the collection.
totalElements
integer
Total number of elements available.
totalPages
integer
Total number of pages available.
open

Tutorial Video

open

Test With Postman

You can test this endpoint using Postman. We have a preconfigured collection that you can download and use. Simply click the button below.

endpoint promotions

GET https://topups.reloadly.com/promotions?page=1&size=3
open

request

copy
open

Response

Body {   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 }

Promotions by id

open

request parameters

Parameter Description Default
promotionId
integer required
The promotional ID.
Authorization
string required
Endpoint requires Authentication token in header.  
open

response parameters

Response 200 Headers content-type: application/json
Parameter Description
promotionId
integer
Unique identifier for a given promotion.
operatorId
integer
Id of operator to which the promotion applies.
title
string
Title of the promotion.
title2
string
2nd title for the promotion if any.
description
string
Description of the promotion.
startDate
string
Date on which the promotion starts.
endDate
string
Date on which the promotion ends.
denominations
string
Amounts for which the promotion applies.
localDenominations
string
Amounts (in destination country currency) for which the promotion applies.
open

Tutorial Video

open

Test With Postman

You can test this endpoint using Postman. We have a preconfigured collection that you can download and use. Simply click the button below.

endpoint /promotions/{promotionId}

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

request

copy
open

Response

Body  {       "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  }

Promotions by country Code

open

request parameters

Parameter Description Default
Authorization
string required
Endpoint requires Authentication token in header.  
CountryCode
string required
countryCode  
open

response parameters

Response 200 Headers content-type: application/json
Parameter Description
promotionId
integer
Unique identifier for a given promotion.
operatorId
integer
Id of operator to which the promotion applies.
title
string
Title of the promotion.
title2
string
2nd title for the promotion if any.
description
string
Description of the promotion.
startDate
string
Date on which the promotion starts.
endDate
string
Date on which the promotion ends.
denominations
string
Amounts for which the promotion applies.
localDenominations
string
Amounts (in destination country currency) for which the promotion applies.
open

Tutorial Video

open

Test With Postman

You can test this endpoint using Postman. We have a preconfigured collection that you can download and use. Simply click the button below.

endpoint /promotions/country-codes/{countryCode}

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

request

copy
open

Response

Body   [     {       "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     }   ]

Promotions by operator id

open

request parameters

Parameter Description Default
operatorId
integer required
The Operator's Id.
Authorization
string required
Endpoint requires Authentication token in header.  
open

response parameters

Response 200 Headers content-type: application/json
Parameter Description
promotionId
integer
The Promotion Id.
operatorId
integer
The Operator Id.
title
string
Title of the promotion.
title2
string
2nd title for the promotion if any.
description
string
Description of the promotion.
startDate
string
Date on which the promotion starts.
endDate
string
Date on which the promotion ends.
denominations
string
Amounts for which the promotion applies.
localDenominations
string
Amounts (in destination country currency) for which the promotion applies.
open

Tutorial Video

open

Test With Postman

You can test this endpoint using Postman. We have a preconfigured collection that you can download and use. Simply click the button below.

endpoint /promotions/operators/{operatorId}

GET https://topups.reloadly.com/promotions/operators/129
open

request

copy
open

Response

Body   [     {       "promotionId": 1,       "operatorId": 129,       "title": " Tigo El Salvador From 25 Jun 2018 00:00 To 25 Jun 2018 23:59 (GMT-06:00)",       "title2": "Get 500 MB and 150 minutes for USA or Canada",       "description": "- For top ups of $10 or more, customers in El Salvador receive the top up plus 500 MBs + 150 Minutes for USA/CAN for 15 days.- The benefits are applied when the top up is received by the user in El Salvador.- Promotional minutes are valid to call any phone number in the USA.- The promotional benefits will be available for use during a period of 360 hours after the top up was received. (15 days)",       "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": 6,       "operatorId": 129,       "title": " Tigo El Salvador From 25 Jun 2018 00:00 To 25 Jun 2018 23:59 (GMT-06:00)",       "title2": "Get 300 MB and 60 minutes for USA or Canada",       "description": "- For top ups between USD $7 and up, customers will receive 300 additional MBs + 60 Minutes for USA/CAN- Promotional balance will expire in 5 days",       "startDate": "Mon, 25 Jun 2018 06:00:00 +0000",       "endDate": "Tue, 26 Jun 2018 05:59:00 +0000",       "denominations": "USD 7 and up",       "localDenominations": null     },     {       "promotionId": 9,       "operatorId": 129,       "title": " Tigo El Salvador From 25 Jun 2018 00:00 To 25 Jun 2018 23:59 (GMT-06:00)",       "title2": "Get 300 MB and 60 minutes for USA or Canada",       "description": "- For top ups between USD $7 and up, customers will receive 300 additional MBs + 60 Minutes for USA/CAN- Promotional balance will expire in 5 days",       "startDate": "Fri, 29 Jun 2018 06:00:00 +0000",       "endDate": "Sat, 30 Jun 2018 05:59:00 +0000",       "denominations": "USD 7 and up",       "localDenominations": null     }   ]

Topups

open

request parameters

Parameter Description Default
operatorId
integer required
The Operator's Id.
amount
integer required
The amount of topup.
useLocalAmount
boolean optional
If the amount is in Local currency of the operator or not. Default : false. Note( Only available for operators that support local topups. Please check operators endpoint for this)
customIdentifier
string optional
Custom Identifier for the transaction.  
recipientPhone
object optional
The recipient's Phone object. Required When Operator is not Nauta Cuba  
recipientEmail
string optional
The recipient's Email Address. Required When Operator is Nauta Cuba
Supports only two email domains
  • @nauta.com.cu
  • @nauta.co.cu
 
senderPhone
object optional
The sender's Phone object.
Authorization
string required
Endpoint requires Authentication token in header.  
open

response parameters

Response 200 Headers content-type: application/json
Parameter Description
transactionId
integer
The Transaction Id.
recipientPhone
string
The phone number of recipient.
recipientEmail
string
The email of recipient. (ONLY IF OPERATOR IS NAUTA CUBA)
senderPhone
string
The phone number of sender.
countryCode
string
ISO 3166-1 alpha-2 country code of topup destination country.
operatorId
integer
The Operator Id.
operatorName
string
The Operator's Name.
requestedAmount
decimal
Topup amount that was requested by sender.
discount
decimal
Discount amount for the transaction.
discountCurrencyCode
string
Discount currency code for the transaction.
requestedAmountCurrencyCode
string
ISO-4217 3 letter currency code of requestedAmount field.
deliveredAmount
decimal
Amount that was delivered in local currency.
deliveredAmountCurrencyCode
string
ISO-4217 3 letter currency code of deliveredAmount field.
customIdentifier
string
Value of the custom identifier field sent in the topup request.
transactionDate
string (date-time)
Time stamp recorded for this transaction.
balanceInfo
object
Balance info after and before the transaction with change.
pinDetail
object
PIN detail info. With Code and information on how to process the PIN on the physical SIM. (Note : Only for operators that support PIN Topup)
open

Tutorial Video

open

Test With Postman

You can test this endpoint using Postman. We have a preconfigured collection that you can download and use. Simply click the button below.

endpoint /topups

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

request

copy
open

Response

Body {       "transactionId": 282571,       "operatorTransactionId": null,       "customIdentifier": "my-custom-identifier-for-internal-usage",       "recipientPhone": "50936377111",       "senderPhone": "13059547862",       "countryCode": "HT",       "operatorId": 174,       "operatorName": "Natcom Haiti",       "discount": 1.4,       "discountCurrencyCode": "USD",       "requestedAmount": 10,       "requestedAmountCurrencyCode": "USD",       "deliveredAmount": 930.00,       "deliveredAmountCurrencyCode": "HTG",       "transactionDate": "2020-01-31 07:43:36"       "pinDetail": null }
//Sample response with "pinDetails"
Body {       "transactionId": 282571,       "operatorTransactionId": 578458945,       "customIdentifier": "fduif0-43844-djdsdiu-3223",       "recipientPhone": "14388352599",       "senderPhone": "13059547862",       "countryCode": "CA",       "operatorId": 62,       "operatorName": "Rogers PIN Canada",       "discount": 0.26,       "discountCurrencyCode": "USD",       "requestedAmount": 8.55,       "requestedAmountCurrencyCode": "USD",       "deliveredAmount": 11.13,       "deliveredAmountCurrencyCode": "CAD",       "transactionDate": "2020-01-31 10:40:16"       "pinDetail": {        "serial": "846574"        "info1": "DIAL *611"        "info2": "DIAL *611"        "info3": "DIAL *611"        "value": null        "code": "773709732479946"        "ivr": "1-888-888-8888"        "validity": "90 days"       } }

Transactions

open

request parameters

Parameter Description Default
page
integer optional
Page number Default value : 1
size
integer optional
Size of each Default value : 100
countryCode
string optional
Country code to filter the transactions
customIdentifier
string optional
Custom Identifier to filter the transactions
endDate
string($date-time) optional
End Date to filter the transactions
operatorId
string optional
Operator Id to filter the transactions
operatorName
string optional
Operator Name to filter the transactions
startDate
string($date-time) optional
Start Date to filter the transactions
Authorization
string required
Endpoint requires Authentication token in header.  
open

response parameters

Response 200 Headers content-type: application/json
Parameter Description
content
collection
Collection of Operators objects.
first
boolean
If this is the first page or not.
last
boolean
If this is the last page or not.
number
integer
Current page number.
numberOfElements
integer
Number of elements within this page's content.
pageable
boolean
A pagable object defining params to be used for paging.
sort
boolean
A Sort element to be used for sorting the collection.
totalElements
integer
Total number of elements available.
totalPages
integer
Total number of pages available.
open

Tutorial Video

open

Test With Postman

You can test this endpoint using Postman. We have a preconfigured collection that you can download and use. Simply click the button below.

endpoint /topups/reports/transactions

GET https://topups.reloadly.com/topups/reports/transactions?page=1&size=1&startTime=2018-06-01 00:00:00&endTime=2018-06-26 23:59:59
open

request

copy
open

Response

Body {   content : [     {       "transactionId": 1,       "operatorTransactionId": 2541365,       "customIdentifier": "your-custom-id-that-you-sent-with-the-transaction",       "recipientPhone": "50936377111",       "senderPhone": "13059547862",       "countryCode": "HT",       "operatorId": 173,       "operatorName": "Digicel Haiti",       "discount": 1.3,       "discountCurrencyCode": "USD",       "requestedAmount": 10,       "requestedAmountCurrencyCode": "USD",       "deliveredAmount": 993.64,       "deliveredAmountCurrencyCode": "HTG",       "transactionDate": "2020-02-09 20:08:10"       "pinDetail": null     }   ]   "pageable": {     "sort": {       "unsorted": false,        "sorted": true     }     "pageSize": 100,     "pageNumber": 0,     "offset": 0,     "paged": true,     "unpaged": false   }   "totalPages": 1,   "totalElements": 1,   "last": false,   "sort": {       "unsorted": false,        "sorted":true   "first": true,   "numberOfElements": 1,   "size": 100,   "number": 0 }

Transactions by id

open

request parameters

Parameter Description Default
transactionId
integer optional
The transaction Id to be retrieved. 1
Authorization
string required
Endpoint requires Authentication token in header.  
open

response parameters

Response 200 Headers content-type: application/json
Parameter Description
operatorTransactionId
string
The Operator Id for the Transaction.
transactionId
integer
The Transaction Id.
recipientPhone
string
The phone number of recipient.
senderPhone
string
The phone number of sender.
countryCode
string
ISO 3166-1 alpha-2 country code of topup destination country.
operatorId
integer
The Operator Id.
requestedAmount
decimal
Topup amount that was requested by sender.
discount
decimal
Discount amount for the transaction.
discountCurrencyCode
string
ISO-4217 3 letter currency code of discount field.
requestedAmountCurrencyCode
string
ISO-4217 3 letter currency code of requestedAmount field.
deliveredAmount
decimal
Amount that was delivered in local currency.
deliveredAmountCurrencyCode
string
ISO-4217 3 letter currency code of deliveredAmount field.
customIdentifier
string
Value of the custom identifier field sent in the topup request.
transactionDate
string
Time stamp recorded for this transaction.
balanceInfo
object
Complete balance object at the time of transaction.
pinDetail
object
PIN detail info.
open

Tutorial Video

open

Test With Postman

You can test this endpoint using Postman. We have a preconfigured collection that you can download and use. Simply click the button below.

endpoint topups/reports/transactions/{transactionId}

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

request

copy
open

Response

Body {       "transactionId": 287924,       "operatorTransactionId": null,       "customIdentifier": "4378-ddi34d-ywue4-dju",       "recipientPhone": "14388352599",       "senderPhone": "13055555555",       "countryCode": "CA",       "operatorId": 62,       "operatorName": "Rogers PIN Canada",       "discount": 0.25,       "discountCurrencyCode": "USD",       "requestedAmount": 8.40,       "requestedAmountCurrencyCode": "USD",       "deliveredAmount": 11.12,       "deliveredAmountCurrencyCode": "CAD",       "transactionDate": "2020-02-09 21:16:07",       "pinDetail": {        "serial": "950189",        "info1": "DIAL *611",        "info2": "DIAL *611",        "info3": "Dial *233* and PIN #",        "value": null,        "code": "773709732335675",        "ivr": "1-888-888-8888",        "validity": "60 days" }
open open