Quickstart

Authorization

The fastest way to get started with the Airtime product is to make a top-up. This section covers how to get started with the Airtime API product. To make a top-up, you will need client credentials which you can get from signing up in the dashboard

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

Choose your environment

Asides from the live environment, Reloadly provides a sandbox (also called test environment) where you can simulate real-life scenarios and use cases for each API endpoint. If you would like to first work with the test environment, you can check out the virtual sandbox in the DevTools section.

Client Credentials

Parameter	Description
client_id	This is a private identifier for your account
client_secret	This is a private key that should not be shared

Environments

Parameter	Description
Sandbox	Use endpoints in test mode and simulate real-like responses
Live	Work with live credentials to build applications

Get your access token

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

cURL

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

HTTPie

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

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

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

JSON

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

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

Make your first top-up

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

cURL

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

HTTPie

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

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

JSON

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

You can test these steps out directly on our Postman collection.

Next steps

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