You're offline — reconnect to continue buying or checking your wallet.
Core concepts

Authentication

Every partner request is authenticated twice, deliberately: an HMAC signature proves the request came from someone holding your secret and wasn't altered in transit, and a bearer token proves an active, scoped session. The two are checked together, a valid signature from client A paired with a token belonging to client B is rejected, not quietly accepted.

1. Sign the request

Three headers carry the signature:

HeaderValue
X-Client-KeyYour public client key (e.g. ck_test_...)
X-TimestampCurrent Unix time in seconds
X-SignatureHex HMAC-SHA256, computed as described below

The string to sign is five fields joined with |:

{client_key}|{timestamp}|{METHOD}|{path}|{sha256_hex(raw_request_body)}

Example, for POST /api/v1/partner/vtu/airtime with body {"network":"mtn","phone":"08011112222","amount":"200.00"}:

ck_test_abc123|1732000000|POST|/api/v1/partner/vtu/airtime|9f1c2...  (sha256 of the exact JSON bytes sent)
  • • Method is upper-case (GET, POST, …).
  • • Path is the request path only, no query string, leading slash included.
  • • Body hash is a plain SHA-256 of the exact bytes you send, for a GET request with no body, this is the hash of an empty string.
  • • The final signature is HMAC-SHA256(signing_string, api_secret), hex-encoded.
import crypto from "node:crypto";

function signRequest(clientKey, apiSecret, method, path, bodyString) {
  const timestamp = Math.floor(Date.now() / 1000).toString();
  const bodyHash = crypto.createHash("sha256").update(bodyString).digest("hex");
  const signingString = [clientKey, timestamp, method.toUpperCase(), path, bodyHash].join("|");
  const signature = crypto.createHmac("sha256", apiSecret).update(signingString).digest("hex");

  return {
    "X-Client-Key": clientKey,
    "X-Timestamp": timestamp,
    "X-Signature": signature,
  };
}

2. Exchange it for a token

POST /partner/auth/token and POST /partner/auth/token/refresh are the only two endpoints that accept a signature alone, every other endpoint also requires the bearer token this returns. That's deliberate: gating refresh behind a token would make an already-expired token impossible to refresh.

200 response
{
  "success": true,
  "data": {
    "tokens": {
      "access_token": "eyJhbGciOiJIUzI1NiIs...",
      "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
      "token_type": "bearer",
      "expires_in": 3599
    }
  }
}
  • • Access tokens last 60 minutes.
  • • Refresh tokens last 14 days from original issuance, refreshing extends the access token, not the 14-day window itself.
  • • Send the access token as Authorization: Bearer <token> on every other request, alongside the same three signature headers.

3. Replay protection

A timestamp more than 5 minutes old or in the future is rejected outright. Within that window, the exact same signed request, same client, timestamp, method, URL, and body, can only be processed once; a repeat is rejected with REPLAY_DETECTED. Generate a fresh timestamp (and therefore a fresh signature) for every request, don't cache and reuse one.