1. Schedule Payments
PAYBETA API
  • Bill Payment API
  • Webhook
  • Paybeta Commission
  • Airtime
    • Providers
      GET
    • Payment
      POST
  • Data Bundle
    • Get Providers
      GET
    • Get Data Bundles
      POST
    • Payment
      POST
  • Cable TV
    • Get Providers
      GET
    • Get Bouquet
      POST
    • Validate Account
      POST
    • Payment
      POST
  • Electricity
    • Get Providers
      GET
    • Validate Account
      POST
    • Payment
      POST
  • Showmax
    • Get Bouquets
      GET
    • Payment
      POST
  • Gaming
    • Get Providers
      GET
    • Validate Account
      POST
    • Payment
      POST
  • Wallet
    • Balance
  • Education
    • Get Providers
    • Get Exam Types
  • Webhook (reference)
  • Schedule Payments
    • Scheduled Payments
    • Setup
      • Options
      • Bundles
    • Create
      • Create - Airtime (one time)
      • Create - Data (monthly)
      • Create - Cable TV (monthly)
      • Create - Electricity (weekly)
    • Manage
      • List schedules
      • Get schedule
      • Update schedule
      • Pay now
      • Retry failed run
      • Pause
      • Resume
      • Cancel (archive)
      • Re-enable
      • Delete
  • Transaction Query
    POST
  1. Schedule Payments

Scheduled 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.

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
Modified at 2026-10-05 22:15:43
Previous
Webhook (reference)
Next
Options
Built with