No-code setup, using Postman
You don't have to write a single line of code to try the TopupRelay partner API. Postman is a free desktop app that sends API requests for you, point and click. This page walks through every step, assuming you've never used Postman before.
Step 1. Install Postman
If you don't already have it, download the free desktop app from postman.com/downloads and install it like any other app. Open it, and skip or create an account when it asks, either is fine.
Step 2. Download two files
These two files are everything the request-sending setup needs. Save them anywhere you'll remember, your Desktop or Downloads folder is fine.
Step 3. Import them into Postman
- 1. In Postman, click Import (top left corner).
- 2. Drag both downloaded files into the window that opens, or click to browse and select them.
- 3. Click Import again to confirm. You'll now see TopupRelay Partner API in the Collections list on the left.
Step 4. Switch to the TopupRelay environment
In the top-right corner of the Postman window, there's a dropdown that probably says No Environment. Click it and choose TopupRelay Sandbox. This is where your keys live, separate from the requests themselves.
Step 5. Fill in your keys
Click the eye icon next to the environment dropdown, then Edit. You'll see a small table. TopupRelay will have given you a client_key (starts with ck_test_) and an api_secret (starts with cs_), shown once when your account was set up.
| Row | What to put there |
|---|---|
| client_key | Paste the key starting with ck_test_ |
| api_secret | Paste the secret starting with cs_ |
| base_url | Leave as-is for testing against your own local setup, or change it to https://api.topuprelay.com once TopupRelay is deployed |
Leave access_token and refresh_token blank, Postman fills those in for you in Step 6. Click Save.
Step 6. Run the requests, in order
Click on TopupRelay Partner API in the left sidebar to open the collection. You'll see four requests, numbered. Click into each one and press the blue Send button, in this order:
- 1
Get an access token
Proves who you are using your key and secret, and gets back a temporary pass that the other requests use. You should see 200 OK at the top of the response.
- 2
Check wallet balance
Shows how much money is in your partner wallet right now. A brand-new account shows 0, that's expected.
- 3
Buy airtime
Sends a real purchase request. Open the Body tab on this request to change the network, phone number, or amount before sending. In test mode nothing real is spent.
- 4
List recent purchases
Confirms request 3 actually went through, and shows whether it succeeded.
If something says 401 or 402
Every request in this collection prints a plain-English note in Postman's Console (View → Show Postman Console) explaining the most likely reason. The two you'll actually hit:
401 on request 1 → client_key or api_secret in the environment is wrong, or your
computer's clock is more than 5 minutes off from the real time.
402 on request 3 → your wallet has no balance yet. Fund it from the TopupRelay
dashboard first, nothing was charged.For every other error code, see Error codes.
Ready to write real code?
Everything these four requests do is also covered, with copy-paste code instead of clicking, on the Quickstart page.