API reference

Wallet

Balances, ledger, transfers and debits.

Overview

Every Century account owns exactly one NGN wallet. Balances are derived from an append-only ledger, so a wallet read always reflects the sum of settled ledger rows. Money-moving calls require the caller's 4-digit transaction PIN and are rejected when the wallet cannot cover the amount.

Balances are returned in naira (₦), not kobo.
Referral and bonus credits are returned separately as lockedBonus / referralLockedBonus and are not spendable.
Wallet-to-wallet transfers require KYC Tier 2 (NIN) on the sender.

Idempotency

Top-up intents are idempotent by reference: createTopupIntent returns an immutable reference, and replaying a settlement for the same reference credits the wallet at most once.

Related webhook events

charge.success transfer.success transfer.failed transfer.reversed

Endpoints

6 operations available to your account.

getWalletState

Bearer token required

Balance, locked bonuses, recent ledger.

Endpoint

GET/_serverFn/getWalletState

Response codes

401	Unauthorized – missing or invalid bearer token.
400	Validation failed – input did not match the schema.
429	Rate limited – slow down and retry.
500	Server error – reported and logged with an error ID.

curl -X GET https://centuryvtu.com/_serverFn/getWalletState \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -G

Example response

{ balance, lockedBonus, referralLockedBonus, log: WalletLedgerRow[] }

Runs against Production using your own signed-in session. No shared or secret credential is used.

createTopupIntent

Bearer token required

Create a server-side top-up intent with an immutable reference.

Endpoint

POST/_serverFn/createTopupIntent

Request body

Field	Type	Required
amount	number (₦100–₦1,000,000)	Yes
processor	string	Yes

Response codes

401	Unauthorized – missing or invalid bearer token.
400	Validation failed – input did not match the schema.
429	Rate limited – slow down and retry.
500	Server error – reported and logged with an error ID.

curl -X POST https://centuryvtu.com/_serverFn/createTopupIntent \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"data":{"amount":500,"processor":"string"}}'

Example response

{ id, reference, amount }

getTopupIntent

Bearer token required

Poll the status of your top-up intent.

Endpoint

GET/_serverFn/getTopupIntent

Request body

Field	Type	Required
reference	string	Yes

Response codes

401	Unauthorized – missing or invalid bearer token.
400	Validation failed – input did not match the schema.
429	Rate limited – slow down and retry.
500	Server error – reported and logged with an error ID.

curl -X GET https://centuryvtu.com/_serverFn/getTopupIntent \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -G

Example response

{ ok: true }

debitWalletFn

Bearer token required

Debit the caller's wallet (requires transaction PIN).

Endpoint

POST/_serverFn/debitWalletFn

Request body

Field	Type	Required
amount	number (min ₦50)	Yes
note	string	Yes
pin	string (4 digits)	Yes

Response codes

401	Unauthorized – missing or invalid bearer token.
400	Validation failed – input did not match the schema.
429	Rate limited – slow down and retry.
500	Server error – reported and logged with an error ID.

curl -X POST https://centuryvtu.com/_serverFn/debitWalletFn \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"data":{"amount":500,"note":"string","pin":"1234"}}'

Example response

{ ok: true }

transferWalletFn

Bearer token required

Send funds to another Century user (KYC Tier 2 required).

Endpoint

POST/_serverFn/transferWalletFn

Request body

Field	Type	Required
username	string	Yes
amount	number	Yes
note	string	No
pin	string	Yes

Response codes

401	Unauthorized – missing or invalid bearer token.
400	Validation failed – input did not match the schema.
429	Rate limited – slow down and retry.
500	Server error – reported and logged with an error ID.

curl -X POST https://centuryvtu.com/_serverFn/transferWalletFn \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"data":{"username":"string","amount":500,"note":"string","pin":"string"}}'

Example response

{ ok: true }

lookupProfileByUsername

Bearer token required

Resolve a @username to a recipient profile.

Endpoint

POST/_serverFn/lookupProfileByUsername

Request body

Field	Type	Required
username	string	Yes

Response codes

401	Unauthorized – missing or invalid bearer token.
400	Validation failed – input did not match the schema.
429	Rate limited – slow down and retry.
500	Server error – reported and logged with an error ID.

curl -X POST https://centuryvtu.com/_serverFn/lookupProfileByUsername \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"data":{"username":"string"}}'

Example response

{ ok: true }