API reference

Payments

Paystack-backed collections, verification and receipts.

Overview

Collections run on Paystack. A payment starts as a top-up intent with a Century reference, is completed either on a Paystack checkout page or by transfer into the user's dedicated virtual account, and is settled by the signed Paystack webhook. Verification is also available on demand so a client can confirm a reference without waiting for the webhook.

Amounts are submitted in naira; Century converts to kobo before calling Paystack.
Dedicated virtual accounts require an approved Tier 2 (NIN) record whose name matches the profile.
Refunds are not exposed through the API — they are handled operationally by the Century team.

Idempotency

Settlement is keyed on the payment reference. A duplicate charge.success for a reference already marked credited is acknowledged with 200 and ignored.

Related webhook events

charge.success

Not implemented

Do not build against these

Partial or API-initiated refunds
Card tokenisation / recurring charges

Endpoints

4 operations available to your account.

startPaystackTopup

Bearer token required

Initialize a Paystack transaction and return an authorization URL.

Endpoint

POST/_serverFn/startPaystackTopup

Request body

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

Example response

{ ok: true }

verifyPaystackTopup

Bearer token required

Verify a Paystack reference and credit the wallet if unsettled.

Endpoint

POST/_serverFn/verifyPaystackTopup

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 POST https://centuryvtu.com/_serverFn/verifyPaystackTopup \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"data":{"reference":"string"}}'

Example response

{ ok: true }

getTopupReceipt

Bearer token required

Fetch a shareable top-up receipt.

Endpoint

GET/_serverFn/getTopupReceipt

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

Example response

{ ok: true }

listPaymentHistory

Bearer token required

List the caller's payment intents/settlements.

Endpoint

GET/_serverFn/listPaymentHistory

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/listPaymentHistory \
  -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.