Integration guides

• Create a top-up intent with the amount in naira. Century returns an immutable reference and a checkout URL.
• Send the user to checkout, or let them transfer into their dedicated virtual account (requires approved Tier 2 NIN).
• Wait for the signed charge.success webhook — that is the moment the wallet is credited.
• If the user returns before the webhook lands, call verification with the reference to settle immediately.

curl -X POST https://centuryvtu.com/_serverFn/createTopupIntent \
  -H "Authorization: Bearer $CENTURY_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"data":{"amount":5000}}'

• Confirm the user holds an approved Tier 2 (NIN) record whose name matches their profile.
• Request the dedicated account — Century creates the customer with the verified identity and returns bank, account number and account name.
• Any transfer into that account settles as charge.success and credits the wallet automatically.
• The account is permanent and reusable; do not regenerate it per payment.

• Load the plan catalog and cache it — it refreshes at most every 30 minutes.
• Validate the recipient number against the network before charging; Century rejects mismatches with NETWORK_MISMATCH.
• Quote the retail price, collect the transaction PIN, then purchase.
• Poll the transaction until it leaves processing. Failures refund the wallet automatically.

const quote = await quotePrice({ service: "data", planId });
const tx = await buyData({ network, phone, planId, pin });

let status = tx.status;
while (status === "processing") {
  await new Promise((r) => setTimeout(r, 3000));
  status = (await getTransaction({ id: tx.id })).status;
}

• Tier 1 — face liveness in the browser. Unlocks transacting.
• Tier 2 — NIN with a phone number. Unlocks wallet transfers and dedicated virtual accounts.
• Tier 3 — bank account plus an ID document.
• Tiers are strictly sequential: a tier cannot be submitted until the previous one is approved.

• Verify the HMAC signature over the raw body before parsing.
• Respond 200 quickly, then process asynchronously — slow handlers cause retries.
• De-duplicate on the reference; the same event can arrive several times.
• Reconcile daily against the provider so a permanently lost webhook still settles.

Full payloads and verification code live in the webhooks reference.