# 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.](/overview#required-request-headers)

### 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`)

```js

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

```

**List Schedules Success Response**
**HTTP Status:** `200 OK`


```js
  {
    "status": "successful",
    "message": "Schedules retrieved successfully.",
    "data": [],
    "meta": {}
  }
```
**Standard Error Response**

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

### 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 |