Reloadly Mobile top up API enables your apps, websites and any other platforms to send mobile credit top ups to over 4.5 billion phones covering 600+ mobile operators worldwide. We provide a commission for every operator available. First you will need to create your account if you haven’t done so. Also, we suggest you download the Reloadly app to view and play with the user functionalities. This will better help guide you when integrating our APIs.

Get Started

Authentication & Authorization

The Reloadly APIs are HTTP-based RESTful APIs that use OAuth 2.0 protocol for authorization. API request and response bodies are formatted in JSON.

OAuth is an open standard that many companies use to provide secure access to protected resources.

When you create a developer account. Reloadly generates a set of OAuth client ID and secret credentials for your app for both sandbox and live environments. You pass these credentials in the Authorization header in the get access token request.

In exchange for these credentials, the Reloadly authorization server issues access tokens called bearer tokens that you use for authorization when you make REST API requests. A bearer token enables you to complete actions on behalf of, and with the approval of the resource owner.

The access_token field in the get access token response contains a bearer token, indicated by the token_type of Bearer :


Response [access_token]

      "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6Ik0wWXpRa",
      "scope": "{scopes}",
      "expires_in": 5184000,
      "token_type": "Bearer"

Include this bearer token in API requests in the Authorization header with the Bearer authentication scheme.


Sample Request

curl -v -X GET \
    -H "Accept: application/com.reloadly.topups-v1+json" \
    -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6Ik0wWXpRa" \

This above sample request uses a bearer token to list topup transactions for an user account :

Access tokens have a finite lifetime. The expires_in field in the get access token response indicates the lifetime, in seconds, of the access token. For example, an expiry value of 3600 indicates that the access token expires in one hour from the time the response was generated.

To detect when an access token expires, write code to either :

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

Before you create another token, re-use the access token until it expires. See the rate limiting guidelines.

API Requests

To construct a REST API request, combine these components :


request parameters

Component Description
The HTTP method
  • GET. Requests data from a resource.
  • POST. Submits data to a resource to process.
  • PUT. Updates a resource
  • PATCH. Partially updates a resource.
  • DELETE. Deletes a resource.
The URL to the API service
  • Sandbox.
  • Live.
The URI to the resource The resource to query, submit data to, update, or delete. For example, /reports/transactions.
Query parameters Optional. Controls which data appears in the response. Use to filter, limit the size of, and sort the data in an API response.
HTTP request headers Includes the Authorization header with the access token.
A JSON request body Required for most GET, POST, PUT, and PATCH calls.

Query Parameters

For most REST GET calls, you can specify one or more optional query parameters on the request URI to filter, limit the size of, and sort the data in an API response. For filter parameters, see the individual GET calls.

To limit, or page, and sort the data that is returned in some API responses, use these, or similar, query parameters :

Note : Not all pagination parameters are available for all API endpoints.


request parameters

Parameter Type Description
The number of items to list in the response.
The start date and time for the range to show in the response, in Internet date and time format. (ISO 8601) For example, startTime=2018-03-06 00:00:00
The end date and time for the range to show in the response, in Internet date and time format. (ISO 8601) For example, endTime=2016-03-06 23:59:59.
The zero-relative start index of the entire list of items that are returned in the response. So, the combination of page=0 and page_size=20 returns the first 20 items. The combination of page=20 and page_size=20 returns the next 20 items.
The number of items to return in the response.
Sorts the transactions in the response by a specified value, such as the create time or update time.
Sorts the items in the response in ascending or descending order.

For example, the API Request Bellow returns details for four invoices beginning with the third invoice and includes the total count of invoices in the response


Transaction Api Request

curl -v -X GET 00:00:00&endTime=2018-03-31 23:59:59 \
    -H "Accept: application/com.reloadly.topups-v1+json" \
    -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6Ik0wWXpRa" \

Request Headers

The commonly used HTTP request headers are :


request parameters

Header Description
Accept Required for operations with a response body. Specifies the response format. The syntax is:

Accept: application/format

Where format is com.reloadly.topups-v1+json .
Authorization Required to get an access token or make API calls.

To get an access token, set this header to your client_id and client_secret credentials.

