Reference
Glossary
Every term used anywhere in these docs, explained in plain English, no prior API experience assumed.
- API
- Short for Application Programming Interface. A way for two computer programs to talk to each other over the internet, the same way a website talks to your browser, except the response is data (usually JSON) instead of a page you look at.
- Endpoint
- One specific address an API responds to, e.g. /wallet or /vtu/airtime. Each endpoint does one job.
- HTTP method
- The kind of action a request is: GET reads something without changing it, POST creates or does something (like a purchase), PUT replaces a setting, DELETE removes something.
- Base URL
- The common starting address every endpoint is added onto, e.g. https://api.topuprelay.com/api/v1. An endpoint like /wallet becomes https://api.topuprelay.com/api/v1/wallet.
- Header
- A small piece of information sent alongside a request, separate from the main content, used for things like proving who you are or saying what format the data is in. Postman and code libraries handle these for you.
- Request body
- The actual content of a request, e.g. the phone number and amount you're sending for a purchase. Usually written as JSON, a simple text format using { } and " " to describe data.
- JSON
- Short for JavaScript Object Notation. A plain-text way to describe data that both humans and computers can read, e.g. {"amount": "200.00"}. Every request and response in this API is JSON.
- Status code
- A 3-digit number every response includes saying what happened: 200/201 means success, 4xx means something about your request was wrong (bad data, wrong key, not enough balance), 5xx means something went wrong on TopupRelay's side.
- client_key / api_secret
- Your two-part partner identity. client_key is not sensitive, it's fine to appear in logs or URLs. api_secret is like a password, never shown in your code, never committed to a public repository, never shared.
- HMAC signature
- A short code computed from your request and your api_secret, proving the request really came from you and wasn't changed on the way. You never type it by hand, a script or library computes it. See Authentication.
- Bearer token / access token
- A temporary pass you get back after proving your identity once (see Authentication), then attach to every other request for about an hour before it expires and you get a new one.
- Sandbox / test mode
- A safe practice environment using a test key pair (ck_test_.../cs_test_...) where purchases are simulated, no real airtime moves and no real money is spent. Switch to a live key pair only once your integration works correctly in test mode.
- Wallet
- A running balance you fund in advance, then spend from. Every TopupRelay purchase debits a wallet rather than charging a card each time.
- Ledger
- The full history of every change to a wallet, credits and debits. A wallet's balance is always just the sum of its ledger, never a number edited directly.
- Webhook
- A notification TopupRelay (or a payment gateway) sends to a URL automatically when something finishes, instead of you having to repeatedly ask “is it done yet?”.
- Idempotent
- Safe to repeat. An idempotent request does the same thing whether you send it once or five times by accident, it never double-charges or double-delivers.
- Rate limit
- A cap on how many requests you can send in a short window, to keep the service fast and fair for everyone. See Rate limits.
- Query parameter
- Extra options added to the end of a URL after a ?, e.g. ?limit=10. Used for things like how many results to return.
- Partner account
- Your business's record with TopupRelay. One partner account can hold both a test key pair and a live key pair, each with its own separate wallet.