API reference

VTU & Bills

Airtime, data, cable, electricity, betting and exam pins.

Overview

VTU purchases debit the wallet, call the routed upstream provider, and either complete, stay pending, or refund automatically. Century routes each service to the provider that fulfils it (data → RapidBills; airtime, electricity, cable, betting and airtime-to-cash → MySubWallet; social services → BigiSub) and tops that provider up just-in-time from the collections pool.

Every purchase requires the transaction PIN and KYC Tier 1.
Transaction states: processing → success | failed (refunded). A provider 'pending' response keeps the transaction in processing until reconciliation resolves it — no refund is issued while pending.
Recipient network is validated against the Nigerian prefix map before the wallet is debited, so mismatched numbers fail fast without a charge.
Retail price = wholesale price + configured markup. Use quotePrice to see the amount the user will be charged.

Endpoints

21 operations available to your account.

listAirtimeNetworks

Bearer token required

Available airtime networks.

Endpoint

GET/_serverFn/listAirtimeNetworks

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/listAirtimeNetworks \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -G

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

listDataNetworks

Bearer token required

Available data networks.

Endpoint

GET/_serverFn/listDataNetworks

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/listDataNetworks \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -G

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

listDataPlanTypes

Bearer token required

Plan categories (SME/CG/GIFTING…) for a network.

Endpoint

GET/_serverFn/listDataPlanTypes

Request body

Field	Type	Required
network	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/listDataPlanTypes \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -G

Example response

{ ok: true }

listDataPlans

Bearer token required

All data plans for a network.

Endpoint

GET/_serverFn/listDataPlans

Request body

Field	Type	Required
network	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/listDataPlans \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -G

Example response

{ ok: true }

listDataPlansForCategory

Bearer token required

Plans in one category.

Endpoint

GET/_serverFn/listDataPlansForCategory

Request body

Field	Type	Required
network	string	Yes
planType	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/listDataPlansForCategory \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -G

Example response

{ ok: true }

listCableProviders

Bearer token required

Cable TV providers.

Endpoint

GET/_serverFn/listCableProviders

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/listCableProviders \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -G

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

listCablePlans

Bearer token required

Cable plans for a provider.

Endpoint

GET/_serverFn/listCablePlans

Request body

Field	Type	Required
identifier	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/listCablePlans \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -G

Example response

{ ok: true }

listElectricityPlans

Bearer token required

Available discos.

Endpoint

GET/_serverFn/listElectricityPlans

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/listElectricityPlans \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -G

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

listBetCompanies

Bearer token required

Supported betting companies.

Endpoint

GET/_serverFn/listBetCompanies

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/listBetCompanies \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -G

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

quotePrice

Bearer token required

Return retail price after markup.

Endpoint

POST/_serverFn/quotePrice

Request body

Field	Type	Required
service	string	Yes
provider	string	No
wholesale	number	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/quotePrice \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"data":{"service":"string","provider":"string","wholesale":500}}'

Example response

{ ok: true }

verifyCableIUC

Bearer token required

Lookup cable subscriber name.

Endpoint

POST/_serverFn/verifyCableIUC

Request body

Field	Type	Required
iuc	string	Yes
identifier	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/verifyCableIUC \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"data":{"iuc":"string","identifier":"string"}}'

Example response

{ ok: true }

verifyMeter

Bearer token required

Lookup meter/customer name.

Endpoint

POST/_serverFn/verifyMeter

Request body

Field	Type	Required
meter	string	Yes
plan	string	Yes
type	'prepaid'\|'postpaid'	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/verifyMeter \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"data":{"meter":"string","plan":"string","type":"string"}}'

Example response

{ ok: true }

verifyBetAccount

Bearer token required

Lookup betting customer.

Endpoint

POST/_serverFn/verifyBetAccount

Request body

Field	Type	Required
betting_company	string	Yes
customer_id	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/verifyBetAccount \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"data":{"betting_company":"string","customer_id":"string"}}'

Example response

{ ok: true }

buyAirtime

Bearer token required

Purchase airtime (requires PIN).

Endpoint

POST/_serverFn/buyAirtime

Request body

Field	Type	Required
network	string	Yes
phone	string	Yes
amount	number	Yes
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/buyAirtime \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"data":{"network":"string","phone":"string","amount":500,"pin":"string"}}'

Example response

{ ok: true }

buyData

Bearer token required

Purchase a data bundle (requires PIN).

Endpoint

POST/_serverFn/buyData

Request body

Field	Type	Required
network	string	Yes
plan_id	string	Yes
phone	string	Yes
amount	number	Yes
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/buyData \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"data":{"network":"string","plan_id":"string","phone":"string","amount":500,"pin":"string"}}'

Example response

{ ok: true }

subscribeCable

Bearer token required

Pay a cable subscription (requires PIN).

Endpoint

POST/_serverFn/subscribeCable

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/subscribeCable \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{}'

buyElectricity

Bearer token required

Buy electricity token (requires PIN, min ₦1,000).

Endpoint

POST/_serverFn/buyElectricity

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/buyElectricity \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{}'

fundBet

Bearer token required

Fund a betting wallet (requires PIN).

Endpoint

POST/_serverFn/fundBet

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/fundBet \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{}'

buyEducationPin

Bearer token required

Buy an exam pin (requires PIN).

Endpoint

POST/_serverFn/buyEducationPin

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/buyEducationPin \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{}'

listMyVtuTransactions

Bearer token required

Recent VTU transactions.

Endpoint

GET/_serverFn/listMyVtuTransactions

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/listMyVtuTransactions \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -G

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

getMyVtuTransaction

Bearer token required

Fetch one VTU transaction by id.

Endpoint

POST/_serverFn/getMyVtuTransaction

Request body

Field	Type	Required
id	uuid	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/getMyVtuTransaction \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"data":{"id":"00000000-0000-0000-0000-000000000000"}}'

Example response

{ ok: true }