Schedule Payments

Schedule Airtime, Data, Cable TV and Electricity payments that Paybeta charges to your wallet automatically - once, or daily / weekly / monthly.

Authentication

Every request is authenticated with your live API key in the P-API-KEY header. No transaction PIN is needed. See Authentication details.

How charging works

Nothing is debited when you create a schedule. At each run Paybeta prices the payment with your merchant API commission (the same pricing as a direct purchase), debits your wallet, and calls the biller. The result is sent to your registered webhook (transaction.successful, transaction.pending, transaction.failed) in the same format as direct purchases.
If a run can't be charged (e.g. insufficient balance, biller down, plan price changed) nothing is debited, the schedule moves to failed (see failure_reason), and you can Retry it. If the run had already created a transaction (e.g. insufficient balance) you also receive a transaction.failed webhook. Once your wallet is debited the run is never marked failed; an unconfirmed biller response stays pending until it is confirmed.

Rules

start_at must be at least 10 minutes and at most 1 year ahead (Africa/Lagos time, format YYYY-MM-DD HH:mm or ISO-8601).

ends_at (optional, recurring only) must be after start_at.

Up to 20 open schedules (active / processing / failed / paused) per account.

Airtime: ₦50 - ₦20,000. Data: bundle ≥ ₦200. Cable TV: ₦500 - ₦80,000. Electricity: ₦1,000 - ₦50,000.

Phone numbers: 11 digits starting with 0.

Schedule statuses

active waiting for its next run · processing a run is in progress · completed finished (one-time done or past ends_at) · failed last run was not charged, can be retried · paused on hold · cancelled archived.

Response formats

Standard Success Response
HTTP Status: 200 OK (or 201 Created)

List Schedules Success Response
HTTP Status: 200 OK

Standard Error Response

HTTP Status Codes

Code	Status	Trigger / Description
401	Unauthorized	Missing or invalid API key
404	Not Found	Requested resource not found
422	Unprocessable Entity	Validation failed or action not allowed in current state

Authentication#

How charging works#

Rules#

Schedule statuses#