Note: If you use cURL, specify -u "client_id:secret".

To make REST API calls, include the bearer token in the Authorization header with the Bearer authentication scheme:

Authorization: Bearer Access-Token
Content-Type Required for operations with a request body.

Specifies the request format. The syntax is:

Content-Type: application/format

Where format is json.

API Responses

Reloadly API calls return HTTP status codes. Some API calls also return JSON response bodies that include information about the resource including one or more contextual HATEOAS links. Use these links to request more information about and construct an API flow that is relative to a specific request.

HTTP status codes

Each REST API request returns a success or error status code.



request parameters

Status code Description
200 OK The request succeeded.
201 Created A POST method successfully created a resource. If the resource was already created by a previous execution of the same method, for example, the server returns the HTTP 200 OK status code.
202 Accepted The server accepted the request and will execute it later.
204 No Content The server successfully executed the method but returns no response body.


In the responses for failed requests, Reloadly returns HTTP 4XX or 5XX status codes.

For all errors except Identity errors, Reloadly returns an error response body that includes additional error details in this format: Error Response Format


Error Response Format

  "timeStamp": ERROR_TIME_STAMP (numerical),
  "message": "Account verification failed, invalid or expired token",
  "path": "/accounts/verify",
  "errorCode": "ERROR_CODE",

  // Some types of errors also include a details array:
  "details": [
        "field": "FIELD_NAME",
        "issue": "PROBLEM_WITH_FIELD"

In the responses, Reloadly returns these HTTP status codes for failed requests:


request parameters

HTTP status code Typical error code and error message Cause
400 Bad Request INVALID_REQUEST. Request is not well-formed, syntactically incorrect, or violates schema. See Validation errors. The server could not understand the request. Indicates one of these conditions:
  • The API cannot convert the payload data to the underlying data type.
  • he data is not in the expected data format.
  • A required field is not available.
  • A simple data validation error occurred.
401 Unauthorized AUTHENTICATION_FAILURE. Authentication failed due to invalid authentication credentials. See Authentication errors. The request requires authentication and the caller did not provide valid credentials.
403 Forbidden NOT_AUTHORIZED. Authorization failed due to insufficient permissions. The client is not authorized to access this resource although it might have valid credentials. For example, the client does not have the correct OAuth 2 scope. Additionally, a business-level authorization error might have occurred. For example, the account holder does not have sufficient funds.
404 Not Found RESOURCE_NOT_FOUND. The specified resource does not exist. The server did not find anything that matches the request URI. Either the URI is incorrect or the resource is not available. For example, no data exists in the database at that key.
405 Method Not Allowed METHOD_NOT_SUPPORTED. The server does not implement the requested HTTP method. The service does not support the requested HTTP method. For example, PATCH.
406 Not Acceptable MEDIA_TYPE_NOT_ACCEPTABLE. The server does not implement the media type that would be acceptable to the client. The server cannot use the client-request media type to return the response payload. For example, this error occurs if the client sends an Accept: application/xml request header but the API can generate only an application/json response.
415 Unsupported Media Type UNSUPPORTED_MEDIA_TYPE. The server does not support the request payload’s media type. The API cannot process the media type of the request payload. For example, this error occurs if the client sends a Content-Type: application/xml request header but the API can only accept application/json request payloads.
422 Unprocessable Entity UNPROCCESSABLE_ENTITY. The API cannot complete the requested action, or the request action is semantically incorrect or fails business validation. The API cannot complete the requested action and might require interaction with APIs or processes outside of the current request. No systemic problems limit the API from completing the request. For example, this error occurs for any business validation errors, including errors that are not usually of the 400 type.
429 Unprocessable Entity RATE_LIMIT_REACHED. Too many requests. Blocked due to rate limiting. The rate limit for the user, application, or token exceeds a predefined value. See RFC 6585.
500 Internal Server Error INTERNAL_SERVER_ERROR. An internal server error has occurred. A system or application error occurred. Although the client appears to provide a correct request, something unexpected occurred on the server.
503 Service Unavailable SERVICE_UNAVAILABLE. Service Unavailable. The server cannot handle the request for a service due to temporary maintenance.

Validation errors

For validation errors, Reloadly returns the HTTP 400 Bad Request status code.

To prevent validation errors, ensure that parameters are of the right type and conform to these constraints:


request parameters

Parameter type Description
Character Names, addresses, phone numbers, and so on have maximum character limits.
Numeric Amounts, ids, and so on must use non-negative numeric values and have required formats. For example, a CVV must be three or four numbers while a credit card number must contain only numbers.
Required Must be included in the request. For example, when you provide credit card information, you must include a postal code for most countries.
Monetary Must use the right currency.

Authentication errors

For authentication errors, Reloadly returns the HTTP 401 Unauthorized status code. See authentication and authorization.

Access token-related issues often cause authentication errors.

Ensure that the access token is valid and present and not expired.

Hypermedia as the Engine of Application State (HATEOAS) is a constraint of the REST application architecture that distinguishes it from other network application architectures.

This excerpt from a sample response shows an array of HATEOAS links


HATEOAS Links Sample

  "links": [{
    "href": "",
    "rel": "self",
    "method": "GET"
  }, {
    "href": "",
    "rel": "refund",
    "method": "POST"

You can use the links in this example, as follow : * Use the self link to get more information about the request. Combine the method and the target URL to make the call : GET *Use the refund link to request a refund : POST

The elements in the link object are :


request parameters

Element Required Description
href Required The target URL.
rel Required The link relationship type.
method Optional The HTTP method. Default is GET.

The href element

The href element contains the complete target URL, or link, to use in combination with the HTTP method to make the related call. href is the key HATEOAS component that links a completed call with a subsequent call.

The rel element

The rel element contains the link relationship type, or how the href link relates to the previous call.

For a complete list of the link relationship types, see Link Relationship Types.

The method element

Optional. The method element contains an HTTP method. If present, use this method to make a request to the target URL. If absent, the default method is GET.

The HTTP methods are :


request parameters

Method Description
DELETE Deletes a resource.
GET Shows details for a resource or lists resources.
PATCH Partially updates a resource.
POST Creates or manages a resource.
PUT Updates a resource.

Error Codes

A Reloadly API operation may return multiple error and warning codes :


request parameters

Code Description
TOKEN_EXPIRED Access tokens have a finite lifetime. The expires_in field in the get access token response indicates the lifetime, in seconds, of the access token. For example, an expiry value of 3600 indicates that the access token expires in one hour from the time the response was generated.

To detect when an access token expires, write code to either :

  • Keep track of the expires_in value in the token response. The value is expressed in seconds.
  • Handle the HTTP 401 Unauthorized status code and the TOKEN_EXPIRED error code in the error response message. The API endpoint issues this status code when it detects an expired token.
INVALID_RECIPIENT_PHONE The specified recipientPhone in the request is not valid for the specified country (ISO-2 country code) country
INVALID_SENDER_PHONE The specified senderPhone in the request is not valid for the specified country (ISO-2 country code) country
INVALID_PHONE_NUMBER The specified phone number is not valid
PHONE_RECENTLY_RECHARGED After a given phone number has been topuped-up, a delay of 2 minutes has to take place before the same phone number can be topuped-up again.
COUNTRY_NOT_SUPPORTED The specified country in the request is currently disabled or not supported
OPERATOR_UNAVAILABLE_OR_CURRENTLY_INACTIVE The specified operator is currently disabled or inactive on the platform.
INACTIVE_ACCOUNT Reloadly reserves the right to de-activate a developer account for various reasons. The developer must contact support for more info.
INVALID_AMOUNT_FOR_OPERATOR The specified topup amounts is not valid for the given operator in the request.
TOPUP_TRANSACTION_FAILED Topup transactions may failed various reasons. Developer must contact support if they need more details.
COULD_NOT_AUTO_DETECT_OPERATOR Reloadly platform has the ability to auto-detect mobile carriers/operators for a given phone number, see Operator auto-detect →. In cases where that's not possible, this error code is returned.
ACCOUNT_NOT_FOUND User account not found or does not exist.
MAX_DAILY_TRANSACTION_COUNT_REACHED Some developer account may have a daily transaction count limit. This error code is returned when that occurs
MAX_DAILY_TRANSACTION_AMOUNT_REACHED Some developer account may have a daily total transaction amount limit. This error code is returned when that occurs
TRANSACTION_CANNOT_BE_PROCESSED_AT_THE_MOMENT Topup transactions may failed various reasons. Developer must contact support if they need more details.
INVALID_AMOUNT Reloadly expects amounts to be numerical.
INSUFFICIENT_BALANCE This error code is returned when a user attempts an API operation that requires adequate account balance to be available in order to be performed. This error code is returned when the user account lack enought balance.
OPERATOR_NOT_IN_SERVICE The specified operator in the request is currently disabled, inactive or not in service on the platform.

Make Your First Call

To make REST API calls, create a Reloadly developer account and get an access token :

  1. Create a developer account <= (click to go there). When you create a developer account, Reloadly generates a set of OAuth credentials.
  2. Get an access token. Pass the OAuth credentials in a get access token call.In response, the Reloadly authorization server issues an access token.
  3. Make REST API calls. Use the access token for authentication when you make REST API calls.

Get an access token

URLs: ``

To get an access token, you pass your OAuth credentials in a get access token call. To make this call, you can use either cURL on the command line or the Postman app. For complete details on this endpoint Check Endpoint Doc →

In response, the Reloadly authorization server issues an access token.

Re-use the access token until it expires. See our rate limiting guidelines. When it expires, you can get a new token.

cURL example

  • If you use Windows, use a Bash shell to make cURL calls.
  • If you use a command-line tool other than cURL, set content-type to application/json.
  1. Download cURL for your environment.
  2. From the command line, run this command :

curl -d '{
}' \
-H "Content-Type: application/json" \

Where :


request parameters

The get access token endpoint.
client_id Your client ID.
client_secret Your client secret.
audience The API you're requesting the access token for.
Live :
Sandbox :
grant_type The grant type. Set to client_credentials.
  1. View the sample response.

Postman example

  1. Download the latest version of Postman for your environment, and open Postman.
  2. Select the POST method.
  3. Enter the request URL.
  4. On the Header tab, enter Content-Type under key and application/json as value :

request parameters

key Content-Type
value application/json
  1. On the Body tab, select raw and enter this information :

   "client_id": "YOUR_CLIENT_ID",

   "client_secret": "YOUR_CLIENT_SECRET",

   "grant_type": "client_credentials",

   "audience": ""
  1. Click Send
  2. View the sample response :
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSU",

  "scope": "send-topups read-topups-history read-operators read-promotions",

  "expires_in": 86400,

  "token_type": "Bearer"

Where :


request parameters

access_token Your access token.
expires_in The number of seconds after which the token expires. Request another token when the current one expires.

Make REST API Calls

With a valid access token, you can make REST API calls.

This sample call sends a airtime (topup) transaction and uses only the required input parameters. The access token in the call is an OAuth bearer token.

Note: Topups API calls are always made by an actor. The actor specifies a bearer token in the Authorization: Bearer request header. A bearer token is an access token that is issued to the actor by an authorization server with the approval of the resource owner. In this case, the actor uses the bearer token to make a topup request.

curl -d '{
          "recipientPhone": {
            "countryCode": "HT",
            "number": "50936377111" //(Note the "+509" country dialing code for Haiti)
          "senderPhone": {
            "countryCode": "US",
            "number": "13059547862" //(Note the "+1" country dialing code for USA)
          "operatorId": 173,
          "amount": 15,
          "customIdentifier": "transaction by"
        }' \
    -H "Accept: application/com.reloadly.topups-v1+json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSU" \
    -X POST

Note: Phone numbers (recipientPhone, senderPhone) can be in 2 formats. In the example above, the "+" sign is not present in front of the country dialing codes (see countries dialing codes). Our API also accept phone number prefixed with "+". The following is equivalent to the example above :

Tutorial Series

API Reference

Airtime API

The Reloadly Topups API is RESTful and uses a JSON data format. The API grants users in more than 100 countries access to its feature set. The API enables users to conduct topup (airtime) transactions, retrieve account data, view international rates, see history and much more.

Account Balance

Use the /accounts/balance resource to list account available balance. You will need an active access token to make a successful call to this endpoint. You can read on how to get the access token for you account Here. Once the access token is available all we need to do is make a GET request to the account balance endpoint. Complete details of the endpoint with all parameters it take and the complete structure of the response can be found here Endpoint Details →

Commissions & Discounts

Commissions or Discounts are a way for you to check what percentage discount rate will you get for each operator when you do a successful top-up. This can be used to make automated calculation on your side for calculating of the profits. We provide easy way to retrieve commissions for all operators. All Commissions are paid instantly when a top-up is processed. When you make a GET request to the /operators/commissions Endpoint, You will be returned will all commission details of all operators. You can further filter the commissions for a specific operator by using the /operators/{operatorId}/commissions endpoint. Simply append the operator Id in the endpoint path and you are good to go.

One thing to note on the response is that All Operators provide two types of discounts, One is the international discount and the other is the local discount. These are returned in the internationalPercentage and localPercentage variables in the response. Based on what you're account country is and which country you are sending the topup to you are eligible for either one of these discounts. For example if you're sending from the US to Canada you will be eligible for the international discount for the canadian operator. While sending within the same country you will be eligible for the local discount of the operator.

You can check the complete detail of the response and parameters on the Endpoint Documentation →


In order for you to calculate the right amount to send and to estimate what amount will be received on the reciever end, We provide an easy to use endpoint for this purpose. You can get the active rate for any currency by simply making a POST request to /operators/fx-rate Endpoint. We need to send the operator's Id and the amount that we want the rate to be calculated for. The base currency is always your account's currency.

So as an example, If you account is in US Dollar and you are trying to send to a nigerian Operator you can quickly make a Post call to the endpoint and send the operator's Id with the Amount in Canadian Dollar to calculate what amount you will receive in Nigerian Naira. Here is the Endpoint Documentation → for fx-rate.


Reloadly supports 140+ Countries around the globe. You can get a list of all supported countries by makind a GET request to /countries Endpoint. The response will give you a list with complete details, iso, flag as well as calling codes for each country. You can also further filter the countries by getting details for a specific country by its ISO using the /countries/{countryIsoCode} Endpoint. Simply replace the iso code in the path and you're good to go.

Complete Response details and structure can be found in the Endpoint Documentation →.


Apart from supporting Over 140 Countries, Reloadly also supports 600+ Operators. In order to retrieve a complete list of all operators you simply need to make a GET request to the /operators Endpoint. The endpoint provide a complete list of operators that are paginated. You can set the number of operators to retrieve in each page by simply tweaking the size parameter. Reloadly returns complete detail of each operator so you don't need to make multiple calls, Including what type of operator this is, what topup types it support and even details on the commissions for the operator.

Within the reloadly platform, There exist two types of Operators. One that support Range values (Anything between the minnimun and maximum range). While the other that support Fixed values (Only a cetain values are supported). Reloadly will return you the type of the operator within the response in denominationType variable. If this is set to RANGE you will receive the minimum and maximum values in the minAmount and maxAmount variables for that operator. However if the denomination type is FIXED you will not get these values but rather get an array of all values supported in the fixedAmounts variable. Now a point to remember here is that these values are already converted into your account's currency.

Auto-Detect Operators

Reloadly also provide a simple way for its API's users to automatically detect the operator for any given number. This can be done by making a simple GET request to the /operators/auto-detect/phone/{phone}/countries/{iso} Endpoint. We will need to append the phone number with or without the country code and the Country's ISO in the path and the Reloadly platform will automatically find the operator for this number and send you complete details of that operator. Read the Operator's Endpoint Documentation for more details on this.

Local Amount support for Operators

If you wish to send topup in the local amount that is the amount of the operator's currency (or receiver's currency), Reloadly also support this for limited operators. We are on our way to support local transfer for all operators but currently we only support some of the operators. This can be easily determined by the supportsLocalAmounts flag that is returned in the response. If the flag is true it means the operator in question supports local transfer. Meaning you can send the amount in local currency (the receiver's currency) and the operator will send that exact amount. We will automatically apply the fx-rate of the transaction time to your account. To get exact values/ranges Reloadly provide various attributes in the response for the operator besides supportsLocalAmounts. If the Operator is Range and supports local then you will get the localMinAmount and localMaxAmount alongside the minAmount and MaxAmount. Given that as the name states the local ones are already converted into the local currency. Similarly for Fixed type operators relodaly will return localFixedAmounts.

When sending topup we will also have the ability to specify if we are sending amount in local currency or not. To read more on topups check the Topups Section.

PIN support for Operators

Apart from all this there are also some operators that support PIN transactions. This can be easily checked by the pin flag. If this is true then you can easily get PIN based topups for this operator via Reloadly platform. For PIN topups the platform will provide you with complete details with a PIN number (card number) that you can use to topup locally on the sim card. These topups are not relevant to the numbers and can be used for any number of the same operator.

To read more on the internals of what parameters are supported and what are returned by the operators endpoint and how you can filter for either the Id of the operator or country's ISO read more on the Endpoint Documentation →.


Reloady is also supported for enabling operator's promotions. These are provided by the Operators and can be activated by sending a specific topup amount as per the details of the promotion. Reloadly provide neat ways to get all details on the promotion and to showcase these to your customers.

To get a complete list of promotions simply make a GET request to the /promotions Endpoint. Promotions are already paginated can you can simply append the page number in your request to proceed to the next page. Reloadly will also return the start and end date of the promotion so that you can keep your system in sync on when to add/remove promotions from it. This endpoint also support's filter and you can filter the promotions by either Id of the promotion, Id of the operator or even get all promotions within the country by filtering via country's ISO.

Complete list of supported sub endpoints and parameters for promotions alons with the structure of response can be found in the Endpoint Documentation → Section.


In order to send a successful topup. There are a few prerequisites to the system. We need to know the phone number to send the topup, the operator of the phone number, the country of the operator and the amount for the topup.

There are multiple ways of handling this and getting this information from the user. You can create a simple form and showcase all the countries that are supported in a simple selection by using the Countries Endpoint.

Once you can the user select a country, To get the operator we can go with it in two different ways. A) we can have reloadly auto-detect the operator Or B) We can simple filter the operators by country using the /operators/countries/{countryIsoCode} endpoint and show a selection for those.
It is recommended to do both on your side to provide the best experience to the users. So basically get the country and then get the number from the user and make a call to the reloadly platform to detect the operator for that number. Once that is received confirm the operator with the user and provide ability to change operator.

Once we have all this information we will need to also send the amount for the topup. Remember based on the type of the operator (Range or Fixed) Not all values will be supported. Read the Operators Documentation to see what is supported and what not.

Top-up in Local Amounts

Reloadly also provides the ability to top up local values. By default, the values will be available in your account’s currency, but you can maintain one wallet and top up in different local values from many countries. If you want to send exact amounts in Local/Operator's/Receiver's currency, then simply send in the useLocalAmount flag and set that to true. This will tell the platform that you are sending the amount in local currency and not in your dashboard's currency or international pipe. Not all operator's support a local amount yet so make sure to check the operator's details to know if it supports local or not. You can read more on local operators Here

Complete details on the POST call for the Topup api can be found in the Endpoint Documentation → Section. Be sure to check that as well.

Nauta Cuba Top-up

Reloadly also supports Nauta Cuba for top-ups. However the process is a bit different from sending normal topups. Instead of sending recipientPhone we send recipientEmail and that's just about it. The rest of the process is exactly the same as sending any other topup.

Note : There are two types of email domains that are allowed for Nauta Cuba Top-up.


You can find example codes for making successful request for nauta cuba Here →


Just like all systems, We also keep a record of all transactions so that our users can track their activity in their respective dashboards. Apart from doing just that we also provide a neat way to integrate transactions into your own systems. You can get a complete list of your past top-up transactions by simply doing the GET request to /topups/reports/transactions Endpoint.

This will provide you with a paginated result with all your recent transactions and the ability to paginate to further previous transactions.

All on Transactions can be found in the Endpoint Documentation → Section.

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.