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)

{
  "status": "successful",
  "message": "Operation completed successfully.",
  "data": {}
}

List Schedules Success Response HTTP Status: 200 OK

  {
    "status": "successful",
    "message": "Schedules retrieved successfully.",
    "data": [],
    "meta": {}
  }

Standard Error Response

{
  "status": "failed",
  "message": "Error description here.",
  "errors": {
    "field_name": [
      "Validation or constraint error message."
    ]
  }
}

HTTP Status Codes#