# Paybeta API documentation

> Add airtime, data, electricity tokens, cable TV and JAMB/WAEC PINs to your Nigerian app with one REST API. Free sandbox and commission on every sale.

Developer documentation for the Paybeta API. It is a REST API: requests and responses are JSON.

- Live base URL: `https://api.paybeta.ng`
- Sandbox base URL: `https://api.sandbox.paybeta.ng` (use it for testing)
- Authentication: send your secret key in the `P-API-KEY` header.
- API keys: https://console.paybeta.ng
- Support: support@paybeta.ng
- Each page below is also available as markdown by adding `.md` to its URL.

---

Source: https://docs.paybeta.ng/overview

# Paybeta VTU & Bill Payment API Documentation

![Paybeta VTU and bill payment API for Nigeria](https://storebox.cloudone.ng/cdn/paybeta/web/static/img/Paybeta_App_Banner.jpg)


## Overview

The [Paybeta](https://www.paybeta.ng) API is a REST API for VTU and bill payments in Nigeria. With one integration and one wallet, your app can sell airtime, data bundles, electricity tokens, cable TV subscriptions and exam PINs.

Every request and response is JSON, and transaction results are also sent to your webhook. Paybeta manages the provider relationships, so you integrate once instead of with each telco, DisCo and TV provider. You can test everything in the sandbox before going live.

| | |
| --- | --- |
| **Protocol** | REST over HTTPS |
| **Data format** | JSON requests and responses |
| **Authentication** | API key in the `P-API-KEY` header |
| **Environments** | Sandbox and Production |
| **Commission** | See the [Commission Rate Schedule](https://www.paybeta.ng/commissions) |

## Supported Services and Providers

| Service | Providers | What you can do |
| --- | --- | --- |
| **Airtime (VTU)** | MTN, Airtel, Glo, 9mobile | Instant top-up to any Nigerian number, plus [bulk airtime](/buy-bulk-airtime) to many numbers in one request |
| **Data bundles** | MTN, Airtel, Glo, 9mobile | List available bundles and purchase by bundle code |
| **Electricity** | EKEDC, IKEDC, AEDC, IBEDC, EEDC, PHED, JED, KEDCO, KAEDCO | Validate a prepaid or postpaid meter, then pay and receive the token or units |
| **Cable TV and streaming** | DSTV, GOTV, StarTimes, Showmax | List bouquets, validate the smartcard number and renew the subscription |
| **Education** | JAMB, WAEC | List exam types and purchase PINs. See [Education](/education) |
| **Scheduled payments** | Airtime, data, cable TV, electricity | Create one-time or recurring purchases. See [Schedule Payments](/schedule-payments) |

### Electricity coverage

Paybeta supports all of Nigeria's 11 electricity distribution companies (DisCos):

| DisCo | Code |
| --- | --- |
| Eko Electricity | EKEDC |
| Ikeja Electric | IKEDC |
| Abuja Electricity | AEDC |
| Ibadan Electricity | IBEDC |
| Enugu Electricity | EEDC |
| Port Harcourt Electricity | PHED |
| Jos Electricity | JED |
| Kano Electricity | KEDCO |
| Kaduna Electric | KAEDCO |
| Aba Electric | ABA |
| Yola Electricity | YEDC |
| Benin Electricity | BEDC |


![How a Paybeta bill payment transaction flows](https://storebox.cloudone.ng/cdn/paybeta/web/static/img/paybeta_products.png)

## Getting Started

1. **Create a sandbox account.** Register for a [Sandbox Account](https://console.sandbox.paybeta.ng/register) to build and test your integration safely.

2. **Request API access.** Email support@paybeta.ng to request API activation. For real-time technical help, join the [Paybeta Slack Community](https://join.slack.com/t/paybetacommunity/shared_invite/zt-215i1gm93-tUxac83S_m3VWFTynadgOw).

3. **Complete verification.** Your Account Manager will guide you through the compliance checklist for KYC (Know Your Customer) and KYB (Know Your Business) documents.

4. **Go live.** Register for a [Production Account](https://console.paybeta.ng/register) and switch to the production base URL and your live API key.

⚠️ **Important**: Your account must be approved and enabled for Live Mode by the Paybeta compliance team before calls to production endpoints will succeed.

## Base URLs

| Environment | Base URL |
| --- | --- |
| Sandbox (**Testing**) | https://api.sandbox.paybeta.ng |
| Production (**Live**) | https://api.paybeta.ng |

## Authentication

All API requests must be made over **HTTPS**. Authenticate by sending your API key in the `P-API-KEY` request header. You can find your API keys in the [Paybeta Console Settings](https://console.paybeta.ng/merchant/settings).

Keep your API key secret. Call the API from your server only, and never expose the key in a mobile app or in browser code.

### Required request headers

| **Header** | **Value** | **Description** |
| --- | --- | --- |
| Accept | application/json | Sets the response format. |
| Content-Type | application/json | Sets the request payload format. |
| P-API-KEY | Your secret API key | Authorizes your API requests. |

### Example

```js
headers.set('Accept', 'application/json');
headers.set('Content-Type', 'application/json');
headers.set('P-API-KEY', 'YOUR_API_KEY');
```

## Response Format

Every response from the Paybeta API uses the same JSON structure, so you can handle success and errors the same way across all services.

| **Field** | **Type** | **Description** |
| --- | --- | --- |
| status | string | The state of the transaction: `successful`, `failed` or `pending`. |
| message | string | A human-readable explanation of the result. |
| data | object | Transaction details. For example, the token and units for electricity, or the generated PINs for ePIN requests. |

### Example response

```json
{
    "status": "successful",
    "message": "Transaction successful",
    "data": {
        "reference": "1714742875",
        "amount": 2000,
        "chargedAmount": 1950,
        "commission": 50,
        "biller": "MTN AIRTIME",
        "customerId": "08068539221",
        "transactionDate": "2024-05-03 14:27:57",
        "transactionId": "1714742877672593466202420"
    }
}
```

A `pending` status means the provider has not yet confirmed the transaction. Do not retry the purchase; wait for the final result on your [webhook](/webhook-reference).


---

Source: https://docs.paybeta.ng/commission

# Commission

Paybeta offers commissions to API users in the form of **discounts on transactions**. These commissions allow API agents to earn a portion (percentage or flat amount) of each transaction while providing seamless bill payment services to their customers.

If you’re looking to track your earnings, it’s essential to know where to find your Paybeta commissions. In this guide, we’ll walk you through the steps to locate commission details, understand your earnings, and ensure you’re maximizing your profits on the platform. Below, you’ll find a step-by-step guide on how to retrieve and review your commission, helping you maximize your profits.

### How API Commissions Work
Commissions are applied as discounts on transactions, reducing the final amount API customers pay instead of charging them the full transaction price.. The commission structure is categorized into three types:

#### 1. Percentage-Based Discount
The commission is applied as a **percentage of the transaction amount**.

This means that the discount is dynamically calculated based on the total value of the transaction.

**Example**: If a 4% commission is applied to a ₦1,000 transaction, the discount will be ₦**40**, making the effective charge ₦940.

#### 2. Flat Rate-Based Discount
The commission is applied as a **fixed amount per transaction**, regardless of the transaction value.

The discount is predetermined for each product.

**Example**: If a flat discount of **₦50** is set for a service, every transaction will receive a **₦50** reduction, irrespective of the transaction amount.

### Where to Find Paybeta Commissions?
You can view the general commission for each product directly on the website [**HERE**](https://www.paybeta.ng/commissions).


---

Source: https://docs.paybeta.ng/webhook-reference

# Webhook (reference)

> Each run that debits your wallet is reported to your registered webhook endpoint, in the same format as a direct purchase. `data.reference` is the run's transaction reference (it starts with the schedule reference), and `transactionId` matches the schedule's `last_run.transaction_id`.

```json
{
  "eventType": "transaction.successful",
  "type": "data",
  "data": {
    "reference": "SCH-7F3K9QX2AB12-K3P9XQ2M",
    "amount": "1,000.00",
    "chargedAmount": "970.00",
    "commission": "30.00",
    "biller": "MTN 1GB - 30 Days",
    "customerId": "08031234567",
    "token": "0",
    "unit": "0",
    "voucher": "0",
    "currency": "NGN",
    "transactionId": "API-17596704001234567",
    "transactionDate": "2026-11-01 09:00:12",
    "status": "SUCCESSFUL",
    "message": "Your transaction was successful"
  }
}
```

Paybeta webhooks include a cryptographic signature in the `Signature` header to ensure the webhook originated from **Paybeta** and hasn't been tampered with.

## Signature Generation
The value passed inside the Signature header is calculated using a Hash-based Message Authentication Code (HMAC) with a SHA-256 hashing algorithm.

- **Algorithm**: HMAC-SHA256
- **Key**: Your API `Secret Key` (keep this hidden on your backend server environment).
- **Data**: The reference value located inside the transaction data block (`data.reference`).

### Sample Request

**Sent for every recipient once it is charged (and again if a pending one is later confirmed or reversed):**

``` PHP
{
  "eventType": "transaction.successful|transaction.pending|transaction.failed",
  "type": "vtu|tv|gaming|data|utility|education|insurance|travel",
  "data": {
    "reference": "REF-3AQ780KP87WS1356",
    "amount": "300.00",
    "chargedAmount": "292.50",
    "commission": "7.50",
    "biller": "MTN Airtime",
    "customerId": "08030000000",
    "token": "0",
    "unit": "0",
    "bonusToken": "0",
    "voucher": "0",
    "currency": "NGN",
    "transactionId": "API-4780819357880920990",
    "transactionDate": "2025-03-07 16:29:17",
    "status": "SUCCESSFUL",
    "message": "Your transaction was successful"
  }
}
```

## How to Verify the Signature

- Capture the incoming raw JSON payload and extract the data.reference string.
- Read the value present inside the Signature request header.
- Compute an **HMAC-SHA256** hash using the transaction reference as the data string and your merchant secret key as the signing key.
- Compare your locally computed string with the header value using a **constant-time string comparison** method to safeguard against timing analysis side-channel attacks.

Code Verification Code Examples




**PHP / Laravel**

 
    
    ```PHP
  
    <?php

    namespace App\Http\Controllers;

    use Illuminate\Http\Request;

    class PaybetaWebhookController extends Controller
    {
        public function handle(Request $request)
        {
            $payload = $request->json()->all();
            $headerSignature = $request->header('Signature');

            // Extract transaction reference
            $reference = $payload['data']['reference'] ?? '';

            // Retrieve your secret key securely from configuration
            $secretKey = config('services.paybeta.secret_key');

            // Calculate expected signature
            $computedSignature = hash_hmac('sha256', $reference, $secretKey);

            // Safe string comparison preventing timing attacks
            if (!hash_equals($computedSignature, $headerSignature)) {
                return response()->json(['error' => 'Invalid Signature'], 401);
            }

            // Process transaction event logic below
            // ...

            return response()->json(['status' => 'success'], 200);
        }
    }
    ```



**Node.js (Express)**

    ``` JS
    const express = require('express');
    const crypto = require('crypto');
    const app = express();

    app.use(express.json());

    app.post('/webhooks/paybeta', (req, res) => {
        const headerSignature = req.headers['signature'];
        const payload = req.body;

        // Extract transaction reference
        const reference = payload?.data?.reference || '';
        const secretKey = process.env.PAYBETA_SECRET_KEY;

        // Compute signature
        const computedSignature = crypto
            .createHmac('sha256', secretKey)
            .update(reference)
            .digest('hex');

        // Safe timing-attack-resistant comparison
        try {
            const isVerified = crypto.timingSafeEqual(
                Buffer.from(computedSignature, 'utf-8'),
                Buffer.from(headerSignature, 'utf-8')
            );

            if (!isVerified) {
                return res.status(401).json({ error: 'Invalid Signature' });
            }
        } catch (e) {
            return res.status(401).json({ error: 'Verification failed' });
        }

        // Process event data safely
        res.status(200).json({ status: 'success' });
    });

     ```


**C# (.NET Core / ASP.NET)**

    
```csharp

using Microsoft.AspNetCore.Mvc;
using System.Security.Cryptography;
using System.Text;
using System.Text.Json;

namespace PaybetaWebhook.Controllers
{
    [ApiController]
    [Route("webhooks")]
    public class PaybetaWebhookController : ControllerBase
    {
        private const string SecretKey = "your_secret_key_here";

        [HttpPost("paybeta")]
        public async Task<IActionResult> HandleWebhook()
        {
            // 1. Extract the Signature from headers
            if (!Request.Headers.TryGetValue("Signature", out var headerSignature))
            {
                return Unauthorized(new { error = "Missing Signature header" });
            }

            // 2. Read and parse the incoming body stream
            using var reader = new StreamReader(Request.Body);
            var rawJson = await reader.ReadToEndAsync();
            
            using var jsonDoc = JsonDocument.Parse(rawJson);
            
            // Navigate safely to payload string: data.reference
            string reference = "";
            if (jsonDoc.RootElement.TryGetProperty("data", out var dataElement) && 
                dataElement.TryGetProperty("reference", out var refElement))
            {
                reference = refElement.GetString() ?? "";
            }

            // 3. Compute expected HMAC-SHA256 signature
            var keyBytes = Encoding.UTF8.GetBytes(SecretKey);
            var referenceBytes = Encoding.UTF8.GetBytes(reference);

            using var hmac = new HMACSHA256(keyBytes);
            var hashBytes = hmac.ComputeHash(referenceBytes);
            
            // Convert byte array to hexadecimal string representation
            var computedSignature = Convert.ToHexString(hashBytes).ToLower();

            // 4. Safe constant-time string comparison
            if (!CryptographicOperations.FixedTimeEquals(
                Encoding.UTF8.GetBytes(computedSignature), 
                Encoding.UTF8.GetBytes(headerSignature.ToString())))
            {
                return Unauthorized(new { error = "Invalid Signature" });
            }

            // Execute core backend settlement workflow here
            return Ok(new { status = "success" });
        }
    }
}
```


**Java (Spring Boot)**

    
```java
package com.paybeta.webhook.controller;

import org.json.JSONObject;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;

@RestController
@RequestMapping("/webhooks")
public class PaybetaWebhookController {

    private static final String SECRET_KEY = "your_secret_key_here";

    @PostMapping("/paybeta")
    public ResponseEntity<String> handleWebhook(
            @RequestHeader("Signature") String headerSignature,
            @RequestBody String rawJsonPayload) {

        try {
            // 1. Parse JSON block to extract the transaction reference string
            JSONObject jsonObject = new JSONObject(rawJsonPayload);
            String reference = jsonObject.getJSONObject("data").optString("reference", "");

            // 2. Initialize HMAC-SHA256 Engine
            Mac sha256HMAC = Mac.getInstance("HmacSHA256");
            SecretKeySpec secretKeySpec = new SecretKeySpec(
                SECRET_KEY.getBytes(StandardCharsets.UTF_8), "HmacSHA256"
            );
            sha256HMAC.init(secretKeySpec);

            // 3. Calculate Signature Bytes and encode to Hex string representation
            byte[] rawMacBytes = sha256HMAC.doFinal(reference.getBytes(StandardCharsets.UTF_8));
            StringBuilder hexStringBuilder = new StringBuilder();
            for (byte b : rawMacBytes) {
                hexStringBuilder.append(String.format("%02x", b));
            }
            String computedSignature = hexStringBuilder.toString();

            // 4. Secure constant-time evaluation to block execution timing attacks
            boolean signaturesMatch = MessageDigest.isEqual(
                    computedSignature.getBytes(StandardCharsets.UTF_8),
                    headerSignature.getBytes(StandardCharsets.UTF_8)
            );

            if (!signaturesMatch) {
                return ResponseEntity.status(HttpStatus.UNAUTHORIZED)
                        .body("{\"error\": \"Invalid Signature\"}");
            }

            // Process your platform updates here safely
            return ResponseEntity.ok("{\"status\": \"success\"}");

        } catch (Exception e) {
            return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
                    .body("{\"error\": \"Processing exception occurred\"}");
        }
    }
}

```


**Python (Flask)**

    
```python

import hmac
import hashlib
from flask import Flask, request, jsonify

app = Flask(__name__)

PAYBETA_SECRET_KEY = "your_secret_key_here"

@app.route('/webhooks/paybeta', methods=['POST'])
def paybeta_webhook():
    header_signature = request.headers.get('Signature')
    payload = request.get_json() or {}
    
    # Extract reference path string
    transaction_data = payload.get('data', {})
    reference = transaction_data.get('reference', '')

    # Generate expected hash match
    computed_signature = hmac.new(
        key=PAYBETA_SECRET_KEY.encode('utf-8'),
        msg=reference.encode('utf-8'),
        digestmod=hashlib.sha256
    ).hexdigest()

    # Compare safely
    if not hmac.compare_digest(computed_signature, header_signature):
        return jsonify({"error": "Invalid Signature"}), 401

    # Execute system update routines
    return jsonify({"status": "success"}), 200

if __name__ == '__main__':
    app.run(port=5000)
```




---

Source: https://docs.paybeta.ng/airtime-providers

# Providers

`GET https://api.paybeta.ng/v2/airtime/providers`

Authentication: `P-API-KEY` header.

Response:

``` json
{
  "status": "successful",
  "message": "Request processed successfully.",
  "data": [
    {
      "name": "MTN VTU",
      "category": "airtime",
      "status": true,
      "logo": "https://res.cloudinary.com/paybeta/image/upload/v1713709773/Provider/VTU/800px-New-mtn-logo_wpn9qq.jpg"
    },
    {
      "name": "GLO VTU",
      "category": "airtime",
      "status": true,
      "logo": "https://res.cloudinary.com/paybeta/image/upload/v1713709647/Provider/VTU/glo_fpaf7m.svg"
    },
    {
      "name": "AIrtel VTU",
      "category": "airtime",
      "status": true,
      "logo": "https://res.cloudinary.com/paybeta/image/upload/v1713709747/Provider/VTU/airtel_qkjpk1.png"
    },
    {
      "name": "9mobile VTU",
      "category": "airtime",
      "status": true,
      "logo": "https://res.cloudinary.com/paybeta/image/upload/v1713709763/Provider/VTU/9mobile_iswfnh.svg"
    }
  ]
}

 ```

## Response 200: Success

```json
{
    "status": "successful",
    "message": "Request processed successfully.",
    "data": [
        {
            "name": "MTN VTU",
            "category": "airtime",
            "status": true,
            "logo": "https://res.cloudinary.com/paybeta/image/upload/v1713709773/Provider/VTU/800px-New-mtn-logo_wpn9qq.jpg"
        },
        {
            "name": "GLO VTU",
            "category": "airtime",
            "status": true,
            "logo": "https://res.cloudinary.com/paybeta/image/upload/v1713709647/Provider/VTU/glo_fpaf7m.svg"
        },
        {
            "name": "AIrtel VTU",
            "category": "airtime",
            "status": true,
            "logo": "https://res.cloudinary.com/paybeta/image/upload/v1713709747/Provider/VTU/airtel_qkjpk1.png"
        },
        {
            "name": "9mobile VTU",
            "category": "airtime",
            "status": true,
            "logo": "https://res.cloudinary.com/paybeta/image/upload/v1713709763/Provider/VTU/9mobile_iswfnh.svg"
        }
    ]
}
```


---

Source: https://docs.paybeta.ng/airtime-payment

# Payment

`POST https://api.paybeta.ng/v2/airtime/purchase`

Authentication: `P-API-KEY` header.

The available service are:

_mtn_vtu_

_glo_vtu_

_9mobile_vtu_

_airtel_vtu_

## Body

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `service` | string | yes |  |
| `phoneNumber` | string | yes |  |
| `amount` | integer | yes |  |
| `reference` | string | yes |  |

## Request: Request body

```json
{
    "service": "mtn_vtu",
    "phoneNumber": "08123333394",
    "amount": 200,
    "reference": "{{$timestamp}}"
}
```

## Response 200: Success

```json
{
    "status": "successful",
    "message": "Transaction successful",
    "data": {
        "reference": "1714742875",
        "amount": 2000,
        "chargedAmount": 1950,
        "commission": 50,
        "biller": "MTN AIRTIME",
        "customerId": "08068539221",
        "previousBalance": 499971725,
        "currentBalance": 499969775,
        "transactionDate": "2024-05-03 14:27:57",
        "transactionId": "1714742877672593466202420"
    }
}
```


---

Source: https://docs.paybeta.ng/mtn-vtu-api-integration

# MTN VTU API Integration

> This section contains the recommended flow for integrating MTN VTU services on the Paybeta RESTful API.

MTN Airtime API on Paybeta


---

Source: https://docs.paybeta.ng/data-bundle-get-providers

# Get Providers

`GET https://api.paybeta.ng/v2/data-bundle/providers`

Authentication: `P-API-KEY` header.

``` json
{
    "status": "successful",
    "message": "Request processed successfully.",
    "data": [
        {
            "name": "Airtel Data",
            "category": "internet",
            "slug": "airtel-data",
            "status": true,
            "logo": "https://res.cloudinary.com/paybeta/image/upload/v1713709747/Provider/VTU/airtel_qkjpk1.png"
        },
        {
            "name": "MTN Data",
            "category": "internet",
            "slug": "mtn-data",
            "status": true,
            "logo": "https://res.cloudinary.com/paybeta/image/upload/v1713709773/Provider/VTU/800px-New-mtn-logo_wpn9qq.jpg"
        },
        {
            "name": "Glo Data",
            "category": "internet",
            "slug": "glo-data",
            "status": true,
            "logo": "https://res.cloudinary.com/paybeta/image/upload/v1713709647/Provider/VTU/glo_fpaf7m.svg"
        },
        {
            "name": "9mobile Data",
            "category": "internet",
            "slug": "9mobile-data",
            "status": true,
            "logo": "https://res.cloudinary.com/paybeta/image/upload/v1713709763/Provider/VTU/9mobile_iswfnh.svg"
        }
    ]
}

 ```

## Response 200: Success

```json
{
    "status": "successful",
    "message": "Request processed successfully.",
    "data": [
        {
            "name": "Airtel Data",
            "category": "internet",
            "slug": "airtel-data",
            "status": true,
            "logo": "https://res.cloudinary.com/paybeta/image/upload/v1713709747/Provider/VTU/airtel_qkjpk1.png"
        },
        {
            "name": "MTN Data",
            "category": "internet",
            "slug": "mtn-data",
            "status": true,
            "logo": "https://res.cloudinary.com/paybeta/image/upload/v1713709773/Provider/VTU/800px-New-mtn-logo_wpn9qq.jpg"
        },
        {
            "name": "Glo Data",
            "category": "internet",
            "slug": "glo-data",
            "status": true,
            "logo": "https://res.cloudinary.com/paybeta/image/upload/v1713709647/Provider/VTU/glo_fpaf7m.svg"
        },
        {
            "name": "9mobile Data",
            "category": "internet",
            "slug": "9mobile-data",
            "status": true,
            "logo": "https://res.cloudinary.com/paybeta/image/upload/v1713709763/Provider/VTU/9mobile_iswfnh.svg"
        }
    ]
}
```


---

Source: https://docs.paybeta.ng/data-bundle-get-data-bundles

# Get Data Bundles

`GET https://api.paybeta.ng/v2/data-bundle/list`

Authentication: `P-API-KEY` header.

``` json
{
    "status": "successful",
    "message": "Request processed successfully.",
    "data": [
        {
            "name": "Airtel Data",
            "category": "internet",
            "slug": "airtel-data",
            "status": true,
            "logo": "https://res.cloudinary.com/paybeta/image/upload/v1713709747/Provider/VTU/airtel_qkjpk1.png"
        },
        {
            "name": "MTN Data",
            "category": "internet",
            "slug": "mtn-data",
            "status": true,
            "logo": "https://res.cloudinary.com/paybeta/image/upload/v1713709773/Provider/VTU/800px-New-mtn-logo_wpn9qq.jpg"
        },
        {
            "name": "Glo Data",
            "category": "internet",
            "slug": "glo-data",
            "status": true,
            "logo": "https://res.cloudinary.com/paybeta/image/upload/v1713709647/Provider/VTU/glo_fpaf7m.svg"
        },
        {
            "name": "9mobile Data",
            "category": "internet",
            "slug": "9mobile-data",
            "status": true,
            "logo": "https://res.cloudinary.com/paybeta/image/upload/v1713709763/Provider/VTU/9mobile_iswfnh.svg"
        }
    ]
}

 ```

## Body

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `service` | string | yes |  |

## Request: Request body

```json
{
    "service": "mtn_data"
}
```

## Response 200: Success

```json
{
    "status": "successful",
    "message": "Request processed successfully.",
    "data": {
        "packages": [
            {
                "code": "MTN_100_MB_DAILY_DATA_BUNDLE",
                "description": "MTN 100 MB DAILY DATA BUNDLE",
                "price": "100.00"
            },
            {
                "code": "MTN_200_MB_DAILY_DATA_BUNDLE",
                "description": "MTN 200 MB DAILY DATA BUNDLE",
                "price": "200.00"
            },
            {
                "code": "MTN_1.8_GB_MONTHLY_DATA_BUNDLE",
                "description": "MTN 1.8 GB MONTHLY DATA BUNDLE",
                "price": "1500.00"
            },
            ...
        ]
    }
}
```


---

Source: https://docs.paybeta.ng/data-bundle-payment

# Payment

`POST https://api.paybeta.ng/v2/data-bundle/purchase`

Authentication: `P-API-KEY` header.

## Body

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `service` | string | yes |  |
| `amount` | integer | yes |  |
| `phoneNumber` | string | yes |  |
| `code` | string | yes |  |
| `reference` | string | yes |  |

## Request: Request body

```json
{
    "service": "mtn_data",
    "amount": 100,
    "phoneNumber": "08138539550",
    "code": "MT1",
    "reference": "{{$timestamp}}"
}
```

## Response 200: Success

```json
{
    "status": "successful",
    "message": "Transaction successful",
    "data": {
        "reference": "1715553597",
        "amount": 100,
        "chargedAmount": 97.5,
        "commission": 2.5,
        "biller": "MTN 100MB 1 Day",
        "customerId": "08060000000",
        "token": null,
        "unit": null,
        "bonusToken": null,
        "transactionDate": "2024-05-12 23:39:58",
        "transactionId": "17155535989070949852"
    }
}
```


---

Source: https://docs.paybeta.ng/cable-tv-get-providers

# Get Providers

`GET https://api.paybeta.ng/v2/cable/providers`

Authentication: `P-API-KEY` header.

## Response 200: Success

```json
{
    "status": "successful",
    "message": "Request processed successfully.",
    "data": [
        {
            "name": "DStv",
            "category": "cable",
            "slug": "dstv",
            "status": true,
            "logo": "https://res.cloudinary.com/paybeta/image/upload/v1714827633/Provider/Cable/dstv.jpg"
        },
        {
            "name": "GOtv",
            "category": "cable",
            "slug": "gotv",
            "status": true,
            "logo": "https://res.cloudinary.com/paybeta/image/upload/v1714828100/Provider/Cable/gotv.png"
        },
        {
            "name": "StarTimes",
            "category": "cable",
            "slug": "startimes",
            "status": true,
            "logo": "https://res.cloudinary.com/paybeta/image/upload/v1714827913/Provider/Cable/startimes.jpg"
        }
    ]
}
```


---

Source: https://docs.paybeta.ng/cable-tv-get-bouquet

# Get Bouquet

`POST https://api.paybeta.ng/v2/cable/bouquet`

Authentication: `P-API-KEY` header.

## Body

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `service` | string | yes |  |

## Request: Request body

```json
{
    "service": "dstv"
}
```

## Response 200: Success

```json
{
    "status": "successful",
    "message": "Request processed successfully.",
    "data": {
        "packages": [
            {
                "code": "GOHAN",
                "description": "GOtv Smallie - monthly",
                "price": "1900"
            },
            {
                "code": "GOTVNJ1",
                "description": "GOtv Jinja Bouquet",
                "price": "3900"
            },
            {
                "code": "GOLITE",
                "description": "GOtv Smallie - quarterly",
                "price": "5100"
            },
            {
                "code": "GOTVNJ2",
                "description": "GOtv Jolli Bouquet",
                "price": "5800"
            },
            {
                "code": "GOtvMax",
                "description": "GOtv Max",
                "price": "8500"
            },
            {
                "code": "GOTVSUPA",
                "description": "SUPA",
                "price": "11400"
            },
            {
                "code": "GOTVSUPAPLUS",
                "description": "GOtv Supa Plus Bouquet",
                "price": "13900"
            },
            {
                "code": "GOLTANL",
                "description": "GOtv Smallie - yearly",
                "price": "15000"
            }
        ]
    }
}
```


---

Source: https://docs.paybeta.ng/cable-tv-validate-account

# Validate Account

`POST https://api.paybeta.ng/v2/cable/validate`

Authentication: `P-API-KEY` header.

## Body

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `service` | string | yes |  |
| `smartCardNumber` | string | yes |  |

## Request: Request body

```json
{
    "service": "gotv",
    "smartCardNumber": "8072916698"
}
```

## Response 200: Success

```json
{
    "status": "successful",
    "message": "Request processed successfully.",
    "data": {
        "customerName": "KAREEM KAREEM",
        "smartCardNumber": "8072916698",
        "service": "GOTV"
    }
}
```


---

Source: https://docs.paybeta.ng/cable-tv-payment

# Payment

`POST https://api.paybeta.ng/v2/cable/purchase`

Authentication: `P-API-KEY` header.

## Body

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `service` | string | yes |  |
| `smartCardNumber` | string | yes |  |
| `amount` | integer | yes |  |
| `packageCode` | string | yes |  |
| `customerName` | string | yes |  |
| `reference` | string | yes |  |

## Request: Request body

```json
{
    "service": "dstv",
    "smartCardNumber": "806***82",
    "amount": 200,
    "packageCode": "COMPLE36",
    "customerName": "JOHN DOE",
    "reference": "{{$timestamp}}"
}
```

## Response 200: Success

```json
{
    "status": "successful",
    "message": "Transaction successful",
    "data": {
        "reference": "1715458530",
        "amount": 201,
        "chargedAmount": 197.99,
        "commission": 3.02,
        "biller": "DStv Compact Plus",
        "customerId": "8216167618",
        "token": null,
        "unit": null,
        "bonusToken": null,
        "transactionDate": "2024-05-11 21:15:31",
        "transactionId": "17154585319693132432"
    }
}
```


---

Source: https://docs.paybeta.ng/electricity-get-providers

# Get Providers

`GET https://api.paybeta.ng/v2/electricity/providers`

Authentication: `P-API-KEY` header.

## Response 200: Success

```json
{
    "status": "successful",
    "message": "Request processed successfully.",
    "data": [
        {
            "name": "Enugu Electricity",
            "category": "electricity",
            "slug": "enugu-electric",
            "status": true,
            "logo": "https://res.cloudinary.com/paybeta/image/upload/v1715293602/Provider/Electricity/eedc.png"
        },
        {
            "name": "Abuja Electricity",
            "category": "electricity",
            "status": true,
            "logo": "https://res.cloudinary.com/paybeta/image/upload/v1715293658/Provider/Electricity/aedc.png"
        },
        {
            "name": "Ikeja Electric",
            "category": "electricity",
            "slug": "ikeja-electric",
            "status": true,
            "logo": "https://res.cloudinary.com/paybeta/image/upload/v1715293826/Provider/Electricity/ikedc.png"
        }
        ...
    ]
}
```


---

Source: https://docs.paybeta.ng/electricity-validate-account

# Validate Account

`POST https://api.paybeta.ng/v2/electricity/validate`

Authentication: `P-API-KEY` header.

## Body

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `service` | string | yes |  |
| `meterNumber` | string | yes |  |
| `meterType` | string | yes |  |

## Request: Request body

```json
{
    "service": "ikeja-electric",
    "meterNumber": "0111100049",
    "meterType": "prepaid"
}
```


---

Source: https://docs.paybeta.ng/electricity-payment

# Payment

`POST https://api.paybeta.ng/v2/electricity/purchase`

Authentication: `P-API-KEY` header.

## Body

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `service` | string | yes |  |
| `meterNumber` | string | yes |  |
| `meterType` | string | yes |  |
| `amount` | integer | yes |  |
| `customerName` | string | yes |  |
| `customerAddress` | string | yes |  |
| `reference` | string | yes |  |

## Request: Request body

```json
{
    "service": "ikeja-electric",
    "meterNumber": "042***3016",
    "meterType": "prepaid",
    "amount": 2000,
    "customerName": "MR JOHN DOE",
    "customerAddress": "1 JOHN DOE STR",
    "reference": "{{$timestamp}}"
}
```

## Response 200: Success

```json
{
    "status": "successful",
    "message": "Transaction successful",
    "data": {
        "reference": "1715455653",
        "amount": 1000,
        "chargedAmount": 496.5,
        "commission": 3.5,
        "biller": "Ikeja Electricity - IKEDC",
        "customerId": "10428776010",
        "token": "3193-6233-0096-7827-3805",
        "unit": "44.6",
        "bonusToken": "",
        "transactionDate": "2024-05-11 20:27:33",
        "transactionId": "17154556531428310982"
    }
}
```


---

Source: https://docs.paybeta.ng/gaming-get-providers

# Get Providers

`GET https://api.paybeta.ng/v2/gaming/providers`

Authentication: `P-API-KEY` header.

## Response 200: Success

```json
{
    "status": "successful",
    "message": "Request processed successfully.",
    "data": [
        {
            "name": "betking",
            "category": "gaming",
            "slug": "betking",
            "logo": ""
        },
        {
            "name": "bet9ja",
            "category": "gaming",
            "slug": "bet9ja",
            "logo": ""
        },
        {
            "name": "bangbet",
            "category": "gaming",
            "slug": "bangbet",
            "logo": ""
        }
        ...
    ]
}
```


---

Source: https://docs.paybeta.ng/gaming-validate-account

# Validate Account

`POST https://api.paybeta.ng/v2/gaming/validate`

Authentication: `P-API-KEY` header.

## Body

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `service` | string | yes |  |
| `customerId` | string | yes |  |

## Request: Request body

```json
{
    "service": "nairabet",
    "customerId": "20***96"
}
```

## Response 200: Success

```json
{
    "status": "successful",
    "message": "Request processed successfully.",
    "data": {
        "customerName": "DAVID SAKOUNO",
        "customerId": "14430818",
        "service": "Bet9ja",
        "minimumAmount": 100
    }
}
```


---

Source: https://docs.paybeta.ng/gaming-payment

# Payment

`POST https://api.paybeta.ng/v2/gaming/purchase`

Authentication: `P-API-KEY` header.

## Body

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `service` | string | yes |  |
| `customerId` | string | yes |  |
| `amount` | integer | yes |  |
| `customerName` | string | yes |  |
| `reference` | string | yes |  |

## Request: Request body

```json
{
    "service": "nairabet",
    "customerId": "201***96",
    "amount": 1000,
    "customerName": "gen***07",
    "reference": "{{$timestamp}}"
}
```


---

Source: https://docs.paybeta.ng/education

# Education


---

Source: https://docs.paybeta.ng/education-get-providers

# Get Providers

`GET https://api.paybeta.ng/v2/education/providers`

Authentication: `P-API-KEY` header.

## Response 200: Success

```json
{
    "status": "successful",
    "message": "Request processed successfully.",
    "data": [
        {
            "name": "JAMB PIN Vending",
            "category": "education",
            "slug": "jamb",
            "logo": "https://res.cloudinary.com/paybeta/image/upload/v1770680329/Static/img/jamb-pin-vending.jpg"
        },
        {
            "name": "WAEC Registration PIN",
            "category": "education",
            "slug": "waec-registration",
            "logo": "https://res.cloudinary.com/paybeta/image/upload/v1770680211/Static/img/waec-pin.jpg"
        },
        {
            "name": "WAEC Result Checker PIN",
            "category": "education",
            "slug": "waec-result",
            "logo": "https://res.cloudinary.com/paybeta/image/upload/v1770680280/Static/img/waec-result-checker-pin.jpg"
        }
    ]
}
```


---

Source: https://docs.paybeta.ng/education-get-exam-types

# Get Exam Types

`POST https://api.paybeta.ng/v2/education/list`

Authentication: `P-API-KEY` header.

## Request: Request body

```json
{
    "service": "jamb"
}
```

## Response 200: Success

```json
{
    "status": "successful",
    "message": "Request processed successfully.",
    "data": [
        {
            "name": "DStv",
            "category": "cable",
            "slug": "dstv",
            "status": true,
            "logo": "https://res.cloudinary.com/paybeta/image/upload/v1714827633/Provider/Cable/dstv.jpg"
        },
        {
            "name": "GOtv",
            "category": "cable",
            "slug": "gotv",
            "status": true,
            "logo": "https://res.cloudinary.com/paybeta/image/upload/v1714828100/Provider/Cable/gotv.png"
        },
        {
            "name": "StarTimes",
            "category": "cable",
            "slug": "startimes",
            "status": true,
            "logo": "https://res.cloudinary.com/paybeta/image/upload/v1714827913/Provider/Cable/startimes.jpg"
        }
    ]
}
```


---

Source: https://docs.paybeta.ng/education-payment

# Payment

`POST https://api.paybeta.ng/v2/education/purchase`

Authentication: `P-API-KEY` header.

## Request: Request body

```json
{
    "service": "jamb",
    "examCode": "UTMEWOM",
    "customerId": "529***4301",
    "amount": 7600,
    "reference": "{{$timestamp}}"
}
```


---

Source: https://docs.paybeta.ng/buy-bulk-airtime

# Buy Bulk Airtime

Top up many phone numbers in one request. Send a JSON list of recipients; Paybeta checks the whole list, confirms your wallet covers it, then processes **each number** on its own — one failed number never holds up the rest.

### 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 it works
1. Submit the list. Every recipient is validated up front; if any row is invalid the whole request is rejected with the row in the error key (e.g. `recipients.3.phone_number`) and nothing is queued.
2. The priced total (`total_charge`, after your API commission) must be covered by your wallet balance.
3. Each recipient is then processed in turn (a few seconds apart): priced with your API commission, debited from your wallet, sent to the network once, and reported to your **webhook** like any airtime purchase.
4. A recipient that can't be charged (e.g. balance ran out mid-way, network down) is marked failed and not debited. An unconfirmed network response stays `pending` until it is confirmed (`delivered`) or refunded (`reversed`).
5. The same phone number appearing twice in one request is topped up at least 5 minutes apart.


### Rules
- Up to 1,000 recipients per request; total of all amounts at least **NGN100**.
- biller: `mtn`, `glo`, `airtel` or `9mobile` (`mtn_vtu` etc. also accepted).
- `phone_number`: 234 + 10 digits (e.g. `2348031234567`); `08031234567` is also accepted.
- amount: NGN50 – NGN20,000 per recipient; a phone number can receive at most NGN50,000 airtime per day.
- `reference` (request): yours, required, **5-40** chars (letters, numbers, `.` `_` `-`), unique per account.
- `recipients[].reference`: optional, 5-60 chars, unique. Defaults to `<reference>-<row>` (e.g. `PAYROLL-OCT-2`). No reference may have been used for an earlier transaction.

   
### Tracking a number
Each recipient is its own transaction: query it with `POST /v2/transaction/query` and the recipient's `reference`, or watch your webhook — `data.reference` is the recipient reference, plus `batchReference`, `batchId` and `row`.

### Statuses
Batch: `queued` → `processing` → `completed`, or `cancelled`. Recipient: `queued`, `processing`, `delivered`, `pending`, `failed` (not charged), `reversed` (refunded), `cancelled` (skipped).

### Response formats
**Success Response**
**HTTP Status:** `200 OK` (or `201 Created`)

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

### Error Response
**HTTP Status:** `4xx`


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


---

Source: https://docs.paybeta.ng/buy-bulk-airtime-bulk-airtime

# Bulk airtime

`POST https://api.paybeta.ng/v2/bulk-airtime`

Authentication: `P-API-KEY` header.

Queue airtime for every recipient in the list. Saves `batch_id` / `reference` for the other requests.

| Field | Required | Notes |
|---|---|---|
| reference | yes | your id for the whole request, unique per account |
| description | no | your label, max 100 chars |
| recipients | yes | 1 – 1,000 items |
| recipients[].biller | yes | `mtn` · `glo` · `airtel` · `9mobile` |
| recipients[].phone_number | yes | `2348031234567` (or `08031234567`) |
| recipients[].amount | yes | NGN50 – NGN20,000 |
| recipients[].reference | no | your id for this number; default `<reference>-<row>` |

## Body

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `reference` | string | yes |  |
| `description` | string | yes |  |
| `recipients` | array | yes |  |
| `recipients[].biller` | string | yes |  |
| `recipients[].phone_number` | string | yes |  |
| `recipients[].amount` | integer | yes |  |
| `recipients[].reference` | string | no |  |

## Request: Request body

```json
{
    "reference": "PAYROLL-{{$timestamp}}",
    "description": "October staff airtime",
    "recipients": [
        {
            "biller": "mtn",
            "phone_number": "2348031234567",
            "amount": 1000,
            "reference": "STAFF-{{$timestamp}}-ADA"
        },
        {
            "biller": "glo",
            "phone_number": "2348051234567",
            "amount": 500
        },
        {
            "biller": "airtel",
            "phone_number": "08021234567",
            "amount": 200
        }
    ]
}
```

## Response 201: Success

```json
{
    "status": "successful",
    "message": "Bulk airtime queued. 3 recipient(s) will be processed shortly.",
    "data": {
        "reference": "PAYROLL-OCT",
        "batch_id": "BLK-K3P9XQ2M7Z1A",
        "description": "October staff airtime",
        "status": "queued",
        "total_recipients": 3,
        "total_amount": 1700,
        "total_charge": 1644,
        "amount_charged": 0,
        "summary": {
            "successful": 0,
            "pending": 0,
            "failed": 0,
            "queued": 3,
            "cancelled": 0
        },
        "created_at": "2026-10-05T09:00:00+01:00",
        "started_at": null,
        "completed_at": null,
        "cancelled_at": null,
        "recipients": [
            {
                "row": 1,
                "reference": "STAFF-OCT-ADA",
                "biller": "mtn",
                "phone_number": "08031234567",
                "amount": 1000,
                "charged_amount": null,
                "status": "queued",
                "response_description": null,
                "transaction_id": null,
                "processed_at": null
            },
            {
                "row": 2,
                "reference": "PAYROLL-OCT-2",
                "biller": "glo",
                "phone_number": "08051234567",
                "amount": 500,
                "charged_amount": null,
                "status": "queued",
                "response_description": null,
                "transaction_id": null,
                "processed_at": null
            },
            {
                "row": 3,
                "reference": "PAYROLL-OCT-3",
                "biller": "airtel",
                "phone_number": "08021234567",
                "amount": 200,
                "charged_amount": null,
                "status": "queued",
                "response_description": null,
                "transaction_id": null,
                "processed_at": null
            }
        ]
    }
}
```

## Response 422: Error

```json
{
    "status": "failed",
    "message": "Recipient 3 phone_number must be 234 followed by 10 digits (or 0 followed by 10 digits).",
    "errors": {
        "recipients.2.phone_number": [
            "Recipient 3 phone_number must be 234 followed by 10 digits (or 0 followed by 10 digits)."
        ]
    }
}
```


---

Source: https://docs.paybeta.ng/buy-bulk-airtime-list-bulk-requests

# List bulk requests

`GET https://api.paybeta.ng/v2/bulk-airtime`

Authentication: `P-API-KEY` header.

Your bulk airtime requests, newest first (without the per-recipient list).

## Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | string | no | queued, processing, completed, cancelled |
| `reference` | string | no | your request reference |
| `per_page` | string | yes | max 50 |
| `page` | string | yes |  |

## Response 200: Success

```json
{
    "status": "successful",
    "message": "Bulk airtime requests retrieved successfully",
    "data": [
        {
            "reference": "PAYROLL-OCT",
            "batch_id": "BLK-K3P9XQ2M7Z1A",
            "description": "October staff airtime",
            "status": "completed",
            "total_recipients": 3,
            "total_amount": 1700,
            "total_charge": 1644,
            "amount_charged": 1450,
            "summary": {
                "successful": 1,
                "pending": 1,
                "failed": 1,
                "queued": 0,
                "cancelled": 0
            },
            "created_at": "2026-10-05T09:00:00+01:00",
            "started_at": "2026-10-05T09:00:02+01:00",
            "completed_at": "2026-10-05T09:00:14+01:00",
            "cancelled_at": null
        }
    ],
    "meta": {
        "current_page": 1,
        "last_page": 1,
        "per_page": 20,
        "total": 1
    }
}
```


---

Source: https://docs.paybeta.ng/buy-bulk-airtime-get-bulk-request

# Get bulk request

`GET https://api.paybeta.ng/v2/bulk-airtime/batchId`

Authentication: `P-API-KEY` header.

One request with the result for every recipient. The URL accepts the `batch_id` (BLK-…) or your `reference`.

## Response 200: Success

```json
{
    "status": "successful",
    "message": "Bulk airtime request retrieved successfully",
    "data": {
        "reference": "PAYROLL-OCT",
        "batch_id": "BLK-K3P9XQ2M7Z1A",
        "description": "October staff airtime",
        "status": "completed",
        "total_recipients": 3,
        "total_amount": 1700,
        "total_charge": 1644,
        "amount_charged": 1450,
        "summary": {
            "successful": 1,
            "pending": 1,
            "failed": 1,
            "queued": 0,
            "cancelled": 0
        },
        "created_at": "2026-10-05T09:00:00+01:00",
        "started_at": "2026-10-05T09:00:02+01:00",
        "completed_at": "2026-10-05T09:00:14+01:00",
        "cancelled_at": null,
        "recipients": [
            {
                "row": 1,
                "reference": "STAFF-OCT-ADA",
                "biller": "mtn",
                "phone_number": "08031234567",
                "amount": 1000,
                "charged_amount": 970,
                "status": "delivered",
                "response_description": "TRANSACTION SUCCESSFUL",
                "transaction_id": "API-17619840121234567",
                "processed_at": "2026-10-05T09:00:12+01:00"
            },
            {
                "row": 2,
                "reference": "PAYROLL-OCT-2",
                "biller": "glo",
                "phone_number": "08051234567",
                "amount": 500,
                "charged_amount": 480,
                "status": "pending",
                "response_description": "TRANSACTION PENDING",
                "transaction_id": "API-17619840171234567",
                "processed_at": "2026-10-05T09:00:12+01:00"
            },
            {
                "row": 3,
                "reference": "PAYROLL-OCT-3",
                "biller": "airtel",
                "phone_number": "08021234567",
                "amount": 200,
                "charged_amount": 194,
                "status": "failed",
                "response_description": "Insufficient wallet balance. NGN194.00 was required but your balance was NGN50.00.",
                "transaction_id": "API-17619840221234567",
                "processed_at": "2026-10-05T09:00:12+01:00"
            }
        ]
    }
}
```

## Response 404: Error

```json
{
    "status": "failed",
    "message": "Bulk airtime request not found.",
    "data": null
}
```


---

Source: https://docs.paybeta.ng/buy-bulk-airtime-download-report-csv

# Download report (CSV)

`GET https://api.paybeta.ng/v2/bulk-airtime/batchId/report`

Authentication: `P-API-KEY` header.

Per-recipient results as CSV: row, reference, biller, phone_number, amount, charged_amount, status, transaction_id, description, processed_at.


---

Source: https://docs.paybeta.ng/buy-bulk-airtime-cancel

# Cancel

`POST https://api.paybeta.ng/v2/bulk-airtime/batchId/cancel`

Authentication: `P-API-KEY` header.

Stop recipients that have not started yet (they become `cancelled`, not charged). Numbers already processed are not affected.

## Response 200: Success

```json
{
    "status": "successful",
    "message": "Bulk request cancelled. 2 recipient(s) that had not started were skipped.",
    "data": {
        "reference": "PAYROLL-OCT",
        "batch_id": "BLK-K3P9XQ2M7Z1A",
        "description": "October staff airtime",
        "status": "cancelled",
        "total_recipients": 3,
        "total_amount": 1700,
        "total_charge": 1644,
        "amount_charged": 970,
        "summary": {
            "successful": 1,
            "pending": 0,
            "failed": 0,
            "queued": 0,
            "cancelled": 2
        },
        "created_at": "2026-10-05T09:00:00+01:00",
        "started_at": null,
        "completed_at": null,
        "cancelled_at": "2026-10-05T09:00:06+01:00",
        "recipients": [
            {
                "row": 1,
                "reference": "STAFF-OCT-ADA",
                "biller": "mtn",
                "phone_number": "08031234567",
                "amount": 1000,
                "charged_amount": 970,
                "status": "delivered",
                "response_description": "TRANSACTION SUCCESSFUL",
                "transaction_id": "API-17619840121234567",
                "processed_at": "2026-10-05T09:00:12+01:00"
            },
            {
                "row": 2,
                "reference": "PAYROLL-OCT-2",
                "biller": "glo",
                "phone_number": "08051234567",
                "amount": 500,
                "charged_amount": null,
                "status": "cancelled",
                "response_description": "Cancelled by merchant before processing.",
                "transaction_id": null,
                "processed_at": null
            },
            {
                "row": 3,
                "reference": "PAYROLL-OCT-3",
                "biller": "airtel",
                "phone_number": "08021234567",
                "amount": 200,
                "charged_amount": null,
                "status": "cancelled",
                "response_description": "Cancelled by merchant before processing.",
                "transaction_id": null,
                "processed_at": null
            }
        ]
    }
}
```

## Response 422: Error

```json
{
    "status": "failed",
    "message": "This bulk request has already finished.",
    "data": null
}
```


---

Source: https://docs.paybeta.ng/buy-bulk-airtime-query-one-number

# Query one number

`POST https://api.paybeta.ng/v2/transaction/query`

Authentication: `P-API-KEY` header.

Status of one recipient, with its reference (default `<reference>-<row>`).

## Body

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `reference` | string | yes |  |

## Request: Request body

```json
{
    "reference": "{{batchReference}}-2"
}
```

## Response 200: Success

```json
{
    "status": "successful",
    "message": "Your glo airtime payment is successful",
    "code": "00",
    "data": {
        "paymentStatus": "Delivered",
        "reference": "PAYROLL-OCT-2",
        "amount": 500,
        "amountPaid": 480,
        "product": "Glo Airtime",
        "customerId": "08051234567",
        "token": "0",
        "unit": null,
        "transactionId": "API-17619840171234567",
        "transactionDate": "2026-10-05T08:00:12.000000Z"
    }
}
```


---

Source: https://docs.paybeta.ng/schedule-payments

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


---

Source: https://docs.paybeta.ng/schedule-payments-options

# Options

`GET https://api.paybeta.ng/v2/scheduled-payments/options`

Services, billers, frequencies and meter types accepted by **Create**, plus `min_lead_minutes` and the timezone used for dates.

## Response 200: Success

```json
{
    "success": true,
    "data": {
        "services": [
            {
                "key": "airtime",
                "label": "Airtime",
                "billers": [
                    {
                        "biller": "mtn_vtu",
                        "name": "MTN Airtime",
                        "has_bundles": false
                    }
                ]
            },
            {
                "key": "data",
                "label": "Internet Data",
                "billers": [
                    {
                        "biller": "mtn_data",
                        "name": "MTN Data",
                        "has_bundles": true
                    }
                ]
            },
            {
                "key": "cabletv",
                "label": "Cable TV",
                "billers": [
                    {
                        "biller": "dstv",
                        "name": "DStv",
                        "has_bundles": true
                    }
                ]
            },
            {
                "key": "electricity",
                "label": "Electricity",
                "billers": [
                    {
                        "biller": "ikeja-electric",
                        "name": "Ikeja Electric - IKEDC",
                        "has_bundles": false
                    }
                ]
            }
        ],
        "frequencies": [
            {
                "key": "once",
                "label": "One time"
            },
            {
                "key": "daily",
                "label": "Daily"
            },
            {
                "key": "weekly",
                "label": "Weekly"
            },
            {
                "key": "monthly",
                "label": "Monthly"
            }
        ],
        "meter_types": [
            {
                "key": "prepaid",
                "label": "Prepaid Meter"
            },
            {
                "key": "postpaid",
                "label": "Postpaid Meter"
            }
        ],
        "min_lead_minutes": 10,
        "timezone": "Africa/Lagos"
    }
}
```


---

Source: https://docs.paybeta.ng/schedule-payments-bundles

# Bundles

`GET https://api.paybeta.ng/v2/scheduled-payments/options`

Authentication: `P-API-KEY` header.

Services, billers, frequencies and meter types accepted by **Create**, plus `min_lead_minutes` and the timezone used for dates.

## Response 200: Success

```json
{
    "success": true,
    "data": {
        "services": [
            {
                "key": "airtime",
                "label": "Airtime",
                "billers": [
                    {
                        "biller": "mtn_vtu",
                        "name": "MTN Airtime",
                        "has_bundles": false
                    }
                ]
            },
            {
                "key": "data",
                "label": "Internet Data",
                "billers": [
                    {
                        "biller": "mtn_data",
                        "name": "MTN Data",
                        "has_bundles": true
                    }
                ]
            },
            {
                "key": "cabletv",
                "label": "Cable TV",
                "billers": [
                    {
                        "biller": "dstv",
                        "name": "DStv",
                        "has_bundles": true
                    }
                ]
            },
            {
                "key": "electricity",
                "label": "Electricity",
                "billers": [
                    {
                        "biller": "ikeja-electric",
                        "name": "Ikeja Electric - IKEDC",
                        "has_bundles": false
                    }
                ]
            }
        ],
        "frequencies": [
            {
                "key": "once",
                "label": "One time"
            },
            {
                "key": "daily",
                "label": "Daily"
            },
            {
                "key": "weekly",
                "label": "Weekly"
            },
            {
                "key": "monthly",
                "label": "Monthly"
            }
        ],
        "meter_types": [
            {
                "key": "prepaid",
                "label": "Prepaid Meter"
            },
            {
                "key": "postpaid",
                "label": "Postpaid Meter"
            }
        ],
        "min_lead_minutes": 10,
        "timezone": "Africa/Lagos"
    }
}
```


---

Source: https://docs.paybeta.ng/create

# Create

> **Body**

| Field | Required | Notes |
|---|---|---|
| service | yes | `airtime` · `data` · `cabletv` · `electricity` |
| biller | yes | from **Options** |
| customer_id | yes | phone number, smartcard number or meter number |
| code | data / cabletv / electricity | bundle code, or meter type for electricity |
| amount | airtime / electricity | ignored for data & cable TV (bundle price is used) |
| frequency | yes | `once` · `daily` · `weekly` · `monthly` |
| start_at | yes | first run, ≥ 10 minutes from now |
| ends_at | no | recurring only |
| description | no | your label, max 100 chars |

Each request in this folder saves the new schedule's reference to `scheduleReference`.

**Body**

| Field | Required | Notes |
|---|---|---|
| service | yes | `airtime` · `data` · `cabletv` · `electricity` |
| biller | yes | from **Options** |
| customer_id | yes | phone number, smartcard number or meter number |
| code | data / cabletv / electricity | bundle code, or meter type for electricity |
| amount | airtime / electricity | ignored for data & cable TV (bundle price is used) |
| frequency | yes | `once` · `daily` · `weekly` · `monthly` |
| start_at | yes | first run, ≥ 10 minutes from now |
| ends_at | no | recurring only |
| description | no | your label, max 100 chars |

Each request in this folder saves the new schedule's reference to `scheduleReference`.


---

Source: https://docs.paybeta.ng/schedule-payments-create-airtime-one-time

# Create - Airtime (one time)

`POST https://api.paybeta.ng/v2/scheduled-payments`

Authentication: `P-API-KEY` header.

Schedule a one-time airtime top-up. `amount` is required (50 - 20,000).

## Body

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `service` | string | yes |  |
| `biller` | string | yes |  |
| `customer_id` | string | yes |  |
| `amount` | integer | yes |  |
| `frequency` | string | yes |  |
| `start_at` | string | yes |  |
| `description` | string | yes |  |

## Request: Request body

```json
{
    "service": "airtime",
    "biller": "mtn_vtu",
    "customer_id": "08031234567",
    "amount": 500,
    "frequency": "once",
    "start_at": "{{startAt}}",
    "description": "Airtime for Dad"
}
```

## Response 201: Success

```json
{
    "success": true,
    "message": "Payment scheduled successfully.",
    "data": {
        "reference": "SCH-7F3K9QX2AB12",
        "service": "airtime",
        "service_label": "Airtime",
        "biller": "mtn_vtu",
        "biller_label": "MTN Airtime",
        "biller_code": null,
        "product_name": "MTN Airtime VTU",
        "customer_id": "08031234567",
        "customer_name": null,
        "amount": 500,
        "frequency": "once",
        "frequency_label": "One time",
        "starts_at": "2026-10-10T09:00:00+01:00",
        "ends_at": null,
        "next_run_at": "2026-10-10T09:00:00+01:00",
        "status": "active",
        "failure_reason": null,
        "can_retry": false,
        "can_cancel": true,
        "can_pause": true,
        "can_pay_now": true,
        "can_resume": false,
        "resume_needs_start_at": false,
        "paused_at": null,
        "can_edit": true,
        "archived": false,
        "can_reactivate": false,
        "can_delete": false,
        "reactivation_needs_start_at": false,
        "cancelled_at": null,
        "total_runs": 0,
        "last_run_at": null,
        "last_run": null,
        "description": "Airtime for Dad",
        "summary": "Airtime scheduled for the beneficiary 08031234567",
        "created_at": "2026-10-05T12:00:00+01:00"
    }
}
```


---

Source: https://docs.paybeta.ng/schedule-payments-create-data-monthly

# Create - Data (monthly)

`POST https://api.paybeta.ng/v2/scheduled-payments`

Authentication: `P-API-KEY` header.

Schedule a recurring data bundle. `code` is the bundle code from **Bundles**; the amount comes from the bundle price. `ends_at` is optional.

## Body

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `service` | string | yes |  |
| `biller` | string | yes |  |
| `customer_id` | string | yes |  |
| `code` | string | yes |  |
| `frequency` | string | yes |  |
| `start_at` | string | yes |  |
| `ends_at` | string | yes |  |
| `description` | string | yes |  |

## Request: Request body

```json
{
    "service": "data",
    "biller": "mtn_data",
    "customer_id": "08031234567",
    "code": "mtn-1gb-30days",
    "frequency": "monthly",
    "start_at": "{{startAt}}",
    "ends_at": "{{endsAt}}",
    "description": "Data for Mum"
}
```

## Response 201: Success

```json
{
    "success": true,
    "message": "Payment scheduled successfully.",
    "data": {
        "reference": "SCH-7F3K9QX2AB12",
        "service": "data",
        "service_label": "Internet Data",
        "biller": "mtn_data",
        "biller_label": "MTN Data",
        "biller_code": "mtn-1gb-30days",
        "product_name": "MTN 1GB - 30 Days",
        "customer_id": "08031234567",
        "customer_name": null,
        "amount": 1000,
        "frequency": "monthly",
        "frequency_label": "Monthly",
        "starts_at": "2026-11-01T09:00:00+01:00",
        "ends_at": null,
        "next_run_at": "2026-11-01T09:00:00+01:00",
        "status": "active",
        "failure_reason": null,
        "can_retry": false,
        "can_cancel": true,
        "can_pause": true,
        "can_pay_now": true,
        "can_resume": false,
        "resume_needs_start_at": false,
        "paused_at": null,
        "can_edit": true,
        "archived": false,
        "can_reactivate": false,
        "can_delete": false,
        "reactivation_needs_start_at": false,
        "cancelled_at": null,
        "total_runs": 0,
        "last_run_at": null,
        "last_run": null,
        "description": "Data for Mum",
        "summary": "Internet Data scheduled for the beneficiary 08031234567",
        "created_at": "2026-10-05T12:00:00+01:00"
    }
}
```

## Response 422: Error

```json
{
    "success": false,
    "message": "The schedule date must be at least 10 minutes from now.",
    "errors": {
        "start_at": [
            "The schedule date must be at least 10 minutes from now."
        ]
    }
}
```


---

Source: https://docs.paybeta.ng/schedule-payments-create-cable-tv-monthly

# Create - Cable TV (monthly)

`POST https://api.paybeta.ng/v2/scheduled-payments`

Authentication: `P-API-KEY` header.

Schedule a recurring TV subscription. `customer_id` is the smartcard number and is validated with the provider. `code` is the bouquet code from **Bundles**. Bouquet must be ₦500 - ₦80,000.

## Body

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `service` | string | yes |  |
| `biller` | string | yes |  |
| `customer_id` | string | yes |  |
| `code` | string | yes |  |
| `frequency` | string | yes |  |
| `start_at` | string | yes |  |

## Request: Request body

```json
{
    "service": "cabletv",
    "biller": "dstv",
    "customer_id": "7027914329",
    "code": "dstv-padi",
    "frequency": "monthly",
    "start_at": "{{startAt}}"
}
```


---

Source: https://docs.paybeta.ng/schedule-payments-create-electricity-weekly

# Create - Electricity (weekly)

`POST https://api.paybeta.ng/v2/scheduled-payments`

Authentication: `P-API-KEY` header.

Schedule recurring electricity tokens. `customer_id` is the meter number (validated with the provider), `code` is the meter type (`prepaid` | `postpaid`). `amount` is ₦1,000 - ₦50,000 and must meet the meter's minimum vend.

## Body

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `service` | string | yes |  |
| `biller` | string | yes |  |
| `customer_id` | string | yes |  |
| `code` | string | yes |  |
| `amount` | integer | yes |  |
| `frequency` | string | yes |  |
| `start_at` | string | yes |  |

## Request: Request body

```json
{
    "service": "electricity",
    "biller": "ikeja-electric",
    "customer_id": "45067198783",
    "code": "prepaid",
    "amount": 5000,
    "frequency": "weekly",
    "start_at": "{{startAt}}"
}
```


---

Source: https://docs.paybeta.ng/schedule-payments-list-schedules

# List schedules

`GET https://api.paybeta.ng/v2/scheduled-payments`

Authentication: `P-API-KEY` header.

Paginated list, newest first. Without `status`, cancelled (archived) schedules are hidden.

## Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | string | no | active, processing, completed, failed, paused, cancelled (or archived) |
| `per_page` | string | yes | max 50 |
| `page` | string | yes |  |

## Response 200: Success

```json
{
    "status": "successful",
    "message": "Scheduled payments retrieved successfully",
    "data": [
        {
            "reference": "SCH-7F3K9QX2AB12",
            "service": "data",
            "service_label": "Internet Data",
            "biller": "mtn_data",
            "biller_label": "MTN Data",
            "biller_code": "mtn-1gb-30days",
            "product_name": "MTN 1GB - 30 Days",
            "customer_id": "08031234567",
            "customer_name": null,
            "amount": 1000,
            "frequency": "monthly",
            "frequency_label": "Monthly",
            "starts_at": "2026-11-01T09:00:00+01:00",
            "ends_at": null,
            "next_run_at": "2026-11-01T09:00:00+01:00",
            "status": "active",
            "failure_reason": null,
            "can_retry": false,
            "can_cancel": true,
            "can_pause": true,
            "can_pay_now": true,
            "can_resume": false,
            "resume_needs_start_at": false,
            "paused_at": null,
            "can_edit": true,
            "archived": false,
            "can_reactivate": false,
            "can_delete": false,
            "reactivation_needs_start_at": false,
            "cancelled_at": null,
            "total_runs": 0,
            "last_run_at": null,
            "last_run": null,
            "description": "Data for Mum",
            "summary": "Internet Data scheduled for the beneficiary 08031234567",
            "created_at": "2026-10-05T12:00:00+01:00"
        }
    ],
    "meta": {
        "current_page": 1,
        "last_page": 1,
        "per_page": 20,
        "total": 1
    }
}
```


---

Source: https://docs.paybeta.ng/schedule-payments-get-schedule

# Get schedule

`GET https://api.paybeta.ng/v2/scheduled-payments/{schedulereference}`

Authentication: `P-API-KEY` header.

One schedule including its full run history (`runs`).

## Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `schedulereference` | string | yes |  |

## Response 200: Success

```json
{
    "status": "successful",
    "data": {
        "reference": null,
        "schedule_id": "SCH-9SC5QIH5GNLC",
        "service": "airtime",
        "service_label": "Airtime",
        "biller": "mtn_vtu",
        "biller_label": "MTN Airtime",
        "biller_code": null,
        "product_name": "MTN Airtime VTU",
        "customer_id": "08123456780",
        "customer_name": null,
        "amount": 100,
        "frequency": "once",
        "frequency_label": "One time",
        "starts_at": "2026-10-05T03:40:00+01:00",
        "ends_at": null,
        "next_run_at": null,
        "status": "completed",
        "failure_reason": null,
        "can_retry": false,
        "can_cancel": false,
        "can_pause": false,
        "can_pay_now": false,
        "can_resume": false,
        "resume_needs_start_at": false,
        "paused_at": null,
        "can_edit": false,
        "archived": false,
        "can_reactivate": false,
        "can_delete": false,
        "reactivation_needs_start_at": false,
        "cancelled_at": null,
        "total_runs": 1,
        "last_run_at": "2026-10-05T03:40:47+01:00",
        "last_run": {
            "cycle": 1,
            "attempt": 1,
            "trigger": "auto",
            "due_at": "2026-10-05T03:40:00+01:00",
            "status": "delivered",
            "response_description": "TRANSACTION SUCCESSFUL",
            "transaction_id": "API-1791168046493950345",
            "transaction_reference": "SCH-9SC5QIH5GNLC-B9AP46D6",
            "amount": 100,
            "charged_amount": 97,
            "token": null,
            "started_at": "2026-10-05T03:40:44+01:00",
            "finished_at": "2026-10-05T03:40:47+01:00"
        },
        "description": "Airtime for Dad",
        "summary": "Airtime scheduled for the beneficiary 08138539550",
        "created_at": "2026-10-05T03:25:41+01:00",
        "runs": [
            {
                "cycle": 1,
                "attempt": 1,
                "trigger": "auto",
                "due_at": "2026-10-05T03:40:00+01:00",
                "status": "delivered",
                "response_description": "TRANSACTION SUCCESSFUL",
                "transaction_id": "API-1791168046493950345",
                "transaction_reference": "SCH-9SC5QIH5GNLC-B9AP46D6",
                "amount": 100,
                "charged_amount": 97,
                "token": null,
                "started_at": "2026-10-05T03:40:44+01:00",
                "finished_at": "2026-10-05T03:40:47+01:00"
            }
        ]
    }
}
```

## Response 404: Error

```json
{
    "success": false,
    "message": "Schedule not found."
}
```


---

Source: https://docs.paybeta.ng/schedule-payments-update-schedule

# Update schedule

`PUT https://api.paybeta.ng/v2/scheduled-payments/{scheduleReference}`

Authentication: `P-API-KEY` header.

Edit a schedule before its first run (`can_edit: true`). Same body and rules as **Create**; the schedule restarts from the new `start_at`.

## Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `scheduleReference` | string | yes |  |

## Body

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `service` | string | yes |  |
| `biller` | string | yes |  |
| `customer_id` | string | yes |  |
| `code` | string | yes |  |
| `frequency` | string | yes |  |
| `start_at` | string | yes |  |

## Request: Request body

```json
{
    "service": "data",
    "biller": "mtn_data",
    "customer_id": "08031234567",
    "code": "mtn-2gb-30days",
    "frequency": "monthly",
    "start_at": "{{startAt}}"
}
```

## Response 200: Success

```json
{
    "success": true,
    "message": "Schedule updated successfully.",
    "data": {
        "reference": "SCH-7F3K9QX2AB12",
        "service": "data",
        "service_label": "Internet Data",
        "biller": "mtn_data",
        "biller_label": "MTN Data",
        "biller_code": "mtn-1gb-30days",
        "product_name": "MTN 1GB - 30 Days",
        "customer_id": "08031234567",
        "customer_name": null,
        "amount": 1000,
        "frequency": "monthly",
        "frequency_label": "Monthly",
        "starts_at": "2026-11-01T09:00:00+01:00",
        "ends_at": null,
        "next_run_at": "2026-11-01T09:00:00+01:00",
        "status": "active",
        "failure_reason": null,
        "can_retry": false,
        "can_cancel": true,
        "can_pause": true,
        "can_pay_now": true,
        "can_resume": false,
        "resume_needs_start_at": false,
        "paused_at": null,
        "can_edit": true,
        "archived": false,
        "can_reactivate": false,
        "can_delete": false,
        "reactivation_needs_start_at": false,
        "cancelled_at": null,
        "total_runs": 0,
        "last_run_at": null,
        "last_run": null,
        "description": "Data for Mum",
        "summary": "Internet Data scheduled for the beneficiary 08031234567",
        "created_at": "2026-10-05T12:00:00+01:00"
    }
}
```

## Response 404: Error

```json
{
    "success": false,
    "message": "Schedule not found."
}
```

## Response 422: Error

```json
{
    "success": false,
    "message": "This schedule can no longer be edited — it has already started running.",
    "errors": {
        "schedule": [
            "This schedule can no longer be edited — it has already started running."
        ]
    }
}
```


---

Source: https://docs.paybeta.ng/schedule-payments-pay-now

# Pay now

`POST https://api.paybeta.ng/v2/scheduled-payments/scheduleReference/pay-now`

Authentication: `P-API-KEY` header.

Charge this schedule's payment immediately, on top of its normal plan. The schedule's dates, status and cycle are unchanged. Works on `active` and `paused` schedules (use **Retry** for `failed`). The result arrives on your webhook.

## Response 200: Success

```json
{
    "success": true,
    "message": "Payment started. Your schedule dates are unchanged. Check the schedule shortly for the result.",
    "data": {
        "reference": "SCH-7F3K9QX2AB12",
        "service": "data",
        "service_label": "Internet Data",
        "biller": "mtn_data",
        "biller_label": "MTN Data",
        "biller_code": "mtn-1gb-30days",
        "product_name": "MTN 1GB - 30 Days",
        "customer_id": "08031234567",
        "customer_name": null,
        "amount": 1000,
        "frequency": "monthly",
        "frequency_label": "Monthly",
        "starts_at": "2026-11-01T09:00:00+01:00",
        "ends_at": null,
        "next_run_at": "2026-11-01T09:00:00+01:00",
        "status": "active",
        "failure_reason": null,
        "can_retry": false,
        "can_cancel": true,
        "can_pause": true,
        "can_pay_now": true,
        "can_resume": false,
        "resume_needs_start_at": false,
        "paused_at": null,
        "can_edit": true,
        "archived": false,
        "can_reactivate": false,
        "can_delete": false,
        "reactivation_needs_start_at": false,
        "cancelled_at": null,
        "total_runs": 0,
        "last_run_at": null,
        "last_run": null,
        "description": "Data for Mum",
        "summary": "Internet Data scheduled for the beneficiary 08031234567",
        "created_at": "2026-10-05T12:00:00+01:00"
    }
}
```

## Response 422: Error

```json
{
    "success": false,
    "message": "A payment for this schedule is already processing. Please wait a moment.",
    "errors": {
        "schedule": [
            "A payment for this schedule is already processing. Please wait a moment."
        ]
    }
}
```


---

Source: https://docs.paybeta.ng/schedule-payments-retry-failed-run

# Retry failed run

`POST https://api.paybeta.ng/v2/scheduled-payments/scheduleReference/retry`

Authentication: `P-API-KEY` header.

Re-run a `failed` schedule now (e.g. after funding your wallet). On success a recurring schedule moves on to its next future date.

## Response 200: Success

```json
{
    "success": true,
    "message": "Retry started. Check the schedule shortly for the result.",
    "data": {
        "reference": "SCH-7F3K9QX2AB12",
        "service": "data",
        "service_label": "Internet Data",
        "biller": "mtn_data",
        "biller_label": "MTN Data",
        "biller_code": "mtn-1gb-30days",
        "product_name": "MTN 1GB - 30 Days",
        "customer_id": "08031234567",
        "customer_name": null,
        "amount": 1000,
        "frequency": "monthly",
        "frequency_label": "Monthly",
        "starts_at": "2026-11-01T09:00:00+01:00",
        "ends_at": null,
        "next_run_at": "2026-11-01T09:00:00+01:00",
        "status": "processing",
        "failure_reason": null,
        "can_retry": false,
        "can_cancel": true,
        "can_pause": true,
        "can_pay_now": true,
        "can_resume": false,
        "resume_needs_start_at": false,
        "paused_at": null,
        "can_edit": true,
        "archived": false,
        "can_reactivate": false,
        "can_delete": false,
        "reactivation_needs_start_at": false,
        "cancelled_at": null,
        "total_runs": 0,
        "last_run_at": null,
        "last_run": null,
        "description": "Data for Mum",
        "summary": "Internet Data scheduled for the beneficiary 08031234567",
        "created_at": "2026-10-05T12:00:00+01:00"
    }
}
```

## Response 422: Error

```json
{
    "success": false,
    "message": "Only failed schedules can be retried.",
    "errors": {
        "schedule": [
            "Only failed schedules can be retried."
        ]
    }
}
```


---

Source: https://docs.paybeta.ng/schedule-payments-pause

# Pause

`POST https://api.paybeta.ng/v2/scheduled-payments/scheduleReference/pause`

Authentication: `P-API-KEY` header.

Put a schedule on hold. Nothing is charged until it is resumed.

## Response 200: Success

```json
{
    "success": true,
    "message": "Schedule paused. No payments will be made until you resume it.",
    "data": {
        "reference": "SCH-7F3K9QX2AB12",
        "service": "data",
        "service_label": "Internet Data",
        "biller": "mtn_data",
        "biller_label": "MTN Data",
        "biller_code": "mtn-1gb-30days",
        "product_name": "MTN 1GB - 30 Days",
        "customer_id": "08031234567",
        "customer_name": null,
        "amount": 1000,
        "frequency": "monthly",
        "frequency_label": "Monthly",
        "starts_at": "2026-11-01T09:00:00+01:00",
        "ends_at": null,
        "next_run_at": null,
        "status": "paused",
        "failure_reason": null,
        "can_retry": false,
        "can_cancel": true,
        "can_pause": false,
        "can_pay_now": true,
        "can_resume": true,
        "resume_needs_start_at": false,
        "paused_at": "2026-10-05T12:30:00+01:00",
        "can_edit": true,
        "archived": false,
        "can_reactivate": false,
        "can_delete": false,
        "reactivation_needs_start_at": false,
        "cancelled_at": null,
        "total_runs": 0,
        "last_run_at": null,
        "last_run": null,
        "description": "Data for Mum",
        "summary": "Internet Data scheduled for the beneficiary 08031234567",
        "created_at": "2026-10-05T12:00:00+01:00"
    }
}
```


---

Source: https://docs.paybeta.ng/schedule-payments-resume

# Resume

`POST https://api.paybeta.ng/v2/scheduled-payments/scheduleReference/resume`

Authentication: `P-API-KEY` header.

Resume a `paused` schedule. Recurring schedules continue at the next future cycle — cycles missed while paused are skipped, never charged. For a one-time schedule whose date passed while paused (`resume_needs_start_at: true`), send a new `start_at`.

## Body

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `start_at` | string | yes |  |

## Request: Request body

```json
{
    "start_at": "{{startAt}}"
}
```

## Response 200: Success

```json
{
    "success": true,
    "message": "Schedule resumed.",
    "data": {
        "reference": "SCH-7F3K9QX2AB12",
        "service": "data",
        "service_label": "Internet Data",
        "biller": "mtn_data",
        "biller_label": "MTN Data",
        "biller_code": "mtn-1gb-30days",
        "product_name": "MTN 1GB - 30 Days",
        "customer_id": "08031234567",
        "customer_name": null,
        "amount": 1000,
        "frequency": "monthly",
        "frequency_label": "Monthly",
        "starts_at": "2026-11-01T09:00:00+01:00",
        "ends_at": null,
        "next_run_at": "2026-11-01T09:00:00+01:00",
        "status": "active",
        "failure_reason": null,
        "can_retry": false,
        "can_cancel": true,
        "can_pause": true,
        "can_pay_now": true,
        "can_resume": false,
        "resume_needs_start_at": false,
        "paused_at": null,
        "can_edit": true,
        "archived": false,
        "can_reactivate": false,
        "can_delete": false,
        "reactivation_needs_start_at": false,
        "cancelled_at": null,
        "total_runs": 0,
        "last_run_at": null,
        "last_run": null,
        "description": "Data for Mum",
        "summary": "Internet Data scheduled for the beneficiary 08031234567",
        "created_at": "2026-10-05T12:00:00+01:00"
    }
}
```


---

Source: https://docs.paybeta.ng/schedule-payments-cancel-archive

# Cancel (archive)

`POST https://api.paybeta.ng/v2/scheduled-payments/scheduleReference/cancel`

Authentication: `P-API-KEY` header.

Stop an `active`, `failed` or `paused` schedule and move it to the archive (`status: cancelled`). It can be re-enabled later.

## Response 200: Success

```json
{
    "success": true,
    "message": "Schedule cancelled and moved to archive.",
    "data": {
        "reference": "SCH-7F3K9QX2AB12",
        "service": "data",
        "service_label": "Internet Data",
        "biller": "mtn_data",
        "biller_label": "MTN Data",
        "biller_code": "mtn-1gb-30days",
        "product_name": "MTN 1GB - 30 Days",
        "customer_id": "08031234567",
        "customer_name": null,
        "amount": 1000,
        "frequency": "monthly",
        "frequency_label": "Monthly",
        "starts_at": "2026-11-01T09:00:00+01:00",
        "ends_at": null,
        "next_run_at": null,
        "status": "cancelled",
        "failure_reason": null,
        "can_retry": false,
        "can_cancel": true,
        "can_pause": true,
        "can_pay_now": true,
        "can_resume": false,
        "resume_needs_start_at": false,
        "paused_at": null,
        "can_edit": true,
        "archived": true,
        "can_reactivate": true,
        "can_delete": true,
        "reactivation_needs_start_at": false,
        "cancelled_at": "2026-10-05T12:30:00+01:00",
        "total_runs": 0,
        "last_run_at": null,
        "last_run": null,
        "description": "Data for Mum",
        "summary": "Internet Data scheduled for the beneficiary 08031234567",
        "created_at": "2026-10-05T12:00:00+01:00"
    }
}
```


---

Source: https://docs.paybeta.ng/schedule-payments-re-enable

# Re-enable

`POST https://api.paybeta.ng/v2/scheduled-payments/scheduleReference/reactivate`

Authentication: `P-API-KEY` header.

Bring a `cancelled` schedule back to `active`. Same date rules as **Resume** (`reactivation_needs_start_at`). Counts towards the 20 open schedules limit.

## Body

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `start_at` | string | yes |  |

## Request: Request body

```json
{
    "start_at": "{{startAt}}"
}
```

## Response 200: Success

```json
{
    "success": true,
    "message": "Schedule re-enabled.",
    "data": {
        "reference": "SCH-7F3K9QX2AB12",
        "service": "data",
        "service_label": "Internet Data",
        "biller": "mtn_data",
        "biller_label": "MTN Data",
        "biller_code": "mtn-1gb-30days",
        "product_name": "MTN 1GB - 30 Days",
        "customer_id": "08031234567",
        "customer_name": null,
        "amount": 1000,
        "frequency": "monthly",
        "frequency_label": "Monthly",
        "starts_at": "2026-11-01T09:00:00+01:00",
        "ends_at": null,
        "next_run_at": "2026-11-01T09:00:00+01:00",
        "status": "active",
        "failure_reason": null,
        "can_retry": false,
        "can_cancel": true,
        "can_pause": true,
        "can_pay_now": true,
        "can_resume": false,
        "resume_needs_start_at": false,
        "paused_at": null,
        "can_edit": true,
        "archived": false,
        "can_reactivate": false,
        "can_delete": false,
        "reactivation_needs_start_at": false,
        "cancelled_at": null,
        "total_runs": 0,
        "last_run_at": null,
        "last_run": null,
        "description": "Data for Mum",
        "summary": "Internet Data scheduled for the beneficiary 08031234567",
        "created_at": "2026-10-05T12:00:00+01:00"
    }
}
```


---

Source: https://docs.paybeta.ng/schedule-payments-delete

# Delete

`DELETE https://api.paybeta.ng/v2/scheduled-payments/scheduleReference`

Authentication: `P-API-KEY` header.

Permanently delete a `cancelled` schedule and its run history. Transactions it created stay in your transaction history.

## Response 200: Success

```json
{
    "success": true,
    "message": "Schedule permanently deleted."
}
```

## Response 422: Error

```json
{
    "success": false,
    "message": "Cancel this schedule first. Only archived schedules can be deleted.",
    "errors": {
        "schedule": [
            "Cancel this schedule first. Only archived schedules can be deleted."
        ]
    }
}
```


---

Source: https://docs.paybeta.ng/wallet-balance

# Balance

`GET https://api.paybeta.ng/v2/wallet/balance`

## Response 200: Success

```json
{
    "status": "successful",
    "message": "Request processed successfully.",
    "data": {
        "availableBalance": 4212.45,
        "lienAmount": 0
    }
}
```


---

Source: https://docs.paybeta.ng/checkout-overview

# Checkout API

> Accept card, bank transfer, bank account (GTBank), USSD and Paybeta wallet payments on Paybeta’s hosted payment page.

Create a payment with one API call, send your customer to the `checkout_url` it returns, and Paybeta handles the rest on its hosted payment page. You get a signed webhook when the payment completes, and you can check any payment's status at any time.

## How it works

1. **Create a payment** from your server: `POST /api/v1/payments` with the amount, your `reference` and the customer's email.
2. **Send the customer to `checkout_url`**: redirect them, or open the payment page in a popup with `new PaybetaPop().resumeTransaction(id)`.
3. **Get the webhook** at your `webhook_url` when the payment succeeds or fails.
4. **Verify the payment** (`GET /api/v1/payments/{reference}`) before you deliver.

## Base URL

| | |
| --- | --- |
| **Base URL** | `https://checkout.paybeta.ng` |
| **Test and live** | Same host. Each payment's `mode` (`test` or `live`) picks which. |
| **Currency** | Naira (`NGN`) only. Amounts are in naira, not kobo. |

## Authentication

Send your **live** Paybeta API key in the `P-API-KEY` header, from the Paybeta API console. The same live key creates test and live payments; your test keys don't work here.

```http
P-API-KEY: YOUR_LIVE_API_KEY
Content-Type: application/json
Accept: application/json
```

Your live **secret key** is only used to check webhook signatures. Keep both keys on your server, never in an app or browser.

## Responses

Every response has the same shape: `status`, `message` and `data`. On errors, `status` is `failed`, `message` is the first problem, and `data` is `null`.

```json
{
  "status": "successful",
  "message": "Payment created",
  "data": { "id": "GTW-K3J7Q2M9X4ZP8L1N5R6T0V2B3C4D", "status": "pending", "...": "..." }
}
```

| HTTP status | When |
| --- | --- |
| `201 Created` | A new payment was created. |
| `200 OK` | The payment you asked for, including a repeated create with the same `reference` and amount. |
| `400 Bad Request` | A field is missing or invalid. |
| `401 Unauthorized` | A bad or missing key, a test key (only your live API key works here), or an account without API access. |
| `404 Not Found` | No payment with that reference or id. |
| `409 Conflict` | The `reference` was already used for a different amount. |

## Safe retries

Your `reference` makes creating a payment safe to retry. Sending the same `reference` and amount again returns the existing payment with `200 OK` instead of creating a second one, so a request that timed out can simply be sent again. The same `reference` with a different amount is refused with `409 Conflict`.

## Payment options

Customers can pay by **card**, **bank transfer**, **bank account** (GTBank), **USSD** or **Paybeta wallet**. Paybeta and your console settings (Account Settings › Payment gateway) decide which are on. Use `channels` to offer only some of them; an option that's switched off is left out even if `channels` lists it.

## Fees and settlement

Paybeta's fee is taken from the amount by default: the customer pays `amount` and you receive `merchant_amount`. With `pass_charge: true` the fee is added on top instead: the customer pays `charge_amount` (`amount + fee`) and you receive the full `amount`. Without `pass_charge`, your console default applies.

Settlement is the next business day, into your Paybeta wallet by default, or to your approved bank account if you chose that in the console.


---

Source: https://docs.paybeta.ng/checkout-test-mode

# Test mode (sandbox)

> Create payments with "mode": "test" and pay them with these test details. No real money moves.

Create a payment with `"mode": "test"` and pay it on the payment page with the details below. No real money moves, and real cards, accounts and wallets can't pay test payments. Use your **live** API key: it creates test and live payments alike.

## Cards

Use any future expiry date and any 3-digit CVV.

| Card number | What happens |
| --- | --- |
| `4242 4242 4242 4242` | OTP `123456`. For amounts under ₦7,500. |
| `5555 5555 5555 4444` | PIN `1234`, then OTP `123456`. |
| `5200 0000 0000 1096` | 3-D Secure. |

## Bank account (GTBank)

Any 10-digit account number, then the token `123456`.

## Paybeta wallet

| | |
| --- | --- |
| **Wallet ID** | `0123456789` |
| **Password** | None |
| **Transaction PIN** | `1234` |
| **Code** | `123456` |

No real wallet is used.

## Transfer and USSD

Bank transfer and USSD payments don't complete in test mode.

## Going live

Change `mode` to `live`. Nothing else changes: the same API key, host, webhook and verify call. Live payments charge the customer for real, and `merchant_amount` settles on the next business day.


---

Source: https://docs.paybeta.ng/checkout-create-payment

# Create a payment

> Creates a payment and returns the checkout_url to send your customer to.

`POST https://checkout.paybeta.ng/v1/payments`

Authentication: `P-API-KEY` header.

Send the customer to the returned `checkout_url` (redirect), or open it as a popup with `new PaybetaPop().resumeTransaction(id)`, using the payment's `id`.

- `mode` decides whether this is a test payment (no real money) or a live one. See [Test mode](/checkout-test-mode).
- Sending the same `reference` and amount again returns the existing payment (`200 OK`), so a timed-out request is safe to retry. The same `reference` with another amount is refused (`409 Conflict`).
- Keep the `id` or your `reference` to [verify the payment](/checkout-verify-payment) later.

**More examples** (pick them in the Request menu): a payment where the customer pays the fee, a Paybeta wallet-only payment, and a live payment.

## The payment object

| Field | Description |
| --- | --- |
| `id` | Paybeta's id for the payment (`GTW-…`). |
| `reference` | Your reference. |
| `status` | `pending`, `successful`, `failed` or `expired`. |
| `amount` | The amount you asked for, in naira. |
| `fee` | Paybeta's fee. |
| `pass_charge` | Whether the fee is added on top for the customer. |
| `charge_amount` | What the customer pays: `amount`, or `amount + fee` with `pass_charge`. |
| `amount_paid` | What the customer paid, once paid; `null` before. |
| `merchant_amount` | What you receive. |
| `mode` / `livemode` | `test` or `live`. |
| `channel` | How it was paid (`card`, `transfer`, `bank`, `ussd`, `wallet`); `null` until paid. |
| `customer`, `description`, `metadata` | As you sent them. |
| `recurring`, `authorization` | Saved cards; not available yet. |
| `checkout_url` | The payment page. |
| `failure_reason` | Why the last attempt was declined, if it was. |
| `expires_at`, `paid_at`, `created_at` | Times (ISO 8601, West Africa Time, +01:00). |

## Body

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `mode` | string | yes | `test` (sandbox, no real money) or `live`. |
| `reference` | string | yes | Your unique reference for this payment. Reusing it with the same amount returns the existing payment. |
| `amount` | number | yes | In naira. Minimum ₦100. |
| `currency` | string | no | `NGN` (the only currency). |
| `customer` | object | yes | Who is paying. |
| `customer.email` | string | yes | The customer's email. |
| `customer.name` | string | no | The customer's name. |
| `customer.phone` | string | no | The customer's phone number. |
| `description` | string | no | Shown to the customer on the payment page. |
| `redirect_url` | string | no | Where the customer goes after paying (https). |
| `webhook_url` | string | no | Where the webhook goes (public https). Without it, the one saved in the API console is used. |
| `channels` | string | no | The payment options to offer: `card`, `transfer`, `bank`, `ussd`, `wallet`. Options switched off for your account are left out. |
| `pass_charge` | boolean | no | `true` adds Paybeta's fee on top for the customer, so you receive the full amount. Without it, your console default applies. |
| `metadata` | object | no | Your own data (up to 4KB), returned on the payment and its webhook. |
| `expires_in` | integer | no | Minutes until the payment page expires: 5 to 10080. Default 60. |
| `recurring` | boolean | no | `true` saves the card for later charges (card only). Not available yet. |

## Request: Request body

```json
{
  "mode": "test",
  "reference": "ORDER-{{$timestamp}}",
  "amount": 5000,
  "currency": "NGN",
  "description": "Pro plan · monthly",
  "customer": {
    "email": "ada@example.com",
    "name": "Ada Lovelace",
    "phone": "08012345678"
  },
  "redirect_url": "https://shop.example.com/thanks",
  "webhook_url": "https://shop.example.com/webhooks/paybeta",
  "channels": ["card", "transfer", "bank", "ussd", "wallet"],
  "pass_charge": false,
  "metadata": {
    "cart_id": 9
  },
  "expires_in": 60
}
```

## Request: Customer pays the fee

```json
{
  "mode": "test",
  "reference": "ORDER-{{$timestamp}}",
  "amount": 5000,
  "description": "Pro plan · monthly",
  "customer": {
    "email": "ada@example.com"
  },
  "channels": ["card", "transfer"],
  "pass_charge": true
}
```

## Request: Paybeta wallet only

```json
{
  "mode": "test",
  "reference": "ORDER-{{$timestamp}}",
  "amount": 5000,
  "currency": "NGN",
  "description": "Wallet payment test",
  "customer": {
    "email": "ada@example.com",
    "name": "Ada Lovelace",
    "phone": "08012345678"
  },
  "redirect_url": "https://shop.example.com/thanks",
  "channels": ["wallet"]
}
```

## Request: Live payment

```json
{
  "mode": "live",
  "reference": "ORDER-{{$timestamp}}",
  "amount": 5000,
  "currency": "NGN",
  "description": "Pro plan · monthly",
  "customer": {
    "email": "ada@example.com",
    "name": "Ada Lovelace",
    "phone": "08012345678"
  },
  "redirect_url": "https://shop.example.com/thanks",
  "webhook_url": "https://shop.example.com/webhooks/paybeta",
  "channels": ["card", "transfer", "bank", "ussd", "wallet"],
  "pass_charge": false,
  "metadata": {
    "cart_id": 9
  },
  "expires_in": 60
}
```

## Response 201: Created

```json
{
  "status": "successful",
  "message": "Payment created",
  "data": {
    "id": "GTW-K3J7Q2M9X4ZP8L1N5R6T0V2B3C4D",
    "reference": "ORDER-1001",
    "status": "pending",
    "amount": 5000,
    "fee": 70,
    "pass_charge": false,
    "charge_amount": 5000,
    "amount_paid": null,
    "merchant_amount": 4930,
    "mode": "test",
    "livemode": false,
    "currency": "NGN",
    "channel": null,
    "description": "Pro plan · monthly",
    "customer": {
      "email": "ada@example.com",
      "name": "Ada Lovelace",
      "phone": "08012345678"
    },
    "metadata": {
      "cart_id": 9
    },
    "recurring": false,
    "authorization": null,
    "checkout_url": "https://checkout.paybeta.ng/pay/GTW-K3J7Q2M9X4ZP8L1N5R6T0V2B3C4D",
    "provider": "squad",
    "provider_reference": null,
    "failure_reason": null,
    "expires_at": "2026-10-30T13:00:00+01:00",
    "paid_at": null,
    "created_at": "2026-10-30T12:00:00+01:00"
  }
}
```

## Response 201: Customer pays the fee

```json
{
  "status": "successful",
  "message": "Payment created",
  "data": {
    "id": "GTW-K3J7Q2M9X4ZP8L1N5R6T0V2B3C4D",
    "reference": "ORDER-1001",
    "status": "pending",
    "amount": 5000,
    "fee": 70,
    "pass_charge": true,
    "charge_amount": 5070,
    "amount_paid": null,
    "merchant_amount": 5000,
    "mode": "test",
    "livemode": false,
    "currency": "NGN",
    "channel": null,
    "description": "Pro plan · monthly",
    "customer": {
      "email": "ada@example.com",
      "name": null,
      "phone": null
    },
    "metadata": null,
    "recurring": false,
    "authorization": null,
    "checkout_url": "https://checkout.paybeta.ng/pay/GTW-K3J7Q2M9X4ZP8L1N5R6T0V2B3C4D",
    "provider": "squad",
    "provider_reference": null,
    "failure_reason": null,
    "expires_at": "2026-10-30T13:00:00+01:00",
    "paid_at": null,
    "created_at": "2026-10-30T12:00:00+01:00"
  }
}
```

## Response 200: Same reference again

```json
{
  "status": "successful",
  "message": "Payment already exists for this reference",
  "data": {
    "id": "GTW-K3J7Q2M9X4ZP8L1N5R6T0V2B3C4D",
    "reference": "ORDER-1001",
    "status": "pending",
    "amount": 5000,
    "fee": 70,
    "pass_charge": false,
    "charge_amount": 5000,
    "amount_paid": null,
    "merchant_amount": 4930,
    "mode": "test",
    "livemode": false,
    "currency": "NGN",
    "channel": null,
    "description": "Pro plan · monthly",
    "customer": {
      "email": "ada@example.com",
      "name": "Ada Lovelace",
      "phone": "08012345678"
    },
    "metadata": {
      "cart_id": 9
    },
    "recurring": false,
    "authorization": null,
    "checkout_url": "https://checkout.paybeta.ng/pay/GTW-K3J7Q2M9X4ZP8L1N5R6T0V2B3C4D",
    "provider": "squad",
    "provider_reference": null,
    "failure_reason": null,
    "expires_at": "2026-10-30T13:00:00+01:00",
    "paid_at": null,
    "created_at": "2026-10-30T12:00:00+01:00"
  }
}
```

## Response 400: Validation error

```json
{
  "status": "failed",
  "message": "The amount field is required.",
  "data": null
}
```

## Response 409: Same reference, different amount

```json
{
  "status": "failed",
  "message": "Duplicate reference: a payment with this reference already exists for a different amount.",
  "data": {
    "id": "GTW-K3J7Q2M9X4ZP8L1N5R6T0V2B3C4D",
    "reference": "ORDER-1001",
    "amount": 5000,
    "status": "pending"
  }
}
```


---

Source: https://docs.paybeta.ng/checkout-verify-payment

# Verify a payment

> Returns a payment by your reference or its GTW-… id, with its current status.

`GET https://checkout.paybeta.ng/v1/payments/{reference}`

Authentication: `P-API-KEY` header.

Use your `reference` or Paybeta's id (`GTW-…`). While the payment is still open, Paybeta checks with the processor first, so this is always the current state.

**Always verify before you deliver**: after your [webhook](/checkout-webhooks) (its signature covers only `data.reference`), after the customer is redirected back to your site, or after the popup's `onSuccess`.

| `status` | Meaning |
| --- | --- |
| `pending` | Not paid yet. |
| `successful` | Paid. `amount_paid` and `paid_at` are set. |
| `failed` | Expired after a declined attempt. See `failure_reason`. |
| `expired` | Expired without being paid. |

## Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `reference` | string | yes | Your reference, or the payment's `id` (`GTW-…`). |

## Response 200: Paid

```json
{
  "status": "successful",
  "message": "Request processed successfully.",
  "data": {
    "id": "GTW-K3J7Q2M9X4ZP8L1N5R6T0V2B3C4D",
    "reference": "ORDER-1001",
    "status": "successful",
    "amount": 5000,
    "fee": 70,
    "pass_charge": false,
    "charge_amount": 5000,
    "amount_paid": 5000,
    "merchant_amount": 4930,
    "mode": "test",
    "livemode": false,
    "currency": "NGN",
    "channel": "card",
    "description": "Pro plan · monthly",
    "customer": {
      "email": "ada@example.com",
      "name": "Ada Lovelace",
      "phone": "08012345678"
    },
    "metadata": {
      "cart_id": 9
    },
    "recurring": false,
    "authorization": null,
    "checkout_url": "https://checkout.paybeta.ng/pay/GTW-K3J7Q2M9X4ZP8L1N5R6T0V2B3C4D",
    "provider": "squad",
    "provider_reference": "PBG261030122646ABCDEF1234",
    "failure_reason": null,
    "expires_at": "2026-10-30T13:00:00+01:00",
    "paid_at": "2026-10-30T12:04:10+01:00",
    "created_at": "2026-10-30T12:00:00+01:00"
  }
}
```

## Response 404: Not found

```json
{
  "status": "failed",
  "message": "Payment not found",
  "data": null
}
```


---

Source: https://docs.paybeta.ng/checkout-webhooks

# Checkout webhooks

> Paybeta posts a signed event to your webhook_url when a payment succeeds or fails.

When a payment succeeds or fails, Paybeta sends a `POST` to the payment's `webhook_url`, or to the webhook URL saved in your API console.

## Events

| `eventType` | When |
| --- | --- |
| `transaction.successful` | The payment was paid. |
| `transaction.failed` | The payment failed. |

## Headers

| Header | Value |
| --- | --- |
| `Signature` | HMAC SHA256 of `data.reference`, lowercase hex, keyed with your live **secret key** (for test payments too). |
| `Content-Type` | `application/json` |
| `User-Agent` | `Paybeta/1.0` |
| `X-Paybeta-Version` | `2.0` |
| `X-Paybeta-Timestamp` | When it was sent, e.g. `2026-10-30 14:26:46` |

## Payload

```json
{
  "eventType": "transaction.successful",
  "type": "checkout",
  "data": {
    "reference": "ORDER-1001",
    "amount": "5000.00",
    "chargedAmount": "5000.00",
    "fee": "70.00",
    "settledAmount": "4930.00",
    "currency": "NGN",
    "transactionId": "GTW-K3J7Q2M9X4ZP8L1N5R6T0V2B3C4D",
    "transactionDate": "2026-10-30 14:26:46",
    "status": "SUCCESSFUL",
    "message": "Your transaction was successful",
    "channel": "card",
    "mode": "test",
    "description": "Pro plan · monthly",
    "customer": {
      "email": "ada@example.com",
      "name": "Ada Lovelace",
      "phone": "08012345678"
    },
    "metadata": {
      "cart_id": 9
    }
  }
}
```

## Handling it

1. **Check the signature**: compute HMAC SHA256 of `data.reference` with your live secret key and compare it with the `Signature` header, using a constant-time comparison.
2. **Reply quickly with any `2xx`.** Otherwise Paybeta retries after 1, 5, 10, 30, 60, 180 and 360 minutes.
3. **Ignore duplicates**: the same event can arrive more than once. De-duplicate on `data.transactionId` + `eventType`.
4. **Verify before you deliver**: the signature covers only `data.reference`, so confirm the amount and status with [Verify a payment](/checkout-verify-payment).

## Checking the signature

<AccordionGroup>
<Accordion title="PHP / Laravel" defaultOpen>
```php
use Illuminate\Http\Request;

public function handle(Request $request)
{
    $reference = (string) $request->input('data.reference', '');
    $expected = hash_hmac('sha256', $reference, config('services.paybeta.secret_key'));

    if (! hash_equals($expected, (string) $request->header('Signature'))) {
        abort(401);
    }

    // Verify the payment (GET /api/v1/payments/{reference}) before you deliver.
    return response()->noContent();
}
```
</Accordion>
<Accordion title="Node.js (Express)">
```javascript
const crypto = require('crypto');

app.post('/webhooks/paybeta', express.json(), (req, res) => {
  const reference = (req.body.data && req.body.data.reference) || '';
  const expected = crypto.createHmac('sha256', process.env.PAYBETA_SECRET_KEY).update(reference).digest('hex');
  const received = req.get('Signature') || '';

  if (received.length !== expected.length || !crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected))) {
    return res.sendStatus(401);
  }

  // Verify the payment (GET /api/v1/payments/{reference}) before you deliver.
  res.sendStatus(200);
});
```
</Accordion>
<Accordion title="Python (Flask)">
```python
import hashlib, hmac, os
from flask import Flask, request, abort

app = Flask(__name__)

@app.post("/webhooks/paybeta")
def paybeta_webhook():
    reference = (request.get_json(silent=True) or {}).get("data", {}).get("reference", "")
    expected = hmac.new(os.environ["PAYBETA_SECRET_KEY"].encode(), reference.encode(), hashlib.sha256).hexdigest()

    if not hmac.compare_digest(expected, request.headers.get("Signature", "")):
        abort(401)

    # Verify the payment (GET /api/v1/payments/{reference}) before you deliver.
    return "", 200
```
</Accordion>



---

Source: https://docs.paybeta.ng/transaction-query

# Transaction query

> Query Transaction Status

`POST https://api.paybeta.ng/v2/transaction/query`

Authentication: `P-API-KEY` header.

Using a POST method, transaction status can be queried with the endpoint below passing the reference you generated for the payment:

| **Field** | **Mandatory/Optional** | **Description** |
| --- | --- | --- |
| code | O | This is usually returned as response and can also confirmes the final status of a transaction. ```00 = successful,  01 = pending, 02 = failed, 99 = Not found or invalid reference ```|
| status | O | This is returned as response and tells the final status of the transaction. |
| reference | M | This is the reference with which you sent when purchasing a transaction after the transaction has been processed. |

**Note**: Please allow for 2 minutes before requerying a pending transaction.

## Request: Request body

```json
{
  "reference": "1746988617"
}
```

## Response 200: Success

```json
{
  "status": "successful",
  "message": "Your glo airtime payment is successful",
  "code": "00",
  "data": {
    "paymentStatus": "Delivered",
    "reference": "1746988617",
    "amount": 100,
    "amountPaid": 96,
    "product": "GLO AIRTIME",
    "customerId": "09052216560",
    "token": "0",
    "unit": "0",
    "transactionId": "API-174698861781391390",
    "transactionDate": "2025-05-11T18:37:01.000000Z"
  }
}
```
