Welcome to the Docs

Reloadly provides infrastructure for your applications, websites or any other platform to send mobile top-ups to over 4.5 billion phones spanning 600+ mobile operators worldwide. In this section, you'll find guides, resources and references to build awesome stuff with Reloadly.


To get started with Reloadly, you'll need client credentials which you can get from signing up in the dashboard.

You'll have two different client credentials for two different environments - the sandbox and live environments.

View credentials in dashboard


client credentials

Parameter Description
client_id This is a private identifier for your account.
client_secret This is a private key that shouldn't be shared.


Parameter Description
Sandbox Use test credentials to create real-like scenarios.
Live Work with live credentials to build applications.


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 authorise API requests. Make a POST request to the https://auth.reloadly.com/oauth/token URL to obtain your access token.


Access Token Request

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

Access Token Response Data

        "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"

Make your first top-up

Now you've gotten your access token, the next step is to make a top-up on a mobile number. Reloadly spans across more than 600 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.


Mobile Top-up Request

    curl --include\
        --request POST\
        --header "Content-Type: application/json"\
          --header "Accept: application/com.reloadly.topups-v1+json"\
          --header "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6Ik0wWXpRa"\
          --data - binary "{\
        "recipientPhone\": {\
        "countryCode\": \"HT\",\
        "number\": \"+50936377111\"
        }, \"senderPhone\": {\
        "countryCode\": \"US\",\
        "number\": \"+13059547862\" 
        }, \"operatorId\": 174,\
        "amount\": 15,\
        "customIdentifier\": \"transaction by john@example.com\"
        " \

Mobile Top-up Response Data

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

Next steps

Great! You have gotten started with Reloadly in the fastest way possible. Feel free to modify the Quickstart code sample in order to get more practice with our API.

You can also check out the Airtime product and decide which of its features would be perfect for your use case.