Recurring Billing

Per-cycle billing schedules on a reusable account; deposits are attributed to periods and payers are reminded.

Bill a customer on a recurring cycle from a reusable virtual account. Each cycle Xental opens a period for the (variable) expected amount, attributes the customer's deposits to open periods oldest-first, reminds them when due/overdue, and emits billing.period.due/paid/overdue events. It never pulls funds — the customer pays into their account; Xental attributes and reminds.

Amounts are in kobo

amountKobo: 50000 is ₦500. The per-period expected amount is set at creation and can be changed per cycle via next-amount.

Overpayment carries forward

Paying more than a period's amount settles it and carries the surplus to the next period. To return a surplus instead, refund it (see Transactions).

One active schedule per account

A reusable account can have a single active schedule. Pause, resume, or cancel it as the subscription changes.
get/api/v1/billing/schedules

List the tenant's billing schedules (most recent first).

Requires Bearer token

Query parameters

takeintegeroptional

Responses

200OK
GET /api/v1/billing/schedules
curl -X GET "https://api.xental.online/api/v1/billing/schedules" \
  -H "Authorization: Bearer <API_TOKEN>"
post/api/v1/billing/schedules

Create a schedule on one of your reusable virtual accounts and open its first period.

Creates a schedule on one of your reusable virtual accounts and opens the first period. Interval is Weekly | Monthly | Quarterly | Yearly.

Requires Bearer token

Body parameters

accountRefstringoptional
intervalstringoptional
amountKobointegeroptional
dueOffsetDaysintegeroptional
descriptionstringoptional
referencestringoptional

Responses

201Created400Invalid interval/amount, or the account is closed.404No virtual account for the given accountRef.409The account already has an active schedule (or ref clash).
POST /api/v1/billing/schedules
curl -X POST "https://api.xental.online/api/v1/billing/schedules" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "accountRef": "inv_001",
    "amountKobo": 500000,
    "dueOffsetDays": 100000
  }'
Example request body
{
  "accountRef": "inv_001",
  "amountKobo": 500000,
  "dueOffsetDays": 100000
}
get/api/v1/billing/schedules/{id}

Fetch a schedule by id.

Requires Bearer token

Path parameters

idstringrequired

Responses

200OK404Not Found
GET /api/v1/billing/schedules/{id}
curl -X GET "https://api.xental.online/api/v1/billing/schedules/:id" \
  -H "Authorization: Bearer <API_TOKEN>"
put/api/v1/billing/schedules/{id}/next-amount

Set the expected amount for the next cycle (variable billing).

Sets the expected amount for the next cycle — billing is variable, so each period can differ.

Requires Bearer token

Path parameters

idstringrequired

Body parameters

amountKobointegeroptional

Responses

200OK404Not Found
PUT /api/v1/billing/schedules/{id}/next-amount
curl -X PUT "https://api.xental.online/api/v1/billing/schedules/:id/next-amount" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "amountKobo": 500000
  }'
Example request body
{
  "amountKobo": 500000
}
post/api/v1/billing/schedules/{id}/pause

Pause a schedule (stops opening new periods).

Requires Bearer token

Path parameters

idstringrequired

Responses

200OK
POST /api/v1/billing/schedules/{id}/pause
curl -X POST "https://api.xental.online/api/v1/billing/schedules/:id/pause" \
  -H "Authorization: Bearer <API_TOKEN>"
post/api/v1/billing/schedules/{id}/resume

Resume a paused schedule.

Requires Bearer token

Path parameters

idstringrequired

Responses

200OK
POST /api/v1/billing/schedules/{id}/resume
curl -X POST "https://api.xental.online/api/v1/billing/schedules/:id/resume" \
  -H "Authorization: Bearer <API_TOKEN>"
post/api/v1/billing/schedules/{id}/cancel

Cancel a schedule permanently.

Requires Bearer token

Path parameters

idstringrequired

Responses

200OK
POST /api/v1/billing/schedules/{id}/cancel
curl -X POST "https://api.xental.online/api/v1/billing/schedules/:id/cancel" \
  -H "Authorization: Bearer <API_TOKEN>"
get/api/v1/billing/schedules/{id}/periods

List a schedule's billing periods (most recent first).

Requires Bearer token

Path parameters

idstringrequired

Query parameters

takeintegeroptional

Responses

200OK404Not Found
GET /api/v1/billing/schedules/{id}/periods
curl -X GET "https://api.xental.online/api/v1/billing/schedules/:id/periods" \
  -H "Authorization: Bearer <API_TOKEN>"