You're offline — reconnect to continue buying or checking your wallet.
Get started

Quickstart

TopupRelay has two entry points onto the same wallet and ledger engine: a session-based API for your own end users, and a signed partner API for a business integrating on behalf of its own customers. This section covers the partner API, if you're just using the TopupRelay web app yourself, there's nothing to integrate.

New to APIs entirely? Every technical term used anywhere in these docs, API, endpoint, HMAC, webhook, and so on, is explained in plain English in the Glossary. There's no shame in checking it, these words aren't obvious if you haven't used an API before.

Pick a starting point

Base URL

https://api.topuprelay.com

Every endpoint in these docs is written as a path like /api/v1/partner/wallet, add it onto this base URL to get the full address. Locally, the base URL is http://localhost:8000 instead.

Get a partner key pair

Partner accounts are provisioned by TopupRelay directly rather than through self-serve signup today. You'll be handed a client_key (starts with ck_test_) and an api_secret (starts with cs_) for a test environment. The secret is shown once, when your account is created, and can't be recovered afterward, so store it somewhere safe (a password manager, not a chat message to yourself) the moment you get it.

A complete, working example

This isn't a snippet to adapt, it's a full program. Fill in CLIENT_KEY and API_SECRET near the top, run it, and it gets a token, checks your wallet balance, and buys ₦200 of MTN airtime, printing each result as it goes. Nothing else needs installing, both versions below use only what already ships with the language.

// Save as quickstart.mjs, then run: node quickstart.mjs
// Needs Node.js 18 or newer (for the built-in fetch). No npm install required.
import crypto from "node:crypto";

// 1. Fill these in with the values you were given.
const BASE_URL = "https://api.topuprelay.com"; // use http://localhost:8000 for local testing
const CLIENT_KEY = "ck_test_...";
const API_SECRET = "cs_...";

function signRequest(method, path, bodyString) {
  const timestamp = Math.floor(Date.now() / 1000).toString();
  const bodyHash = crypto.createHash("sha256").update(bodyString).digest("hex");
  const signingString = [CLIENT_KEY, timestamp, method.toUpperCase(), path, bodyHash].join("|");
  const signature = crypto.createHmac("sha256", API_SECRET).update(signingString).digest("hex");
  return { "X-Client-Key": CLIENT_KEY, "X-Timestamp": timestamp, "X-Signature": signature };
}

async function main() {
  // Step 1: get an access token.
  const tokenPath = "/api/v1/partner/auth/token";
  const tokenRes = await fetch(BASE_URL + tokenPath, { method: "POST", headers: signRequest("POST", tokenPath, "") });
  const tokenBody = await tokenRes.json();
  if (!tokenBody.success) {
    console.error("Could not get a token:", tokenBody.error);
    return;
  }
  const accessToken = tokenBody.data.tokens.access_token;
  console.log("Got a token.");

  // Step 2: check wallet balance.
  const walletPath = "/api/v1/partner/wallet";
  const walletHeaders = { ...signRequest("GET", walletPath, ""), Authorization: `Bearer ${accessToken}` };
  const walletRes = await fetch(BASE_URL + walletPath, { headers: walletHeaders });
  const walletBody = await walletRes.json();
  console.log("Wallet balance:", walletBody.data.wallet.balance);

  // Step 3: buy airtime.
  const purchasePath = "/api/v1/partner/vtu/airtime";
  const purchaseBody = JSON.stringify({ network: "mtn", phone: "08011112222", amount: "200.00" });
  const purchaseHeaders = {
    ...signRequest("POST", purchasePath, purchaseBody),
    Authorization: `Bearer ${accessToken}`,
    "Content-Type": "application/json",
  };
  const purchaseRes = await fetch(BASE_URL + purchasePath, { method: "POST", headers: purchaseHeaders, body: purchaseBody });
  const purchaseResult = await purchaseRes.json();
  console.log("Purchase result:", purchaseResult.data ?? purchaseResult.error);
}

main();

If this prints a purchase result with a status field, every piece worked, the signature, the token exchange, and a real (test-mode) purchase. See Error codes if anything printed an error instead.

Sandbox vs live

Every partner account can hold a test key pair and a live key pair, each with its own wallet, funding or spending on one never touches the other. Test-mode VTU purchases are served by a mock provider so you can build and demo your integration without moving real airtime. Switch to your live key pair only once the script or integration above runs cleanly against test.