Skip to content
English
Customer portal
Go to reloadly.com
  • There are no suggestions because the search field is empty.

Getting started! Send your first API Request

Getting Started · API

Send your first API request, in Test and Live

A hands-on walkthrough of Reloadly's OAuth 2.0 authentication — get a token, call the sandbox, then repeat it for production.

Setup time

~10 minutes

Level

Technical

You'll need

Postman (or similar)

Reloadly uses the OAuth 2.0 authorization framework, so before you can call any endpoint you need to exchange your credentials for an access token. This guide walks through getting that token and making your first request — first against the Test (Sandbox) environment, then against Live (Production).

1

How Reloadly's authentication works

Every Reloadly product uses the client credentials grant type from OAuth 2.0. You exchange your client_id and client_secret for an access token, then pass that token as a Bearer token in the header of every subsequent API call.

🧪 Test environment

Uses your TEST client_id/secret. Endpoints live under -sandbox.reloadly.com domains, and nothing here touches real money or sends a real top-up.

🚀 Live environment

Uses your LIVE client_id/secret. Endpoints drop the "sandbox" prefix, and every request is real — it spends real wallet balance.

ℹ️ One important detail: access tokens are scoped per product. A token generated for the Airtime API only works on Airtime endpoints — it won't authenticate you on the Gift Cards or Utility Payments APIs. You request a separate token per product, using its own audience value.
2

Switch to Test Mode and grab your credentials

In your dashboard, turn on the Sandbox toggle in the top-right corner — this puts your whole Portal, including the Developers section, into test mode. Then go to Developers and copy your TEST client_id and client_secret.

💡 Tip: your TEST and LIVE credentials are completely different pairs. Mixing them up is the most common reason a request fails with an authentication error — always double check which mode you're copying credentials from.
3

Get your TEST access token

Using Postman or the HTTP client of your choice, send a POST request to the auth endpoint with your client credentials and the audience of the product you're working with — in this example, Airtime:

POST

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

Headers

Content-Type: application/json

Body (raw JSON)

{
  "client_id": "YOUR_TEST_CLIENT_ID",
  "client_secret": "YOUR_TEST_CLIENT_SECRET",
  "grant_type": "client_credentials",
  "audience": "https://topups-sandbox.reloadly.com"
}

A successful response returns your access token:

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 86400
}

Important: never expose your client_id, client_secret, or access token publicly — for example in client-side code, public repos, or shared screenshots. Treat them the same way you'd treat a password.

4

Call the sandbox: check your balance

With that token in hand, send your first real request — a GET call to check your account balance on the sandbox:

GET

https://topups-sandbox.reloadly.com/accounts/balance

Headers

Authorization: Bearer YOUR_TEST_ACCESS_TOKEN

A working response looks like this:

{
  "balance": 1000.00,
  "currencyCode": "USD",
  "currencyName": "US Dollar",
  "updatedAt": "2026-06-19 10:42:31"
}
ℹ️ That balance number isn't real money — sandbox accounts come preloaded with a test balance so you can simulate top-ups, gift card purchases, and other transactions without spending anything.

🚀 Switch to Live Mode and repeat

Once everything works as expected in sandbox, the move to production is the exact same flow with three changes:

  • Turn the Sandbox toggle off on your dashboard, and copy your LIVE client_id and client_secret from Developers instead.
  • Drop "sandbox" from the audience value in your token request — for Airtime, that becomes https://topups.reloadly.com.
  • Call the production balance endpoint, also without "sandbox": https://topups.reloadly.com/accounts/balance.

From this point on, every request you make in Live mode is real — it deducts from your actual wallet balance and reaches real recipients.

Important: LIVE credentials and LIVE endpoints process real transactions. Test any new integration thoroughly in Sandbox before pointing it at production.

📺 Prefer to watch it end to end?

This full video playlist covers the same steps in Postman, from your first sandbox request through to a live mobile top-up.

❓ Frequently asked questions

Can I reuse the same access token for every request?

Yes, until it expires (see the expires_in field in the token response, in seconds). Cache it and only request a new one once it expires or you get a 401 response — there's no need to fetch a fresh token on every call.

Why does my token work on one endpoint but not another?

Tokens are scoped to the audience you requested them for. A token issued for the Airtime API won't authenticate calls to the Gift Cards or Utility Payments APIs — you need a separate token per product.

I'm getting an unauthorized error — what's the most likely cause?

Almost always a mismatch: TEST credentials used against a LIVE endpoint (or vice versa), an expired token, or a typo in the client_id/client_secret. Double-check which mode you copied your credentials from.

Does the sandbox balance reset over time?

Sandbox is meant purely for testing integration logic, not for tracking real numbers — treat any balance you see there as illustrative rather than something to rely on long-term.

Stuck on your first request?

Our support team can help you debug the call.

Contact support →