Century Developers
Getting started

Quick start

Five minutes from a Century account to your first authenticated call. Everything below runs against production, so keep the amounts small.

1. Create an account

Sign up in the Century app and complete KYC Tier 1 (face liveness). Tier 1 is required before any transaction call will succeed. Tier 2 (NIN) unlocks wallet transfers and a dedicated funding account.

2. Get an access token

Century issues short-lived JWT access tokens through its auth service. In a browser session the token lives in the Supabase client; server-side you exchange credentials for one.

JavaScript
import { createClient } from "@supabase/supabase-js";

const supabase = createClient(CENTURY_URL, CENTURY_PUBLISHABLE_KEY);

const { data, error } = await supabase.auth.signInWithPassword({
  email: "you@example.com",
  password: process.env.CENTURY_PASSWORD,
});

const accessToken = data.session?.access_token;
Never ship credentials to the browser
The publishable key is safe in frontend code. Passwords, service keys and provider secrets are not — keep them in server environment variables only.

3. Read the wallet

cURL
curl -X GET https://centuryvtu.com/_serverFn/getWalletState \
  -H "Authorization: Bearer $CENTURY_ACCESS_TOKEN"
Response
{
  "balance": 2500,
  "lockedBonus": 0,
  "referralLockedBonus": 0,
  "currency": "NGN"
}

4. Quote and buy airtime

Always quote first — the retail price includes Century's markup.

cURL
# Quote
curl -X POST https://centuryvtu.com/_serverFn/quotePrice \
  -H "Authorization: Bearer $CENTURY_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"data":{"service":"airtime","amount":100}}'

# Purchase
curl -X POST https://centuryvtu.com/_serverFn/buyAirtime \
  -H "Authorization: Bearer $CENTURY_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"data":{"network":"mtn","phone":"08012345678","amount":100,"pin":"1234"}}'
  • The wallet is debited before the provider is called.
  • A provider rejection refunds the wallet automatically and returns PROVIDER_REJECTED.
  • A pending provider response keeps the transaction in processing — do not retry it, poll the transaction instead.

5. Handle the result

Poll getTransaction until the status leaves processing, then render a receipt. Read the error reference before writing retry logic.