{ "info": { "_postman_id": "8283ac29-39f9-5e0e-bbc6-647df54ac932", "name": "Paybeta API", "description": "VTU & bill payment API for Nigeria\n\nFull documentation: https://docs.paybeta.ng\n\n**Setup:** set `apiKey` (your secret key from https://console.paybeta.ng) and `baseUrl` in the collection variables, or import the Live / Sandbox environments from https://docs.paybeta.ng/postman/environment/live.json and https://docs.paybeta.ng/postman/environment/sandbox.json.\n\n## Paybeta VTU & Bill Payment API Documentation\n\n![Paybeta VTU and bill payment API for Nigeria](/storage/docs/images/fbb170aa128b9c7b.png)\r\n\r\n\r\n## Overview\r\n\r\nThe [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.\r\n\r\nEvery 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.\r\n\r\n| | |\r\n| --- | --- |\r\n| **Protocol** | REST over HTTPS |\r\n| **Data format** | JSON requests and responses |\r\n| **Authentication** | API key in the `P-API-KEY` header |\r\n| **Environments** | Sandbox and Production |\r\n| **Commission** | See the [Commission Rate Schedule](https://www.paybeta.ng/commissions) |\r\n\r\n## Supported Services and Providers\r\n\r\n| Service | Providers | What you can do |\r\n| --- | --- | --- |\r\n| **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 |\r\n| **Data bundles** | MTN, Airtel, Glo, 9mobile | List available bundles and purchase by bundle code |\r\n| **Electricity** | EKEDC, IKEDC, AEDC, IBEDC, EEDC, PHED, JED, KEDCO, KAEDCO | Validate a prepaid or postpaid meter, then pay and receive the token or units |\r\n| **Cable TV and streaming** | DSTV, GOTV, StarTimes, Showmax | List bouquets, validate the smartcard number and renew the subscription |\r\n| **Education** | JAMB, WAEC | List exam types and purchase PINs. See [Education](/education) |\r\n| **Scheduled payments** | Airtime, data, cable TV, electricity | Create one-time or recurring purchases. See [Schedule Payments](/schedule-payments) |\r\n\r\n### Electricity coverage\r\n\r\nPaybeta supports all of Nigeria's 11 electricity distribution companies (DisCos):\r\n\r\n| DisCo | Code |\r\n| --- | --- |\r\n| Eko Electricity | EKEDC |\r\n| Ikeja Electric | IKEDC |\r\n| Abuja Electricity | AEDC |\r\n| Ibadan Electricity | IBEDC |\r\n| Enugu Electricity | EEDC |\r\n| Port Harcourt Electricity | PHED |\r\n| Jos Electricity | JED |\r\n| Kano Electricity | KEDCO |\r\n| Kaduna Electric | KAEDCO |\r\n| Aba Electric | ABA |\r\n| Yola Electricity | YEDC |\r\n| Benin Electricity | BEDC |\r\n\r\n\r\n![How a Paybeta bill payment transaction flows](/storage/docs/images/de879ee0042269aa.png)\r\n\r\n## Getting Started\r\n\r\n1. **Create a sandbox account.** Register for a [Sandbox Account](https://console.sandbox.paybeta.ng/register) to build and test your integration safely.\r\n\r\n2. **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).\r\n\r\n3. **Complete verification.** Your Account Manager will guide you through the compliance checklist for KYC (Know Your Customer) and KYB (Know Your Business) documents.\r\n\r\n4. **Go live.** Register for a [Production Account](https://console.paybeta.ng/register) and switch to the production base URL and your live API key.\r\n\r\n⚠️ **Important**: Your account must be approved and enabled for Live Mode by the Paybeta compliance team before calls to production endpoints will succeed.\r\n\r\n## Base URLs\r\n\r\n| Environment | Base URL |\r\n| --- | --- |\r\n| Sandbox (**Testing**) | https://api.sandbox.paybeta.ng |\r\n| Production (**Live**) | https://api.paybeta.ng |\r\n\r\n## Authentication\r\n\r\nAll 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).\r\n\r\nKeep your API key secret. Call the API from your server only, and never expose the key in a mobile app or in browser code.\r\n\r\n### Required request headers\r\n\r\n| **Header** | **Value** | **Description** |\r\n| --- | --- | --- |\r\n| Accept | application/json | Sets the response format. |\r\n| Content-Type | application/json | Sets the request payload format. |\r\n| P-API-KEY | Your secret API key | Authorizes your API requests. |\r\n\r\n### Example\r\n\r\n```js\r\nheaders.set('Accept', 'application/json');\r\nheaders.set('Content-Type', 'application/json');\r\nheaders.set('P-API-KEY', 'YOUR_API_KEY');\r\n```\r\n\r\n## Response Format\r\n\r\nEvery response from the Paybeta API uses the same JSON structure, so you can handle success and errors the same way across all services.\r\n\r\n| **Field** | **Type** | **Description** |\r\n| --- | --- | --- |\r\n| status | string | The state of the transaction: `successful`, `failed` or `pending`. |\r\n| message | string | A human-readable explanation of the result. |\r\n| data | object | Transaction details. For example, the token and units for electricity, or the generated PINs for ePIN requests. |\r\n\r\n### Example response\r\n\r\n```json\r\n{\r\n \"status\": \"successful\",\r\n \"message\": \"Transaction successful\",\r\n \"data\": {\r\n \"reference\": \"1714742875\",\r\n \"amount\": 2000,\r\n \"chargedAmount\": 1950,\r\n \"commission\": 50,\r\n \"biller\": \"MTN AIRTIME\",\r\n \"customerId\": \"08068539221\",\r\n \"transactionDate\": \"2024-05-03 14:27:57\",\r\n \"transactionId\": \"1714742877672593466202420\"\r\n }\r\n}\r\n```\r\n\r\nA `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).\n\nhttps://docs.paybeta.ng/overview\n\n---\n\n## Commission\n\nPaybeta 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.\n\nIf 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.\n\n### How API Commissions Work\nCommissions 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:\n\n#### 1. Percentage-Based Discount\nThe commission is applied as a **percentage of the transaction amount**.\n\nThis means that the discount is dynamically calculated based on the total value of the transaction.\n\n**Example**: If a 4% commission is applied to a ₦1,000 transaction, the discount will be ₦**40**, making the effective charge ₦940.\n\n#### 2. Flat Rate-Based Discount\nThe commission is applied as a **fixed amount per transaction**, regardless of the transaction value.\n\nThe discount is predetermined for each product.\n\n**Example**: If a flat discount of **₦50** is set for a service, every transaction will receive a **₦50** reduction, irrespective of the transaction amount.\n\n### Where to Find Paybeta Commissions?\nYou can view the general commission for each product directly on the website [**HERE**](https://www.paybeta.ng/commissions).\n\nhttps://docs.paybeta.ng/commission\n\n---\n\n## Webhook (reference)\n\nEach 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`.\n\n```json\n{\n \"eventType\": \"transaction.successful\",\n \"type\": \"data\",\n \"data\": {\n \"reference\": \"SCH-7F3K9QX2AB12-K3P9XQ2M\",\n \"amount\": \"1,000.00\",\n \"chargedAmount\": \"970.00\",\n \"commission\": \"30.00\",\n \"biller\": \"MTN 1GB - 30 Days\",\n \"customerId\": \"08031234567\",\n \"token\": \"0\",\n \"unit\": \"0\",\n \"voucher\": \"0\",\n \"currency\": \"NGN\",\n \"transactionId\": \"API-17596704001234567\",\n \"transactionDate\": \"2026-11-01 09:00:12\",\n \"status\": \"SUCCESSFUL\",\n \"message\": \"Your transaction was successful\"\n }\n}\n```\n\nPaybeta webhooks include a cryptographic signature in the `Signature` header to ensure the webhook originated from **Paybeta** and hasn't been tampered with.\n\n## Signature Generation\nThe value passed inside the Signature header is calculated using a Hash-based Message Authentication Code (HMAC) with a SHA-256 hashing algorithm.\n\n- **Algorithm**: HMAC-SHA256\n- **Key**: Your API `Secret Key` (keep this hidden on your backend server environment).\n- **Data**: The reference value located inside the transaction data block (`data.reference`).\n\n### Sample Request\n\n**Sent for every recipient once it is charged (and again if a pending one is later confirmed or reversed):**\n\n``` PHP\n{\n \"eventType\": \"transaction.successful|transaction.pending|transaction.failed\",\n \"type\": \"vtu|tv|gaming|data|utility|education|insurance|travel\",\n \"data\": {\n \"reference\": \"REF-3AQ780KP87WS1356\",\n \"amount\": \"300.00\",\n \"chargedAmount\": \"292.50\",\n \"commission\": \"7.50\",\n \"biller\": \"MTN Airtime\",\n \"customerId\": \"08030000000\",\n \"token\": \"0\",\n \"unit\": \"0\",\n \"bonusToken\": \"0\",\n \"voucher\": \"0\",\n \"currency\": \"NGN\",\n \"transactionId\": \"API-4780819357880920990\",\n \"transactionDate\": \"2025-03-07 16:29:17\",\n \"status\": \"SUCCESSFUL\",\n \"message\": \"Your transaction was successful\"\n }\n}\n```\n\n## How to Verify the Signature\n\n- Capture the incoming raw JSON payload and extract the data.reference string.\n- Read the value present inside the Signature request header.\n- Compute an **HMAC-SHA256** hash using the transaction reference as the data string and your merchant secret key as the signing key.\n- Compare your locally computed string with the header value using a **constant-time string comparison** method to safeguard against timing analysis side-channel attacks.\n\nCode Verification Code Examples\n\n\n\n \n \n \n ```PHP\n \n json()->all();\n $headerSignature = $request->header('Signature');\n\n // Extract transaction reference\n $reference = $payload['data']['reference'] ?? '';\n\n // Retrieve your secret key securely from configuration\n $secretKey = config('services.paybeta.secret_key');\n\n // Calculate expected signature\n $computedSignature = hash_hmac('sha256', $reference, $secretKey);\n\n // Safe string comparison preventing timing attacks\n if (!hash_equals($computedSignature, $headerSignature)) {\n return response()->json(['error' => 'Invalid Signature'], 401);\n }\n\n // Process transaction event logic below\n // ...\n\n return response()->json(['status' => 'success'], 200);\n }\n }\n ```\n\n \n \n ``` JS\n const express = require('express');\n const crypto = require('crypto');\n const app = express();\n\n app.use(express.json());\n\n app.post('/webhooks/paybeta', (req, res) => {\n const headerSignature = req.headers['signature'];\n const payload = req.body;\n\n // Extract transaction reference\n const reference = payload?.data?.reference || '';\n const secretKey = process.env.PAYBETA_SECRET_KEY;\n\n // Compute signature\n const computedSignature = crypto\n .createHmac('sha256', secretKey)\n .update(reference)\n .digest('hex');\n\n // Safe timing-attack-resistant comparison\n try {\n const isVerified = crypto.timingSafeEqual(\n Buffer.from(computedSignature, 'utf-8'),\n Buffer.from(headerSignature, 'utf-8')\n );\n\n if (!isVerified) {\n return res.status(401).json({ error: 'Invalid Signature' });\n }\n } catch (e) {\n return res.status(401).json({ error: 'Verification failed' });\n }\n\n // Process event data safely\n res.status(200).json({ status: 'success' });\n });\n\n ```\n \n \n \n```csharp\n\nusing Microsoft.AspNetCore.Mvc;\nusing System.Security.Cryptography;\nusing System.Text;\nusing System.Text.Json;\n\nnamespace PaybetaWebhook.Controllers\n{\n [ApiController]\n [Route(\"webhooks\")]\n public class PaybetaWebhookController : ControllerBase\n {\n private const string SecretKey = \"your_secret_key_here\";\n\n [HttpPost(\"paybeta\")]\n public async Task HandleWebhook()\n {\n // 1. Extract the Signature from headers\n if (!Request.Headers.TryGetValue(\"Signature\", out var headerSignature))\n {\n return Unauthorized(new { error = \"Missing Signature header\" });\n }\n\n // 2. Read and parse the incoming body stream\n using var reader = new StreamReader(Request.Body);\n var rawJson = await reader.ReadToEndAsync();\n \n using var jsonDoc = JsonDocument.Parse(rawJson);\n \n // Navigate safely to payload string: data.reference\n string reference = \"\";\n if (jsonDoc.RootElement.TryGetProperty(\"data\", out var dataElement) && \n dataElement.TryGetProperty(\"reference\", out var refElement))\n {\n reference = refElement.GetString() ?? \"\";\n }\n\n // 3. Compute expected HMAC-SHA256 signature\n var keyBytes = Encoding.UTF8.GetBytes(SecretKey);\n var referenceBytes = Encoding.UTF8.GetBytes(reference);\n\n using var hmac = new HMACSHA256(keyBytes);\n var hashBytes = hmac.ComputeHash(referenceBytes);\n \n // Convert byte array to hexadecimal string representation\n var computedSignature = Convert.ToHexString(hashBytes).ToLower();\n\n // 4. Safe constant-time string comparison\n if (!CryptographicOperations.FixedTimeEquals(\n Encoding.UTF8.GetBytes(computedSignature), \n Encoding.UTF8.GetBytes(headerSignature.ToString())))\n {\n return Unauthorized(new { error = \"Invalid Signature\" });\n }\n\n // Execute core backend settlement workflow here\n return Ok(new { status = \"success\" });\n }\n }\n}\n```\n \n \n \n```java\npackage com.paybeta.webhook.controller;\n\nimport org.json.JSONObject;\nimport org.springframework.http.HttpStatus;\nimport org.springframework.http.ResponseEntity;\nimport org.springframework.web.bind.annotation.*;\nimport javax.crypto.Mac;\nimport javax.crypto.spec.SecretKeySpec;\nimport java.nio.charset.StandardCharsets;\nimport java.security.MessageDigest;\n\n@RestController\n@RequestMapping(\"/webhooks\")\npublic class PaybetaWebhookController {\n\n private static final String SECRET_KEY = \"your_secret_key_here\";\n\n @PostMapping(\"/paybeta\")\n public ResponseEntity handleWebhook(\n @RequestHeader(\"Signature\") String headerSignature,\n @RequestBody String rawJsonPayload) {\n\n try {\n // 1. Parse JSON block to extract the transaction reference string\n JSONObject jsonObject = new JSONObject(rawJsonPayload);\n String reference = jsonObject.getJSONObject(\"data\").optString(\"reference\", \"\");\n\n // 2. Initialize HMAC-SHA256 Engine\n Mac sha256HMAC = Mac.getInstance(\"HmacSHA256\");\n SecretKeySpec secretKeySpec = new SecretKeySpec(\n SECRET_KEY.getBytes(StandardCharsets.UTF_8), \"HmacSHA256\"\n );\n sha256HMAC.init(secretKeySpec);\n\n // 3. Calculate Signature Bytes and encode to Hex string representation\n byte[] rawMacBytes = sha256HMAC.doFinal(reference.getBytes(StandardCharsets.UTF_8));\n StringBuilder hexStringBuilder = new StringBuilder();\n for (byte b : rawMacBytes) {\n hexStringBuilder.append(String.format(\"%02x\", b));\n }\n String computedSignature = hexStringBuilder.toString();\n\n // 4. Secure constant-time evaluation to block execution timing attacks\n boolean signaturesMatch = MessageDigest.isEqual(\n computedSignature.getBytes(StandardCharsets.UTF_8),\n headerSignature.getBytes(StandardCharsets.UTF_8)\n );\n\n if (!signaturesMatch) {\n return ResponseEntity.status(HttpStatus.UNAUTHORIZED)\n .body(\"{\\\"error\\\": \\\"Invalid Signature\\\"}\");\n }\n\n // Process your platform updates here safely\n return ResponseEntity.ok(\"{\\\"status\\\": \\\"success\\\"}\");\n\n } catch (Exception e) {\n return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)\n .body(\"{\\\"error\\\": \\\"Processing exception occurred\\\"}\");\n }\n }\n}\n\n```\n \n \n \n```python\n\nimport hmac\nimport hashlib\nfrom flask import Flask, request, jsonify\n\napp = Flask(__name__)\n\nPAYBETA_SECRET_KEY = \"your_secret_key_here\"\n\n@app.route('/webhooks/paybeta', methods=['POST'])\ndef paybeta_webhook():\n header_signature = request.headers.get('Signature')\n payload = request.get_json() or {}\n \n # Extract reference path string\n transaction_data = payload.get('data', {})\n reference = transaction_data.get('reference', '')\n\n # Generate expected hash match\n computed_signature = hmac.new(\n key=PAYBETA_SECRET_KEY.encode('utf-8'),\n msg=reference.encode('utf-8'),\n digestmod=hashlib.sha256\n ).hexdigest()\n\n # Compare safely\n if not hmac.compare_digest(computed_signature, header_signature):\n return jsonify({\"error\": \"Invalid Signature\"}), 401\n\n # Execute system update routines\n return jsonify({\"status\": \"success\"}), 200\n\nif __name__ == '__main__':\n app.run(port=5000)\n```\n \n\n\nhttps://docs.paybeta.ng/webhook-reference", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json" }, "auth": { "type": "apikey", "apikey": [ { "key": "key", "value": "P-API-KEY", "type": "string" }, { "key": "value", "value": "{{apiKey}}", "type": "string" }, { "key": "in", "value": "header", "type": "string" } ] }, "variable": [ { "key": "baseUrl", "value": "https://api.paybeta.ng", "type": "string" }, { "key": "apiKey", "value": "", "type": "string" } ], "item": [ { "name": "Airtime VTU API", "item": [ { "name": "Providers", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v2/airtime/providers", "host": [ "{{baseUrl}}" ], "path": [ "v2", "airtime", "providers" ] }, "description": "Response:\n\n``` json\n{\n \"status\": \"successful\",\n \"message\": \"Request processed successfully.\",\n \"data\": [\n {\n \"name\": \"MTN VTU\",\n \"category\": \"airtime\",\n \"status\": true,\n \"logo\": \"https://res.cloudinary.com/paybeta/image/upload/v1713709773/Provider/VTU/800px-New-mtn-logo_wpn9qq.jpg\"\n },\n {\n \"name\": \"GLO VTU\",\n \"category\": \"airtime\",\n \"status\": true,\n \"logo\": \"https://res.cloudinary.com/paybeta/image/upload/v1713709647/Provider/VTU/glo_fpaf7m.svg\"\n },\n {\n \"name\": \"AIrtel VTU\",\n \"category\": \"airtime\",\n \"status\": true,\n \"logo\": \"https://res.cloudinary.com/paybeta/image/upload/v1713709747/Provider/VTU/airtel_qkjpk1.png\"\n },\n {\n \"name\": \"9mobile VTU\",\n \"category\": \"airtime\",\n \"status\": true,\n \"logo\": \"https://res.cloudinary.com/paybeta/image/upload/v1713709763/Provider/VTU/9mobile_iswfnh.svg\"\n }\n ]\n}\n\n ```\n\nDocs: https://docs.paybeta.ng/airtime-providers" }, "response": [ { "name": "Success (200)", "originalRequest": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v2/airtime/providers", "host": [ "{{baseUrl}}" ], "path": [ "v2", "airtime", "providers" ] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"successful\",\n \"message\": \"Request processed successfully.\",\n \"data\": [\n {\n \"name\": \"MTN VTU\",\n \"category\": \"airtime\",\n \"status\": true,\n \"logo\": \"https://res.cloudinary.com/paybeta/image/upload/v1713709773/Provider/VTU/800px-New-mtn-logo_wpn9qq.jpg\"\n },\n {\n \"name\": \"GLO VTU\",\n \"category\": \"airtime\",\n \"status\": true,\n \"logo\": \"https://res.cloudinary.com/paybeta/image/upload/v1713709647/Provider/VTU/glo_fpaf7m.svg\"\n },\n {\n \"name\": \"AIrtel VTU\",\n \"category\": \"airtime\",\n \"status\": true,\n \"logo\": \"https://res.cloudinary.com/paybeta/image/upload/v1713709747/Provider/VTU/airtel_qkjpk1.png\"\n },\n {\n \"name\": \"9mobile VTU\",\n \"category\": \"airtime\",\n \"status\": true,\n \"logo\": \"https://res.cloudinary.com/paybeta/image/upload/v1713709763/Provider/VTU/9mobile_iswfnh.svg\"\n }\n ]\n}" } ] }, { "name": "Payment", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v2/airtime/purchase", "host": [ "{{baseUrl}}" ], "path": [ "v2", "airtime", "purchase" ] }, "body": { "mode": "raw", "raw": "{\n \"service\": \"mtn_vtu\",\n \"phoneNumber\": \"08123333394\",\n \"amount\": 200,\n \"reference\": \"{{$timestamp}}\"\n}", "options": { "raw": { "language": "json" } } }, "description": "The available service are:\n\n_mtn_vtu_\n\n_glo_vtu_\n\n_9mobile_vtu_\n\n_airtel_vtu_\n\nDocs: https://docs.paybeta.ng/airtime-payment" }, "response": [ { "name": "Success (200)", "originalRequest": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v2/airtime/purchase", "host": [ "{{baseUrl}}" ], "path": [ "v2", "airtime", "purchase" ] }, "body": { "mode": "raw", "raw": "{\n \"service\": \"mtn_vtu\",\n \"phoneNumber\": \"08123333394\",\n \"amount\": 200,\n \"reference\": \"{{$timestamp}}\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"successful\",\n \"message\": \"Transaction successful\",\n \"data\": {\n \"reference\": \"1714742875\",\n \"amount\": 2000,\n \"chargedAmount\": 1950,\n \"commission\": 50,\n \"biller\": \"MTN AIRTIME\",\n \"customerId\": \"08068539221\",\n \"previousBalance\": 499971725,\n \"currentBalance\": 499969775,\n \"transactionDate\": \"2024-05-03 14:27:57\",\n \"transactionId\": \"1714742877672593466202420\"\n }\n}" } ] } ], "description": "## MTN VTU API Integration\n\nThis section contains the recommended flow for integrating MTN VTU services on the Paybeta RESTful API.\n\nMTN Airtime API on Paybeta\n\nhttps://docs.paybeta.ng/mtn-vtu-api-integration" }, { "name": "Data Bundle API", "item": [ { "name": "Get Providers", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v2/data-bundle/providers", "host": [ "{{baseUrl}}" ], "path": [ "v2", "data-bundle", "providers" ] }, "description": "``` json\n{\n \"status\": \"successful\",\n \"message\": \"Request processed successfully.\",\n \"data\": [\n {\n \"name\": \"Airtel Data\",\n \"category\": \"internet\",\n \"slug\": \"airtel-data\",\n \"status\": true,\n \"logo\": \"https://res.cloudinary.com/paybeta/image/upload/v1713709747/Provider/VTU/airtel_qkjpk1.png\"\n },\n {\n \"name\": \"MTN Data\",\n \"category\": \"internet\",\n \"slug\": \"mtn-data\",\n \"status\": true,\n \"logo\": \"https://res.cloudinary.com/paybeta/image/upload/v1713709773/Provider/VTU/800px-New-mtn-logo_wpn9qq.jpg\"\n },\n {\n \"name\": \"Glo Data\",\n \"category\": \"internet\",\n \"slug\": \"glo-data\",\n \"status\": true,\n \"logo\": \"https://res.cloudinary.com/paybeta/image/upload/v1713709647/Provider/VTU/glo_fpaf7m.svg\"\n },\n {\n \"name\": \"9mobile Data\",\n \"category\": \"internet\",\n \"slug\": \"9mobile-data\",\n \"status\": true,\n \"logo\": \"https://res.cloudinary.com/paybeta/image/upload/v1713709763/Provider/VTU/9mobile_iswfnh.svg\"\n }\n ]\n}\n\n ```\n\nDocs: https://docs.paybeta.ng/data-bundle-get-providers" }, "response": [ { "name": "Success (200)", "originalRequest": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v2/data-bundle/providers", "host": [ "{{baseUrl}}" ], "path": [ "v2", "data-bundle", "providers" ] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"successful\",\n \"message\": \"Request processed successfully.\",\n \"data\": [\n {\n \"name\": \"Airtel Data\",\n \"category\": \"internet\",\n \"slug\": \"airtel-data\",\n \"status\": true,\n \"logo\": \"https://res.cloudinary.com/paybeta/image/upload/v1713709747/Provider/VTU/airtel_qkjpk1.png\"\n },\n {\n \"name\": \"MTN Data\",\n \"category\": \"internet\",\n \"slug\": \"mtn-data\",\n \"status\": true,\n \"logo\": \"https://res.cloudinary.com/paybeta/image/upload/v1713709773/Provider/VTU/800px-New-mtn-logo_wpn9qq.jpg\"\n },\n {\n \"name\": \"Glo Data\",\n \"category\": \"internet\",\n \"slug\": \"glo-data\",\n \"status\": true,\n \"logo\": \"https://res.cloudinary.com/paybeta/image/upload/v1713709647/Provider/VTU/glo_fpaf7m.svg\"\n },\n {\n \"name\": \"9mobile Data\",\n \"category\": \"internet\",\n \"slug\": \"9mobile-data\",\n \"status\": true,\n \"logo\": \"https://res.cloudinary.com/paybeta/image/upload/v1713709763/Provider/VTU/9mobile_iswfnh.svg\"\n }\n ]\n}" } ] }, { "name": "Get Data Bundles", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v2/data-bundle/list", "host": [ "{{baseUrl}}" ], "path": [ "v2", "data-bundle", "list" ] }, "body": { "mode": "raw", "raw": "{\n \"service\": \"mtn_data\"\n}", "options": { "raw": { "language": "json" } } }, "description": "``` json\n{\n \"status\": \"successful\",\n \"message\": \"Request processed successfully.\",\n \"data\": [\n {\n \"name\": \"Airtel Data\",\n \"category\": \"internet\",\n \"slug\": \"airtel-data\",\n \"status\": true,\n \"logo\": \"https://res.cloudinary.com/paybeta/image/upload/v1713709747/Provider/VTU/airtel_qkjpk1.png\"\n },\n {\n \"name\": \"MTN Data\",\n \"category\": \"internet\",\n \"slug\": \"mtn-data\",\n \"status\": true,\n \"logo\": \"https://res.cloudinary.com/paybeta/image/upload/v1713709773/Provider/VTU/800px-New-mtn-logo_wpn9qq.jpg\"\n },\n {\n \"name\": \"Glo Data\",\n \"category\": \"internet\",\n \"slug\": \"glo-data\",\n \"status\": true,\n \"logo\": \"https://res.cloudinary.com/paybeta/image/upload/v1713709647/Provider/VTU/glo_fpaf7m.svg\"\n },\n {\n \"name\": \"9mobile Data\",\n \"category\": \"internet\",\n \"slug\": \"9mobile-data\",\n \"status\": true,\n \"logo\": \"https://res.cloudinary.com/paybeta/image/upload/v1713709763/Provider/VTU/9mobile_iswfnh.svg\"\n }\n ]\n}\n\n ```\n\nDocs: https://docs.paybeta.ng/data-bundle-get-data-bundles" }, "response": [ { "name": "Success (200)", "originalRequest": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v2/data-bundle/list", "host": [ "{{baseUrl}}" ], "path": [ "v2", "data-bundle", "list" ] }, "body": { "mode": "raw", "raw": "{\n \"service\": \"mtn_data\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"successful\",\n \"message\": \"Request processed successfully.\",\n \"data\": {\n \"packages\": [\n {\n \"code\": \"MTN_100_MB_DAILY_DATA_BUNDLE\",\n \"description\": \"MTN 100 MB DAILY DATA BUNDLE\",\n \"price\": \"100.00\"\n },\n {\n \"code\": \"MTN_200_MB_DAILY_DATA_BUNDLE\",\n \"description\": \"MTN 200 MB DAILY DATA BUNDLE\",\n \"price\": \"200.00\"\n },\n {\n \"code\": \"MTN_1.8_GB_MONTHLY_DATA_BUNDLE\",\n \"description\": \"MTN 1.8 GB MONTHLY DATA BUNDLE\",\n \"price\": \"1500.00\"\n },\n ...\n ]\n }\n}" } ] }, { "name": "Payment", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v2/data-bundle/purchase", "host": [ "{{baseUrl}}" ], "path": [ "v2", "data-bundle", "purchase" ] }, "body": { "mode": "raw", "raw": "{\n \"service\": \"mtn_data\",\n \"amount\": 100,\n \"phoneNumber\": \"08138539550\",\n \"code\": \"MT1\",\n \"reference\": \"{{$timestamp}}\"\n}", "options": { "raw": { "language": "json" } } }, "description": "Docs: https://docs.paybeta.ng/data-bundle-payment" }, "response": [ { "name": "Success (200)", "originalRequest": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v2/data-bundle/purchase", "host": [ "{{baseUrl}}" ], "path": [ "v2", "data-bundle", "purchase" ] }, "body": { "mode": "raw", "raw": "{\n \"service\": \"mtn_data\",\n \"amount\": 100,\n \"phoneNumber\": \"08138539550\",\n \"code\": \"MT1\",\n \"reference\": \"{{$timestamp}}\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"successful\",\n \"message\": \"Transaction successful\",\n \"data\": {\n \"reference\": \"1715553597\",\n \"amount\": 100,\n \"chargedAmount\": 97.5,\n \"commission\": 2.5,\n \"biller\": \"MTN 100MB 1 Day\",\n \"customerId\": \"08060000000\",\n \"token\": null,\n \"unit\": null,\n \"bonusToken\": null,\n \"transactionDate\": \"2024-05-12 23:39:58\",\n \"transactionId\": \"17155535989070949852\"\n }\n}" } ] } ] }, { "name": "Cable TV API", "item": [ { "name": "Get Providers", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v2/cable/providers", "host": [ "{{baseUrl}}" ], "path": [ "v2", "cable", "providers" ] }, "description": "Docs: https://docs.paybeta.ng/cable-tv-get-providers" }, "response": [ { "name": "Success (200)", "originalRequest": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v2/cable/providers", "host": [ "{{baseUrl}}" ], "path": [ "v2", "cable", "providers" ] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"successful\",\n \"message\": \"Request processed successfully.\",\n \"data\": [\n {\n \"name\": \"DStv\",\n \"category\": \"cable\",\n \"slug\": \"dstv\",\n \"status\": true,\n \"logo\": \"https://res.cloudinary.com/paybeta/image/upload/v1714827633/Provider/Cable/dstv.jpg\"\n },\n {\n \"name\": \"GOtv\",\n \"category\": \"cable\",\n \"slug\": \"gotv\",\n \"status\": true,\n \"logo\": \"https://res.cloudinary.com/paybeta/image/upload/v1714828100/Provider/Cable/gotv.png\"\n },\n {\n \"name\": \"StarTimes\",\n \"category\": \"cable\",\n \"slug\": \"startimes\",\n \"status\": true,\n \"logo\": \"https://res.cloudinary.com/paybeta/image/upload/v1714827913/Provider/Cable/startimes.jpg\"\n }\n ]\n}" } ] }, { "name": "Get Bouquet", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v2/cable/bouquet", "host": [ "{{baseUrl}}" ], "path": [ "v2", "cable", "bouquet" ] }, "body": { "mode": "raw", "raw": "{\n \"service\": \"dstv\"\n}", "options": { "raw": { "language": "json" } } }, "description": "Docs: https://docs.paybeta.ng/cable-tv-get-bouquet" }, "response": [ { "name": "Success (200)", "originalRequest": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v2/cable/bouquet", "host": [ "{{baseUrl}}" ], "path": [ "v2", "cable", "bouquet" ] }, "body": { "mode": "raw", "raw": "{\n \"service\": \"dstv\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"successful\",\n \"message\": \"Request processed successfully.\",\n \"data\": {\n \"packages\": [\n {\n \"code\": \"GOHAN\",\n \"description\": \"GOtv Smallie - monthly\",\n \"price\": \"1900\"\n },\n {\n \"code\": \"GOTVNJ1\",\n \"description\": \"GOtv Jinja Bouquet\",\n \"price\": \"3900\"\n },\n {\n \"code\": \"GOLITE\",\n \"description\": \"GOtv Smallie - quarterly\",\n \"price\": \"5100\"\n },\n {\n \"code\": \"GOTVNJ2\",\n \"description\": \"GOtv Jolli Bouquet\",\n \"price\": \"5800\"\n },\n {\n \"code\": \"GOtvMax\",\n \"description\": \"GOtv Max\",\n \"price\": \"8500\"\n },\n {\n \"code\": \"GOTVSUPA\",\n \"description\": \"SUPA\",\n \"price\": \"11400\"\n },\n {\n \"code\": \"GOTVSUPAPLUS\",\n \"description\": \"GOtv Supa Plus Bouquet\",\n \"price\": \"13900\"\n },\n {\n \"code\": \"GOLTANL\",\n \"description\": \"GOtv Smallie - yearly\",\n \"price\": \"15000\"\n }\n ]\n }\n}" } ] }, { "name": "Validate Account", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v2/cable/validate", "host": [ "{{baseUrl}}" ], "path": [ "v2", "cable", "validate" ] }, "body": { "mode": "raw", "raw": "{\n \"service\": \"gotv\",\n \"smartCardNumber\": \"8072916698\"\n}", "options": { "raw": { "language": "json" } } }, "description": "Docs: https://docs.paybeta.ng/cable-tv-validate-account" }, "response": [ { "name": "Success (200)", "originalRequest": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v2/cable/validate", "host": [ "{{baseUrl}}" ], "path": [ "v2", "cable", "validate" ] }, "body": { "mode": "raw", "raw": "{\n \"service\": \"gotv\",\n \"smartCardNumber\": \"8072916698\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"successful\",\n \"message\": \"Request processed successfully.\",\n \"data\": {\n \"customerName\": \"KAREEM KAREEM\",\n \"smartCardNumber\": \"8072916698\",\n \"service\": \"GOTV\"\n }\n}" } ] }, { "name": "Payment", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v2/cable/purchase", "host": [ "{{baseUrl}}" ], "path": [ "v2", "cable", "purchase" ] }, "body": { "mode": "raw", "raw": "{\n \"service\": \"dstv\",\n \"smartCardNumber\": \"806***82\",\n \"amount\": 200,\n \"packageCode\": \"COMPLE36\",\n \"customerName\": \"JOHN DOE\",\n \"reference\": \"{{$timestamp}}\"\n}", "options": { "raw": { "language": "json" } } }, "description": "Docs: https://docs.paybeta.ng/cable-tv-payment" }, "response": [ { "name": "Success (200)", "originalRequest": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v2/cable/purchase", "host": [ "{{baseUrl}}" ], "path": [ "v2", "cable", "purchase" ] }, "body": { "mode": "raw", "raw": "{\n \"service\": \"dstv\",\n \"smartCardNumber\": \"806***82\",\n \"amount\": 200,\n \"packageCode\": \"COMPLE36\",\n \"customerName\": \"JOHN DOE\",\n \"reference\": \"{{$timestamp}}\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"successful\",\n \"message\": \"Transaction successful\",\n \"data\": {\n \"reference\": \"1715458530\",\n \"amount\": 201,\n \"chargedAmount\": 197.99,\n \"commission\": 3.02,\n \"biller\": \"DStv Compact Plus\",\n \"customerId\": \"8216167618\",\n \"token\": null,\n \"unit\": null,\n \"bonusToken\": null,\n \"transactionDate\": \"2024-05-11 21:15:31\",\n \"transactionId\": \"17154585319693132432\"\n }\n}" } ] } ] }, { "name": "Electricity API", "item": [ { "name": "Get Providers", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v2/electricity/providers", "host": [ "{{baseUrl}}" ], "path": [ "v2", "electricity", "providers" ] }, "description": "Docs: https://docs.paybeta.ng/electricity-get-providers" }, "response": [ { "name": "Success (200)", "originalRequest": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v2/electricity/providers", "host": [ "{{baseUrl}}" ], "path": [ "v2", "electricity", "providers" ] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"successful\",\n \"message\": \"Request processed successfully.\",\n \"data\": [\n {\n \"name\": \"Enugu Electricity\",\n \"category\": \"electricity\",\n \"slug\": \"enugu-electric\",\n \"status\": true,\n \"logo\": \"https://res.cloudinary.com/paybeta/image/upload/v1715293602/Provider/Electricity/eedc.png\"\n },\n {\n \"name\": \"Abuja Electricity\",\n \"category\": \"electricity\",\n \"status\": true,\n \"logo\": \"https://res.cloudinary.com/paybeta/image/upload/v1715293658/Provider/Electricity/aedc.png\"\n },\n {\n \"name\": \"Ikeja Electric\",\n \"category\": \"electricity\",\n \"slug\": \"ikeja-electric\",\n \"status\": true,\n \"logo\": \"https://res.cloudinary.com/paybeta/image/upload/v1715293826/Provider/Electricity/ikedc.png\"\n }\n ...\n ]\n}" } ] }, { "name": "Validate Account", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v2/electricity/validate", "host": [ "{{baseUrl}}" ], "path": [ "v2", "electricity", "validate" ] }, "body": { "mode": "raw", "raw": "{\n \"service\": \"ikeja-electric\",\n \"meterNumber\": \"0111100049\",\n \"meterType\": \"prepaid\"\n}", "options": { "raw": { "language": "json" } } }, "description": "Docs: https://docs.paybeta.ng/electricity-validate-account" }, "response": [] }, { "name": "Payment", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v2/electricity/purchase", "host": [ "{{baseUrl}}" ], "path": [ "v2", "electricity", "purchase" ] }, "body": { "mode": "raw", "raw": "{\n \"service\": \"ikeja-electric\",\n \"meterNumber\": \"042***3016\",\n \"meterType\": \"prepaid\",\n \"amount\": 2000,\n \"customerName\": \"MR JOHN DOE\",\n \"customerAddress\": \"1 JOHN DOE STR\",\n \"reference\": \"{{$timestamp}}\"\n}", "options": { "raw": { "language": "json" } } }, "description": "Docs: https://docs.paybeta.ng/electricity-payment" }, "response": [ { "name": "Success (200)", "originalRequest": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v2/electricity/purchase", "host": [ "{{baseUrl}}" ], "path": [ "v2", "electricity", "purchase" ] }, "body": { "mode": "raw", "raw": "{\n \"service\": \"ikeja-electric\",\n \"meterNumber\": \"042***3016\",\n \"meterType\": \"prepaid\",\n \"amount\": 2000,\n \"customerName\": \"MR JOHN DOE\",\n \"customerAddress\": \"1 JOHN DOE STR\",\n \"reference\": \"{{$timestamp}}\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"successful\",\n \"message\": \"Transaction successful\",\n \"data\": {\n \"reference\": \"1715455653\",\n \"amount\": 1000,\n \"chargedAmount\": 496.5,\n \"commission\": 3.5,\n \"biller\": \"Ikeja Electricity - IKEDC\",\n \"customerId\": \"10428776010\",\n \"token\": \"3193-6233-0096-7827-3805\",\n \"unit\": \"44.6\",\n \"bonusToken\": \"\",\n \"transactionDate\": \"2024-05-11 20:27:33\",\n \"transactionId\": \"17154556531428310982\"\n }\n}" } ] } ] }, { "name": "Gaming API", "item": [ { "name": "Get Providers", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v2/gaming/providers", "host": [ "{{baseUrl}}" ], "path": [ "v2", "gaming", "providers" ] }, "description": "Docs: https://docs.paybeta.ng/gaming-get-providers" }, "response": [ { "name": "Success (200)", "originalRequest": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v2/gaming/providers", "host": [ "{{baseUrl}}" ], "path": [ "v2", "gaming", "providers" ] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"successful\",\n \"message\": \"Request processed successfully.\",\n \"data\": [\n {\n \"name\": \"betking\",\n \"category\": \"gaming\",\n \"slug\": \"betking\",\n \"logo\": \"\"\n },\n {\n \"name\": \"bet9ja\",\n \"category\": \"gaming\",\n \"slug\": \"bet9ja\",\n \"logo\": \"\"\n },\n {\n \"name\": \"bangbet\",\n \"category\": \"gaming\",\n \"slug\": \"bangbet\",\n \"logo\": \"\"\n }\n ...\n ]\n}" } ] }, { "name": "Validate Account", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v2/gaming/validate", "host": [ "{{baseUrl}}" ], "path": [ "v2", "gaming", "validate" ] }, "body": { "mode": "raw", "raw": "{\n \"service\": \"nairabet\",\n \"customerId\": \"20***96\"\n}", "options": { "raw": { "language": "json" } } }, "description": "Docs: https://docs.paybeta.ng/gaming-validate-account" }, "response": [ { "name": "Success (200)", "originalRequest": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v2/gaming/validate", "host": [ "{{baseUrl}}" ], "path": [ "v2", "gaming", "validate" ] }, "body": { "mode": "raw", "raw": "{\n \"service\": \"nairabet\",\n \"customerId\": \"20***96\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"successful\",\n \"message\": \"Request processed successfully.\",\n \"data\": {\n \"customerName\": \"DAVID SAKOUNO\",\n \"customerId\": \"14430818\",\n \"service\": \"Bet9ja\",\n \"minimumAmount\": 100\n }\n}" } ] }, { "name": "Payment", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v2/gaming/purchase", "host": [ "{{baseUrl}}" ], "path": [ "v2", "gaming", "purchase" ] }, "body": { "mode": "raw", "raw": "{\n \"service\": \"nairabet\",\n \"customerId\": \"201***96\",\n \"amount\": 1000,\n \"customerName\": \"gen***07\",\n \"reference\": \"{{$timestamp}}\"\n}", "options": { "raw": { "language": "json" } } }, "description": "Docs: https://docs.paybeta.ng/gaming-payment" }, "response": [] } ] }, { "name": "Education API", "item": [ { "name": "Get Providers", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v2/education/providers", "host": [ "{{baseUrl}}" ], "path": [ "v2", "education", "providers" ] }, "description": "Docs: https://docs.paybeta.ng/education-get-providers" }, "response": [ { "name": "Success (200)", "originalRequest": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v2/education/providers", "host": [ "{{baseUrl}}" ], "path": [ "v2", "education", "providers" ] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"successful\",\n \"message\": \"Request processed successfully.\",\n \"data\": [\n {\n \"name\": \"JAMB PIN Vending\",\n \"category\": \"education\",\n \"slug\": \"jamb\",\n \"logo\": \"https://res.cloudinary.com/paybeta/image/upload/v1770680329/Static/img/jamb-pin-vending.jpg\"\n },\n {\n \"name\": \"WAEC Registration PIN\",\n \"category\": \"education\",\n \"slug\": \"waec-registration\",\n \"logo\": \"https://res.cloudinary.com/paybeta/image/upload/v1770680211/Static/img/waec-pin.jpg\"\n },\n {\n \"name\": \"WAEC Result Checker PIN\",\n \"category\": \"education\",\n \"slug\": \"waec-result\",\n \"logo\": \"https://res.cloudinary.com/paybeta/image/upload/v1770680280/Static/img/waec-result-checker-pin.jpg\"\n }\n ]\n}" } ] }, { "name": "Get Exam Types", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v2/education/list", "host": [ "{{baseUrl}}" ], "path": [ "v2", "education", "list" ] }, "body": { "mode": "raw", "raw": "{\n \"service\": \"jamb\"\n}", "options": { "raw": { "language": "json" } } }, "description": "Docs: https://docs.paybeta.ng/education-get-exam-types" }, "response": [ { "name": "Success (200)", "originalRequest": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v2/education/list", "host": [ "{{baseUrl}}" ], "path": [ "v2", "education", "list" ] }, "body": { "mode": "raw", "raw": "{\n \"service\": \"jamb\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"successful\",\n \"message\": \"Request processed successfully.\",\n \"data\": [\n {\n \"name\": \"DStv\",\n \"category\": \"cable\",\n \"slug\": \"dstv\",\n \"status\": true,\n \"logo\": \"https://res.cloudinary.com/paybeta/image/upload/v1714827633/Provider/Cable/dstv.jpg\"\n },\n {\n \"name\": \"GOtv\",\n \"category\": \"cable\",\n \"slug\": \"gotv\",\n \"status\": true,\n \"logo\": \"https://res.cloudinary.com/paybeta/image/upload/v1714828100/Provider/Cable/gotv.png\"\n },\n {\n \"name\": \"StarTimes\",\n \"category\": \"cable\",\n \"slug\": \"startimes\",\n \"status\": true,\n \"logo\": \"https://res.cloudinary.com/paybeta/image/upload/v1714827913/Provider/Cable/startimes.jpg\"\n }\n ]\n}" } ] }, { "name": "Payment", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v2/education/purchase", "host": [ "{{baseUrl}}" ], "path": [ "v2", "education", "purchase" ] }, "body": { "mode": "raw", "raw": "{\n \"service\": \"jamb\",\n \"examCode\": \"UTMEWOM\",\n \"customerId\": \"529***4301\",\n \"amount\": 7600,\n \"reference\": \"{{$timestamp}}\"\n}", "options": { "raw": { "language": "json" } } }, "description": "Docs: https://docs.paybeta.ng/education-payment" }, "response": [] } ], "description": "## Education\n\n\n\nhttps://docs.paybeta.ng/education" }, { "name": "Buy Bulk Airtime API", "item": [ { "name": "Bulk airtime", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v2/bulk-airtime", "host": [ "{{baseUrl}}" ], "path": [ "v2", "bulk-airtime" ] }, "body": { "mode": "raw", "raw": "{\n \"reference\": \"PAYROLL-{{$timestamp}}\",\n \"description\": \"October staff airtime\",\n \"recipients\": [\n {\n \"biller\": \"mtn\",\n \"phone_number\": \"2348031234567\",\n \"amount\": 1000,\n \"reference\": \"STAFF-{{$timestamp}}-ADA\"\n },\n {\n \"biller\": \"glo\",\n \"phone_number\": \"2348051234567\",\n \"amount\": 500\n },\n {\n \"biller\": \"airtel\",\n \"phone_number\": \"08021234567\",\n \"amount\": 200\n }\n ]\n}", "options": { "raw": { "language": "json" } } }, "description": "Queue airtime for every recipient in the list. Saves `batch_id` / `reference` for the other requests.\n\n| Field | Required | Notes |\n|---|---|---|\n| reference | yes | your id for the whole request, unique per account |\n| description | no | your label, max 100 chars |\n| recipients | yes | 1 – 1,000 items |\n| recipients[].biller | yes | `mtn` · `glo` · `airtel` · `9mobile` |\n| recipients[].phone_number | yes | `2348031234567` (or `08031234567`) |\n| recipients[].amount | yes | NGN50 – NGN20,000 |\n| recipients[].reference | no | your id for this number; default `-` |\n\nDocs: https://docs.paybeta.ng/buy-bulk-airtime-bulk-airtime" }, "response": [ { "name": "Success (201)", "originalRequest": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v2/bulk-airtime", "host": [ "{{baseUrl}}" ], "path": [ "v2", "bulk-airtime" ] }, "body": { "mode": "raw", "raw": "{\n \"reference\": \"PAYROLL-{{$timestamp}}\",\n \"description\": \"October staff airtime\",\n \"recipients\": [\n {\n \"biller\": \"mtn\",\n \"phone_number\": \"2348031234567\",\n \"amount\": 1000,\n \"reference\": \"STAFF-{{$timestamp}}-ADA\"\n },\n {\n \"biller\": \"glo\",\n \"phone_number\": \"2348051234567\",\n \"amount\": 500\n },\n {\n \"biller\": \"airtel\",\n \"phone_number\": \"08021234567\",\n \"amount\": 200\n }\n ]\n}", "options": { "raw": { "language": "json" } } } }, "status": "Created", "code": 201, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"successful\",\n \"message\": \"Bulk airtime queued. 3 recipient(s) will be processed shortly.\",\n \"data\": {\n \"reference\": \"PAYROLL-OCT\",\n \"batch_id\": \"BLK-K3P9XQ2M7Z1A\",\n \"description\": \"October staff airtime\",\n \"status\": \"queued\",\n \"total_recipients\": 3,\n \"total_amount\": 1700,\n \"total_charge\": 1644,\n \"amount_charged\": 0,\n \"summary\": {\n \"successful\": 0,\n \"pending\": 0,\n \"failed\": 0,\n \"queued\": 3,\n \"cancelled\": 0\n },\n \"created_at\": \"2026-10-05T09:00:00+01:00\",\n \"started_at\": null,\n \"completed_at\": null,\n \"cancelled_at\": null,\n \"recipients\": [\n {\n \"row\": 1,\n \"reference\": \"STAFF-OCT-ADA\",\n \"biller\": \"mtn\",\n \"phone_number\": \"08031234567\",\n \"amount\": 1000,\n \"charged_amount\": null,\n \"status\": \"queued\",\n \"response_description\": null,\n \"transaction_id\": null,\n \"processed_at\": null\n },\n {\n \"row\": 2,\n \"reference\": \"PAYROLL-OCT-2\",\n \"biller\": \"glo\",\n \"phone_number\": \"08051234567\",\n \"amount\": 500,\n \"charged_amount\": null,\n \"status\": \"queued\",\n \"response_description\": null,\n \"transaction_id\": null,\n \"processed_at\": null\n },\n {\n \"row\": 3,\n \"reference\": \"PAYROLL-OCT-3\",\n \"biller\": \"airtel\",\n \"phone_number\": \"08021234567\",\n \"amount\": 200,\n \"charged_amount\": null,\n \"status\": \"queued\",\n \"response_description\": null,\n \"transaction_id\": null,\n \"processed_at\": null\n }\n ]\n }\n}" }, { "name": "Error (422)", "originalRequest": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v2/bulk-airtime", "host": [ "{{baseUrl}}" ], "path": [ "v2", "bulk-airtime" ] }, "body": { "mode": "raw", "raw": "{\n \"reference\": \"PAYROLL-{{$timestamp}}\",\n \"description\": \"October staff airtime\",\n \"recipients\": [\n {\n \"biller\": \"mtn\",\n \"phone_number\": \"2348031234567\",\n \"amount\": 1000,\n \"reference\": \"STAFF-{{$timestamp}}-ADA\"\n },\n {\n \"biller\": \"glo\",\n \"phone_number\": \"2348051234567\",\n \"amount\": 500\n },\n {\n \"biller\": \"airtel\",\n \"phone_number\": \"08021234567\",\n \"amount\": 200\n }\n ]\n}", "options": { "raw": { "language": "json" } } } }, "status": "Unprocessable Content", "code": 422, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"failed\",\n \"message\": \"Recipient 3 phone_number must be 234 followed by 10 digits (or 0 followed by 10 digits).\",\n \"errors\": {\n \"recipients.2.phone_number\": [\n \"Recipient 3 phone_number must be 234 followed by 10 digits (or 0 followed by 10 digits).\"\n ]\n }\n}" } ] }, { "name": "List bulk requests", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v2/bulk-airtime?status=completed&reference=PAYROLL-OCT&per_page=20&page=1", "host": [ "{{baseUrl}}" ], "path": [ "v2", "bulk-airtime" ], "query": [ { "key": "status", "value": "completed", "description": "queued, processing, completed, cancelled" }, { "key": "reference", "value": "PAYROLL-OCT", "description": "your request reference" }, { "key": "per_page", "value": "20", "description": "(Required) max 50" }, { "key": "page", "value": "1", "description": "(Required)" } ] }, "description": "Your bulk airtime requests, newest first (without the per-recipient list).\n\nDocs: https://docs.paybeta.ng/buy-bulk-airtime-list-bulk-requests" }, "response": [ { "name": "Success (200)", "originalRequest": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v2/bulk-airtime?status=completed&reference=PAYROLL-OCT&per_page=20&page=1", "host": [ "{{baseUrl}}" ], "path": [ "v2", "bulk-airtime" ], "query": [ { "key": "status", "value": "completed", "description": "queued, processing, completed, cancelled" }, { "key": "reference", "value": "PAYROLL-OCT", "description": "your request reference" }, { "key": "per_page", "value": "20", "description": "(Required) max 50" }, { "key": "page", "value": "1", "description": "(Required)" } ] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"successful\",\n \"message\": \"Bulk airtime requests retrieved successfully\",\n \"data\": [\n {\n \"reference\": \"PAYROLL-OCT\",\n \"batch_id\": \"BLK-K3P9XQ2M7Z1A\",\n \"description\": \"October staff airtime\",\n \"status\": \"completed\",\n \"total_recipients\": 3,\n \"total_amount\": 1700,\n \"total_charge\": 1644,\n \"amount_charged\": 1450,\n \"summary\": {\n \"successful\": 1,\n \"pending\": 1,\n \"failed\": 1,\n \"queued\": 0,\n \"cancelled\": 0\n },\n \"created_at\": \"2026-10-05T09:00:00+01:00\",\n \"started_at\": \"2026-10-05T09:00:02+01:00\",\n \"completed_at\": \"2026-10-05T09:00:14+01:00\",\n \"cancelled_at\": null\n }\n ],\n \"meta\": {\n \"current_page\": 1,\n \"last_page\": 1,\n \"per_page\": 20,\n \"total\": 1\n }\n}" } ] }, { "name": "Get bulk request", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v2/bulk-airtime/batchId", "host": [ "{{baseUrl}}" ], "path": [ "v2", "bulk-airtime", "batchId" ] }, "description": "One request with the result for every recipient. The URL accepts the `batch_id` (BLK-…) or your `reference`.\n\nDocs: https://docs.paybeta.ng/buy-bulk-airtime-get-bulk-request" }, "response": [ { "name": "Success (200)", "originalRequest": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v2/bulk-airtime/batchId", "host": [ "{{baseUrl}}" ], "path": [ "v2", "bulk-airtime", "batchId" ] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"successful\",\n \"message\": \"Bulk airtime request retrieved successfully\",\n \"data\": {\n \"reference\": \"PAYROLL-OCT\",\n \"batch_id\": \"BLK-K3P9XQ2M7Z1A\",\n \"description\": \"October staff airtime\",\n \"status\": \"completed\",\n \"total_recipients\": 3,\n \"total_amount\": 1700,\n \"total_charge\": 1644,\n \"amount_charged\": 1450,\n \"summary\": {\n \"successful\": 1,\n \"pending\": 1,\n \"failed\": 1,\n \"queued\": 0,\n \"cancelled\": 0\n },\n \"created_at\": \"2026-10-05T09:00:00+01:00\",\n \"started_at\": \"2026-10-05T09:00:02+01:00\",\n \"completed_at\": \"2026-10-05T09:00:14+01:00\",\n \"cancelled_at\": null,\n \"recipients\": [\n {\n \"row\": 1,\n \"reference\": \"STAFF-OCT-ADA\",\n \"biller\": \"mtn\",\n \"phone_number\": \"08031234567\",\n \"amount\": 1000,\n \"charged_amount\": 970,\n \"status\": \"delivered\",\n \"response_description\": \"TRANSACTION SUCCESSFUL\",\n \"transaction_id\": \"API-17619840121234567\",\n \"processed_at\": \"2026-10-05T09:00:12+01:00\"\n },\n {\n \"row\": 2,\n \"reference\": \"PAYROLL-OCT-2\",\n \"biller\": \"glo\",\n \"phone_number\": \"08051234567\",\n \"amount\": 500,\n \"charged_amount\": 480,\n \"status\": \"pending\",\n \"response_description\": \"TRANSACTION PENDING\",\n \"transaction_id\": \"API-17619840171234567\",\n \"processed_at\": \"2026-10-05T09:00:12+01:00\"\n },\n {\n \"row\": 3,\n \"reference\": \"PAYROLL-OCT-3\",\n \"biller\": \"airtel\",\n \"phone_number\": \"08021234567\",\n \"amount\": 200,\n \"charged_amount\": 194,\n \"status\": \"failed\",\n \"response_description\": \"Insufficient wallet balance. NGN194.00 was required but your balance was NGN50.00.\",\n \"transaction_id\": \"API-17619840221234567\",\n \"processed_at\": \"2026-10-05T09:00:12+01:00\"\n }\n ]\n }\n}" }, { "name": "Error (404)", "originalRequest": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v2/bulk-airtime/batchId", "host": [ "{{baseUrl}}" ], "path": [ "v2", "bulk-airtime", "batchId" ] } }, "status": "Not Found", "code": 404, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"failed\",\n \"message\": \"Bulk airtime request not found.\",\n \"data\": null\n}" } ] }, { "name": "Download report (CSV)", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v2/bulk-airtime/batchId/report", "host": [ "{{baseUrl}}" ], "path": [ "v2", "bulk-airtime", "batchId", "report" ] }, "description": "Per-recipient results as CSV: row, reference, biller, phone_number, amount, charged_amount, status, transaction_id, description, processed_at.\n\nDocs: https://docs.paybeta.ng/buy-bulk-airtime-download-report-csv" }, "response": [] }, { "name": "Cancel", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v2/bulk-airtime/batchId/cancel", "host": [ "{{baseUrl}}" ], "path": [ "v2", "bulk-airtime", "batchId", "cancel" ] }, "description": "Stop recipients that have not started yet (they become `cancelled`, not charged). Numbers already processed are not affected.\n\nDocs: https://docs.paybeta.ng/buy-bulk-airtime-cancel" }, "response": [ { "name": "Success (200)", "originalRequest": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v2/bulk-airtime/batchId/cancel", "host": [ "{{baseUrl}}" ], "path": [ "v2", "bulk-airtime", "batchId", "cancel" ] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"successful\",\n \"message\": \"Bulk request cancelled. 2 recipient(s) that had not started were skipped.\",\n \"data\": {\n \"reference\": \"PAYROLL-OCT\",\n \"batch_id\": \"BLK-K3P9XQ2M7Z1A\",\n \"description\": \"October staff airtime\",\n \"status\": \"cancelled\",\n \"total_recipients\": 3,\n \"total_amount\": 1700,\n \"total_charge\": 1644,\n \"amount_charged\": 970,\n \"summary\": {\n \"successful\": 1,\n \"pending\": 0,\n \"failed\": 0,\n \"queued\": 0,\n \"cancelled\": 2\n },\n \"created_at\": \"2026-10-05T09:00:00+01:00\",\n \"started_at\": null,\n \"completed_at\": null,\n \"cancelled_at\": \"2026-10-05T09:00:06+01:00\",\n \"recipients\": [\n {\n \"row\": 1,\n \"reference\": \"STAFF-OCT-ADA\",\n \"biller\": \"mtn\",\n \"phone_number\": \"08031234567\",\n \"amount\": 1000,\n \"charged_amount\": 970,\n \"status\": \"delivered\",\n \"response_description\": \"TRANSACTION SUCCESSFUL\",\n \"transaction_id\": \"API-17619840121234567\",\n \"processed_at\": \"2026-10-05T09:00:12+01:00\"\n },\n {\n \"row\": 2,\n \"reference\": \"PAYROLL-OCT-2\",\n \"biller\": \"glo\",\n \"phone_number\": \"08051234567\",\n \"amount\": 500,\n \"charged_amount\": null,\n \"status\": \"cancelled\",\n \"response_description\": \"Cancelled by merchant before processing.\",\n \"transaction_id\": null,\n \"processed_at\": null\n },\n {\n \"row\": 3,\n \"reference\": \"PAYROLL-OCT-3\",\n \"biller\": \"airtel\",\n \"phone_number\": \"08021234567\",\n \"amount\": 200,\n \"charged_amount\": null,\n \"status\": \"cancelled\",\n \"response_description\": \"Cancelled by merchant before processing.\",\n \"transaction_id\": null,\n \"processed_at\": null\n }\n ]\n }\n}" }, { "name": "Error (422)", "originalRequest": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v2/bulk-airtime/batchId/cancel", "host": [ "{{baseUrl}}" ], "path": [ "v2", "bulk-airtime", "batchId", "cancel" ] } }, "status": "Unprocessable Content", "code": 422, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"failed\",\n \"message\": \"This bulk request has already finished.\",\n \"data\": null\n}" } ] }, { "name": "Query one number", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v2/transaction/query", "host": [ "{{baseUrl}}" ], "path": [ "v2", "transaction", "query" ] }, "body": { "mode": "raw", "raw": "{\n \"reference\": \"{{batchReference}}-2\"\n}", "options": { "raw": { "language": "json" } } }, "description": "Status of one recipient, with its reference (default `-`).\n\nDocs: https://docs.paybeta.ng/buy-bulk-airtime-query-one-number" }, "response": [ { "name": "Success (200)", "originalRequest": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v2/transaction/query", "host": [ "{{baseUrl}}" ], "path": [ "v2", "transaction", "query" ] }, "body": { "mode": "raw", "raw": "{\n \"reference\": \"{{batchReference}}-2\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"successful\",\n \"message\": \"Your glo airtime payment is successful\",\n \"code\": \"00\",\n \"data\": {\n \"paymentStatus\": \"Delivered\",\n \"reference\": \"PAYROLL-OCT-2\",\n \"amount\": 500,\n \"amountPaid\": 480,\n \"product\": \"Glo Airtime\",\n \"customerId\": \"08051234567\",\n \"token\": \"0\",\n \"unit\": null,\n \"transactionId\": \"API-17619840171234567\",\n \"transactionDate\": \"2026-10-05T08:00:12.000000Z\"\n }\n}" } ] } ], "description": "## Buy Bulk Airtime\n\nTop 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.\n\n### Authentication\nEvery 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)\n\n### How it works\n1. 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.\n2. The priced total (`total_charge`, after your API commission) must be covered by your wallet balance.\n3. 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.\n4. 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`).\n5. The same phone number appearing twice in one request is topped up at least 5 minutes apart.\n\n\n### Rules\n- Up to 1,000 recipients per request; total of all amounts at least **NGN100**.\n- biller: `mtn`, `glo`, `airtel` or `9mobile` (`mtn_vtu` etc. also accepted).\n- `phone_number`: 234 + 10 digits (e.g. `2348031234567`); `08031234567` is also accepted.\n- amount: NGN50 – NGN20,000 per recipient; a phone number can receive at most NGN50,000 airtime per day.\n- `reference` (request): yours, required, **5-40** chars (letters, numbers, `.` `_` `-`), unique per account.\n- `recipients[].reference`: optional, 5-60 chars, unique. Defaults to `-` (e.g. `PAYROLL-OCT-2`). No reference may have been used for an earlier transaction.\n\n \n### Tracking a number\nEach 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`.\n\n### Statuses\nBatch: `queued` → `processing` → `completed`, or `cancelled`. Recipient: `queued`, `processing`, `delivered`, `pending`, `failed` (not charged), `reversed` (refunded), `cancelled` (skipped).\n\n### Response formats\n**Success Response**\n**HTTP Status:** `200 OK` (or `201 Created`)\n\n```js\n{\n \"status\": \"successful\",\n \"message\": \"Operation completed successfully.\",\n \"data\": {}\n}\n```\n\n### Error Response\n**HTTP Status:** `4xx`\n\n\n```js\n{\n \"status\": \"failed\",\n \"message\": \"Error description here.\",\n \"errors\": {\n \"field_name\": [\n \"Validation or constraint error message.\"\n ]\n }\n}\n```\n\n\n### HTTP Status Codes\n\n\n| Code | Status | Trigger / Description\n| --- | --- | --- |\n| **401** | Unauthorized | Missing or invalid API key |\n| **404** | Not Found | Requested resource not found |\n| **422** | Unprocessable Entity | Validation failed or action not allowed in current state |\n\nhttps://docs.paybeta.ng/buy-bulk-airtime" }, { "name": "Schedule Payments", "item": [ { "name": "Setup", "item": [ { "name": "Options", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v2/scheduled-payments/options", "host": [ "{{baseUrl}}" ], "path": [ "v2", "scheduled-payments", "options" ] }, "auth": { "type": "noauth" }, "description": "Services, billers, frequencies and meter types accepted by **Create**, plus `min_lead_minutes` and the timezone used for dates.\n\nDocs: https://docs.paybeta.ng/schedule-payments-options" }, "response": [ { "name": "Success (200)", "originalRequest": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v2/scheduled-payments/options", "host": [ "{{baseUrl}}" ], "path": [ "v2", "scheduled-payments", "options" ] }, "auth": { "type": "noauth" } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"success\": true,\n \"data\": {\n \"services\": [\n {\n \"key\": \"airtime\",\n \"label\": \"Airtime\",\n \"billers\": [\n {\n \"biller\": \"mtn_vtu\",\n \"name\": \"MTN Airtime\",\n \"has_bundles\": false\n }\n ]\n },\n {\n \"key\": \"data\",\n \"label\": \"Internet Data\",\n \"billers\": [\n {\n \"biller\": \"mtn_data\",\n \"name\": \"MTN Data\",\n \"has_bundles\": true\n }\n ]\n },\n {\n \"key\": \"cabletv\",\n \"label\": \"Cable TV\",\n \"billers\": [\n {\n \"biller\": \"dstv\",\n \"name\": \"DStv\",\n \"has_bundles\": true\n }\n ]\n },\n {\n \"key\": \"electricity\",\n \"label\": \"Electricity\",\n \"billers\": [\n {\n \"biller\": \"ikeja-electric\",\n \"name\": \"Ikeja Electric - IKEDC\",\n \"has_bundles\": false\n }\n ]\n }\n ],\n \"frequencies\": [\n {\n \"key\": \"once\",\n \"label\": \"One time\"\n },\n {\n \"key\": \"daily\",\n \"label\": \"Daily\"\n },\n {\n \"key\": \"weekly\",\n \"label\": \"Weekly\"\n },\n {\n \"key\": \"monthly\",\n \"label\": \"Monthly\"\n }\n ],\n \"meter_types\": [\n {\n \"key\": \"prepaid\",\n \"label\": \"Prepaid Meter\"\n },\n {\n \"key\": \"postpaid\",\n \"label\": \"Postpaid Meter\"\n }\n ],\n \"min_lead_minutes\": 10,\n \"timezone\": \"Africa/Lagos\"\n }\n}" } ] }, { "name": "Bundles", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v2/scheduled-payments/options", "host": [ "{{baseUrl}}" ], "path": [ "v2", "scheduled-payments", "options" ] }, "description": "Services, billers, frequencies and meter types accepted by **Create**, plus `min_lead_minutes` and the timezone used for dates.\n\nDocs: https://docs.paybeta.ng/schedule-payments-bundles" }, "response": [ { "name": "Success (200)", "originalRequest": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v2/scheduled-payments/options", "host": [ "{{baseUrl}}" ], "path": [ "v2", "scheduled-payments", "options" ] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"success\": true,\n \"data\": {\n \"services\": [\n {\n \"key\": \"airtime\",\n \"label\": \"Airtime\",\n \"billers\": [\n {\n \"biller\": \"mtn_vtu\",\n \"name\": \"MTN Airtime\",\n \"has_bundles\": false\n }\n ]\n },\n {\n \"key\": \"data\",\n \"label\": \"Internet Data\",\n \"billers\": [\n {\n \"biller\": \"mtn_data\",\n \"name\": \"MTN Data\",\n \"has_bundles\": true\n }\n ]\n },\n {\n \"key\": \"cabletv\",\n \"label\": \"Cable TV\",\n \"billers\": [\n {\n \"biller\": \"dstv\",\n \"name\": \"DStv\",\n \"has_bundles\": true\n }\n ]\n },\n {\n \"key\": \"electricity\",\n \"label\": \"Electricity\",\n \"billers\": [\n {\n \"biller\": \"ikeja-electric\",\n \"name\": \"Ikeja Electric - IKEDC\",\n \"has_bundles\": false\n }\n ]\n }\n ],\n \"frequencies\": [\n {\n \"key\": \"once\",\n \"label\": \"One time\"\n },\n {\n \"key\": \"daily\",\n \"label\": \"Daily\"\n },\n {\n \"key\": \"weekly\",\n \"label\": \"Weekly\"\n },\n {\n \"key\": \"monthly\",\n \"label\": \"Monthly\"\n }\n ],\n \"meter_types\": [\n {\n \"key\": \"prepaid\",\n \"label\": \"Prepaid Meter\"\n },\n {\n \"key\": \"postpaid\",\n \"label\": \"Postpaid Meter\"\n }\n ],\n \"min_lead_minutes\": 10,\n \"timezone\": \"Africa/Lagos\"\n }\n}" } ] } ] }, { "name": "Create", "item": [ { "name": "Create - Airtime (one time)", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v2/scheduled-payments", "host": [ "{{baseUrl}}" ], "path": [ "v2", "scheduled-payments" ] }, "body": { "mode": "raw", "raw": "{\n \"service\": \"airtime\",\n \"biller\": \"mtn_vtu\",\n \"customer_id\": \"08031234567\",\n \"amount\": 500,\n \"frequency\": \"once\",\n \"start_at\": \"{{startAt}}\",\n \"description\": \"Airtime for Dad\"\n}", "options": { "raw": { "language": "json" } } }, "description": "Schedule a one-time airtime top-up. `amount` is required (50 - 20,000).\n\nDocs: https://docs.paybeta.ng/schedule-payments-create-airtime-one-time" }, "response": [ { "name": "Success (201)", "originalRequest": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v2/scheduled-payments", "host": [ "{{baseUrl}}" ], "path": [ "v2", "scheduled-payments" ] }, "body": { "mode": "raw", "raw": "{\n \"service\": \"airtime\",\n \"biller\": \"mtn_vtu\",\n \"customer_id\": \"08031234567\",\n \"amount\": 500,\n \"frequency\": \"once\",\n \"start_at\": \"{{startAt}}\",\n \"description\": \"Airtime for Dad\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Created", "code": 201, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"success\": true,\n \"message\": \"Payment scheduled successfully.\",\n \"data\": {\n \"reference\": \"SCH-7F3K9QX2AB12\",\n \"service\": \"airtime\",\n \"service_label\": \"Airtime\",\n \"biller\": \"mtn_vtu\",\n \"biller_label\": \"MTN Airtime\",\n \"biller_code\": null,\n \"product_name\": \"MTN Airtime VTU\",\n \"customer_id\": \"08031234567\",\n \"customer_name\": null,\n \"amount\": 500,\n \"frequency\": \"once\",\n \"frequency_label\": \"One time\",\n \"starts_at\": \"2026-10-10T09:00:00+01:00\",\n \"ends_at\": null,\n \"next_run_at\": \"2026-10-10T09:00:00+01:00\",\n \"status\": \"active\",\n \"failure_reason\": null,\n \"can_retry\": false,\n \"can_cancel\": true,\n \"can_pause\": true,\n \"can_pay_now\": true,\n \"can_resume\": false,\n \"resume_needs_start_at\": false,\n \"paused_at\": null,\n \"can_edit\": true,\n \"archived\": false,\n \"can_reactivate\": false,\n \"can_delete\": false,\n \"reactivation_needs_start_at\": false,\n \"cancelled_at\": null,\n \"total_runs\": 0,\n \"last_run_at\": null,\n \"last_run\": null,\n \"description\": \"Airtime for Dad\",\n \"summary\": \"Airtime scheduled for the beneficiary 08031234567\",\n \"created_at\": \"2026-10-05T12:00:00+01:00\"\n }\n}" } ] }, { "name": "Create - Data (monthly)", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v2/scheduled-payments", "host": [ "{{baseUrl}}" ], "path": [ "v2", "scheduled-payments" ] }, "body": { "mode": "raw", "raw": "{\n \"service\": \"data\",\n \"biller\": \"mtn_data\",\n \"customer_id\": \"08031234567\",\n \"code\": \"mtn-1gb-30days\",\n \"frequency\": \"monthly\",\n \"start_at\": \"{{startAt}}\",\n \"ends_at\": \"{{endsAt}}\",\n \"description\": \"Data for Mum\"\n}", "options": { "raw": { "language": "json" } } }, "description": "Schedule a recurring data bundle. `code` is the bundle code from **Bundles**; the amount comes from the bundle price. `ends_at` is optional.\n\nDocs: https://docs.paybeta.ng/schedule-payments-create-data-monthly" }, "response": [ { "name": "Success (201)", "originalRequest": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v2/scheduled-payments", "host": [ "{{baseUrl}}" ], "path": [ "v2", "scheduled-payments" ] }, "body": { "mode": "raw", "raw": "{\n \"service\": \"data\",\n \"biller\": \"mtn_data\",\n \"customer_id\": \"08031234567\",\n \"code\": \"mtn-1gb-30days\",\n \"frequency\": \"monthly\",\n \"start_at\": \"{{startAt}}\",\n \"ends_at\": \"{{endsAt}}\",\n \"description\": \"Data for Mum\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Created", "code": 201, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"success\": true,\n \"message\": \"Payment scheduled successfully.\",\n \"data\": {\n \"reference\": \"SCH-7F3K9QX2AB12\",\n \"service\": \"data\",\n \"service_label\": \"Internet Data\",\n \"biller\": \"mtn_data\",\n \"biller_label\": \"MTN Data\",\n \"biller_code\": \"mtn-1gb-30days\",\n \"product_name\": \"MTN 1GB - 30 Days\",\n \"customer_id\": \"08031234567\",\n \"customer_name\": null,\n \"amount\": 1000,\n \"frequency\": \"monthly\",\n \"frequency_label\": \"Monthly\",\n \"starts_at\": \"2026-11-01T09:00:00+01:00\",\n \"ends_at\": null,\n \"next_run_at\": \"2026-11-01T09:00:00+01:00\",\n \"status\": \"active\",\n \"failure_reason\": null,\n \"can_retry\": false,\n \"can_cancel\": true,\n \"can_pause\": true,\n \"can_pay_now\": true,\n \"can_resume\": false,\n \"resume_needs_start_at\": false,\n \"paused_at\": null,\n \"can_edit\": true,\n \"archived\": false,\n \"can_reactivate\": false,\n \"can_delete\": false,\n \"reactivation_needs_start_at\": false,\n \"cancelled_at\": null,\n \"total_runs\": 0,\n \"last_run_at\": null,\n \"last_run\": null,\n \"description\": \"Data for Mum\",\n \"summary\": \"Internet Data scheduled for the beneficiary 08031234567\",\n \"created_at\": \"2026-10-05T12:00:00+01:00\"\n }\n}" }, { "name": "Error (422)", "originalRequest": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v2/scheduled-payments", "host": [ "{{baseUrl}}" ], "path": [ "v2", "scheduled-payments" ] }, "body": { "mode": "raw", "raw": "{\n \"service\": \"data\",\n \"biller\": \"mtn_data\",\n \"customer_id\": \"08031234567\",\n \"code\": \"mtn-1gb-30days\",\n \"frequency\": \"monthly\",\n \"start_at\": \"{{startAt}}\",\n \"ends_at\": \"{{endsAt}}\",\n \"description\": \"Data for Mum\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Unprocessable Content", "code": 422, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"success\": false,\n \"message\": \"The schedule date must be at least 10 minutes from now.\",\n \"errors\": {\n \"start_at\": [\n \"The schedule date must be at least 10 minutes from now.\"\n ]\n }\n}" } ] }, { "name": "Create - Cable TV (monthly)", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v2/scheduled-payments", "host": [ "{{baseUrl}}" ], "path": [ "v2", "scheduled-payments" ] }, "body": { "mode": "raw", "raw": "{\n \"service\": \"cabletv\",\n \"biller\": \"dstv\",\n \"customer_id\": \"7027914329\",\n \"code\": \"dstv-padi\",\n \"frequency\": \"monthly\",\n \"start_at\": \"{{startAt}}\"\n}", "options": { "raw": { "language": "json" } } }, "description": "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.\n\nDocs: https://docs.paybeta.ng/schedule-payments-create-cable-tv-monthly" }, "response": [] }, { "name": "Create - Electricity (weekly)", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v2/scheduled-payments", "host": [ "{{baseUrl}}" ], "path": [ "v2", "scheduled-payments" ] }, "body": { "mode": "raw", "raw": "{\n \"service\": \"electricity\",\n \"biller\": \"ikeja-electric\",\n \"customer_id\": \"45067198783\",\n \"code\": \"prepaid\",\n \"amount\": 5000,\n \"frequency\": \"weekly\",\n \"start_at\": \"{{startAt}}\"\n}", "options": { "raw": { "language": "json" } } }, "description": "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.\n\nDocs: https://docs.paybeta.ng/schedule-payments-create-electricity-weekly" }, "response": [] } ], "description": "## Create\n\n> **Body**\n\n| Field | Required | Notes |\n|---|---|---|\n| service | yes | `airtime` · `data` · `cabletv` · `electricity` |\n| biller | yes | from **Options** |\n| customer_id | yes | phone number, smartcard number or meter number |\n| code | data / cabletv / electricity | bundle code, or meter type for electricity |\n| amount | airtime / electricity | ignored for data & cable TV (bundle price is used) |\n| frequency | yes | `once` · `daily` · `weekly` · `monthly` |\n| start_at | yes | first run, ≥ 10 minutes from now |\n| ends_at | no | recurring only |\n| description | no | your label, max 100 chars |\n\nEach request in this folder saves the new schedule's reference to `scheduleReference`.\n\n**Body**\n\n| Field | Required | Notes |\n|---|---|---|\n| service | yes | `airtime` · `data` · `cabletv` · `electricity` |\n| biller | yes | from **Options** |\n| customer_id | yes | phone number, smartcard number or meter number |\n| code | data / cabletv / electricity | bundle code, or meter type for electricity |\n| amount | airtime / electricity | ignored for data & cable TV (bundle price is used) |\n| frequency | yes | `once` · `daily` · `weekly` · `monthly` |\n| start_at | yes | first run, ≥ 10 minutes from now |\n| ends_at | no | recurring only |\n| description | no | your label, max 100 chars |\n\nEach request in this folder saves the new schedule's reference to `scheduleReference`.\n\nhttps://docs.paybeta.ng/create" }, { "name": "Manage", "item": [ { "name": "List schedules", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v2/scheduled-payments?status=active&per_page=20&page=1", "host": [ "{{baseUrl}}" ], "path": [ "v2", "scheduled-payments" ], "query": [ { "key": "status", "value": "active", "description": "active, processing, completed, failed, paused, cancelled (or archived)" }, { "key": "per_page", "value": "20", "description": "(Required) max 50" }, { "key": "page", "value": "1", "description": "(Required)" } ] }, "description": "Paginated list, newest first. Without `status`, cancelled (archived) schedules are hidden.\n\nDocs: https://docs.paybeta.ng/schedule-payments-list-schedules" }, "response": [ { "name": "Success (200)", "originalRequest": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v2/scheduled-payments?status=active&per_page=20&page=1", "host": [ "{{baseUrl}}" ], "path": [ "v2", "scheduled-payments" ], "query": [ { "key": "status", "value": "active", "description": "active, processing, completed, failed, paused, cancelled (or archived)" }, { "key": "per_page", "value": "20", "description": "(Required) max 50" }, { "key": "page", "value": "1", "description": "(Required)" } ] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"successful\",\n \"message\": \"Scheduled payments retrieved successfully\",\n \"data\": [\n {\n \"reference\": \"SCH-7F3K9QX2AB12\",\n \"service\": \"data\",\n \"service_label\": \"Internet Data\",\n \"biller\": \"mtn_data\",\n \"biller_label\": \"MTN Data\",\n \"biller_code\": \"mtn-1gb-30days\",\n \"product_name\": \"MTN 1GB - 30 Days\",\n \"customer_id\": \"08031234567\",\n \"customer_name\": null,\n \"amount\": 1000,\n \"frequency\": \"monthly\",\n \"frequency_label\": \"Monthly\",\n \"starts_at\": \"2026-11-01T09:00:00+01:00\",\n \"ends_at\": null,\n \"next_run_at\": \"2026-11-01T09:00:00+01:00\",\n \"status\": \"active\",\n \"failure_reason\": null,\n \"can_retry\": false,\n \"can_cancel\": true,\n \"can_pause\": true,\n \"can_pay_now\": true,\n \"can_resume\": false,\n \"resume_needs_start_at\": false,\n \"paused_at\": null,\n \"can_edit\": true,\n \"archived\": false,\n \"can_reactivate\": false,\n \"can_delete\": false,\n \"reactivation_needs_start_at\": false,\n \"cancelled_at\": null,\n \"total_runs\": 0,\n \"last_run_at\": null,\n \"last_run\": null,\n \"description\": \"Data for Mum\",\n \"summary\": \"Internet Data scheduled for the beneficiary 08031234567\",\n \"created_at\": \"2026-10-05T12:00:00+01:00\"\n }\n ],\n \"meta\": {\n \"current_page\": 1,\n \"last_page\": 1,\n \"per_page\": 20,\n \"total\": 1\n }\n}" } ] }, { "name": "Get schedule", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v2/scheduled-payments/:schedulereference", "host": [ "{{baseUrl}}" ], "path": [ "v2", "scheduled-payments", ":schedulereference" ], "variable": [ { "key": "schedulereference", "value": "SCH-9SC5QIH5GNLC", "description": "" } ] }, "description": "One schedule including its full run history (`runs`).\n\nDocs: https://docs.paybeta.ng/schedule-payments-get-schedule" }, "response": [ { "name": "Success (200)", "originalRequest": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v2/scheduled-payments/:schedulereference", "host": [ "{{baseUrl}}" ], "path": [ "v2", "scheduled-payments", ":schedulereference" ], "variable": [ { "key": "schedulereference", "value": "SCH-9SC5QIH5GNLC", "description": "" } ] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"successful\",\n \"data\": {\n \"reference\": null,\n \"schedule_id\": \"SCH-9SC5QIH5GNLC\",\n \"service\": \"airtime\",\n \"service_label\": \"Airtime\",\n \"biller\": \"mtn_vtu\",\n \"biller_label\": \"MTN Airtime\",\n \"biller_code\": null,\n \"product_name\": \"MTN Airtime VTU\",\n \"customer_id\": \"08123456780\",\n \"customer_name\": null,\n \"amount\": 100,\n \"frequency\": \"once\",\n \"frequency_label\": \"One time\",\n \"starts_at\": \"2026-10-05T03:40:00+01:00\",\n \"ends_at\": null,\n \"next_run_at\": null,\n \"status\": \"completed\",\n \"failure_reason\": null,\n \"can_retry\": false,\n \"can_cancel\": false,\n \"can_pause\": false,\n \"can_pay_now\": false,\n \"can_resume\": false,\n \"resume_needs_start_at\": false,\n \"paused_at\": null,\n \"can_edit\": false,\n \"archived\": false,\n \"can_reactivate\": false,\n \"can_delete\": false,\n \"reactivation_needs_start_at\": false,\n \"cancelled_at\": null,\n \"total_runs\": 1,\n \"last_run_at\": \"2026-10-05T03:40:47+01:00\",\n \"last_run\": {\n \"cycle\": 1,\n \"attempt\": 1,\n \"trigger\": \"auto\",\n \"due_at\": \"2026-10-05T03:40:00+01:00\",\n \"status\": \"delivered\",\n \"response_description\": \"TRANSACTION SUCCESSFUL\",\n \"transaction_id\": \"API-1791168046493950345\",\n \"transaction_reference\": \"SCH-9SC5QIH5GNLC-B9AP46D6\",\n \"amount\": 100,\n \"charged_amount\": 97,\n \"token\": null,\n \"started_at\": \"2026-10-05T03:40:44+01:00\",\n \"finished_at\": \"2026-10-05T03:40:47+01:00\"\n },\n \"description\": \"Airtime for Dad\",\n \"summary\": \"Airtime scheduled for the beneficiary 08138539550\",\n \"created_at\": \"2026-10-05T03:25:41+01:00\",\n \"runs\": [\n {\n \"cycle\": 1,\n \"attempt\": 1,\n \"trigger\": \"auto\",\n \"due_at\": \"2026-10-05T03:40:00+01:00\",\n \"status\": \"delivered\",\n \"response_description\": \"TRANSACTION SUCCESSFUL\",\n \"transaction_id\": \"API-1791168046493950345\",\n \"transaction_reference\": \"SCH-9SC5QIH5GNLC-B9AP46D6\",\n \"amount\": 100,\n \"charged_amount\": 97,\n \"token\": null,\n \"started_at\": \"2026-10-05T03:40:44+01:00\",\n \"finished_at\": \"2026-10-05T03:40:47+01:00\"\n }\n ]\n }\n}" }, { "name": "Error (404)", "originalRequest": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v2/scheduled-payments/:schedulereference", "host": [ "{{baseUrl}}" ], "path": [ "v2", "scheduled-payments", ":schedulereference" ], "variable": [ { "key": "schedulereference", "value": "SCH-9SC5QIH5GNLC", "description": "" } ] } }, "status": "Not Found", "code": 404, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"success\": false,\n \"message\": \"Schedule not found.\"\n}" } ] }, { "name": "Update schedule", "request": { "method": "PUT", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v2/scheduled-payments/:scheduleReference", "host": [ "{{baseUrl}}" ], "path": [ "v2", "scheduled-payments", ":scheduleReference" ], "variable": [ { "key": "scheduleReference", "value": "SCH-9SC5QIH5GNLC", "description": "" } ] }, "body": { "mode": "raw", "raw": "{\n \"service\": \"data\",\n \"biller\": \"mtn_data\",\n \"customer_id\": \"08031234567\",\n \"code\": \"mtn-2gb-30days\",\n \"frequency\": \"monthly\",\n \"start_at\": \"{{startAt}}\"\n}", "options": { "raw": { "language": "json" } } }, "description": "Edit a schedule before its first run (`can_edit: true`). Same body and rules as **Create**; the schedule restarts from the new `start_at`.\n\nDocs: https://docs.paybeta.ng/schedule-payments-update-schedule" }, "response": [ { "name": "Success (200)", "originalRequest": { "method": "PUT", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v2/scheduled-payments/:scheduleReference", "host": [ "{{baseUrl}}" ], "path": [ "v2", "scheduled-payments", ":scheduleReference" ], "variable": [ { "key": "scheduleReference", "value": "SCH-9SC5QIH5GNLC", "description": "" } ] }, "body": { "mode": "raw", "raw": "{\n \"service\": \"data\",\n \"biller\": \"mtn_data\",\n \"customer_id\": \"08031234567\",\n \"code\": \"mtn-2gb-30days\",\n \"frequency\": \"monthly\",\n \"start_at\": \"{{startAt}}\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"success\": true,\n \"message\": \"Schedule updated successfully.\",\n \"data\": {\n \"reference\": \"SCH-7F3K9QX2AB12\",\n \"service\": \"data\",\n \"service_label\": \"Internet Data\",\n \"biller\": \"mtn_data\",\n \"biller_label\": \"MTN Data\",\n \"biller_code\": \"mtn-1gb-30days\",\n \"product_name\": \"MTN 1GB - 30 Days\",\n \"customer_id\": \"08031234567\",\n \"customer_name\": null,\n \"amount\": 1000,\n \"frequency\": \"monthly\",\n \"frequency_label\": \"Monthly\",\n \"starts_at\": \"2026-11-01T09:00:00+01:00\",\n \"ends_at\": null,\n \"next_run_at\": \"2026-11-01T09:00:00+01:00\",\n \"status\": \"active\",\n \"failure_reason\": null,\n \"can_retry\": false,\n \"can_cancel\": true,\n \"can_pause\": true,\n \"can_pay_now\": true,\n \"can_resume\": false,\n \"resume_needs_start_at\": false,\n \"paused_at\": null,\n \"can_edit\": true,\n \"archived\": false,\n \"can_reactivate\": false,\n \"can_delete\": false,\n \"reactivation_needs_start_at\": false,\n \"cancelled_at\": null,\n \"total_runs\": 0,\n \"last_run_at\": null,\n \"last_run\": null,\n \"description\": \"Data for Mum\",\n \"summary\": \"Internet Data scheduled for the beneficiary 08031234567\",\n \"created_at\": \"2026-10-05T12:00:00+01:00\"\n }\n}" }, { "name": "Error (404)", "originalRequest": { "method": "PUT", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v2/scheduled-payments/:scheduleReference", "host": [ "{{baseUrl}}" ], "path": [ "v2", "scheduled-payments", ":scheduleReference" ], "variable": [ { "key": "scheduleReference", "value": "SCH-9SC5QIH5GNLC", "description": "" } ] }, "body": { "mode": "raw", "raw": "{\n \"service\": \"data\",\n \"biller\": \"mtn_data\",\n \"customer_id\": \"08031234567\",\n \"code\": \"mtn-2gb-30days\",\n \"frequency\": \"monthly\",\n \"start_at\": \"{{startAt}}\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Not Found", "code": 404, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"success\": false,\n \"message\": \"Schedule not found.\"\n}" }, { "name": "Error (422)", "originalRequest": { "method": "PUT", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v2/scheduled-payments/:scheduleReference", "host": [ "{{baseUrl}}" ], "path": [ "v2", "scheduled-payments", ":scheduleReference" ], "variable": [ { "key": "scheduleReference", "value": "SCH-9SC5QIH5GNLC", "description": "" } ] }, "body": { "mode": "raw", "raw": "{\n \"service\": \"data\",\n \"biller\": \"mtn_data\",\n \"customer_id\": \"08031234567\",\n \"code\": \"mtn-2gb-30days\",\n \"frequency\": \"monthly\",\n \"start_at\": \"{{startAt}}\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Unprocessable Content", "code": 422, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"success\": false,\n \"message\": \"This schedule can no longer be edited — it has already started running.\",\n \"errors\": {\n \"schedule\": [\n \"This schedule can no longer be edited — it has already started running.\"\n ]\n }\n}" } ] }, { "name": "Pay now", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v2/scheduled-payments/scheduleReference/pay-now", "host": [ "{{baseUrl}}" ], "path": [ "v2", "scheduled-payments", "scheduleReference", "pay-now" ] }, "description": "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.\n\nDocs: https://docs.paybeta.ng/schedule-payments-pay-now" }, "response": [ { "name": "Success (200)", "originalRequest": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v2/scheduled-payments/scheduleReference/pay-now", "host": [ "{{baseUrl}}" ], "path": [ "v2", "scheduled-payments", "scheduleReference", "pay-now" ] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"success\": true,\n \"message\": \"Payment started. Your schedule dates are unchanged. Check the schedule shortly for the result.\",\n \"data\": {\n \"reference\": \"SCH-7F3K9QX2AB12\",\n \"service\": \"data\",\n \"service_label\": \"Internet Data\",\n \"biller\": \"mtn_data\",\n \"biller_label\": \"MTN Data\",\n \"biller_code\": \"mtn-1gb-30days\",\n \"product_name\": \"MTN 1GB - 30 Days\",\n \"customer_id\": \"08031234567\",\n \"customer_name\": null,\n \"amount\": 1000,\n \"frequency\": \"monthly\",\n \"frequency_label\": \"Monthly\",\n \"starts_at\": \"2026-11-01T09:00:00+01:00\",\n \"ends_at\": null,\n \"next_run_at\": \"2026-11-01T09:00:00+01:00\",\n \"status\": \"active\",\n \"failure_reason\": null,\n \"can_retry\": false,\n \"can_cancel\": true,\n \"can_pause\": true,\n \"can_pay_now\": true,\n \"can_resume\": false,\n \"resume_needs_start_at\": false,\n \"paused_at\": null,\n \"can_edit\": true,\n \"archived\": false,\n \"can_reactivate\": false,\n \"can_delete\": false,\n \"reactivation_needs_start_at\": false,\n \"cancelled_at\": null,\n \"total_runs\": 0,\n \"last_run_at\": null,\n \"last_run\": null,\n \"description\": \"Data for Mum\",\n \"summary\": \"Internet Data scheduled for the beneficiary 08031234567\",\n \"created_at\": \"2026-10-05T12:00:00+01:00\"\n }\n}" }, { "name": "Error (422)", "originalRequest": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v2/scheduled-payments/scheduleReference/pay-now", "host": [ "{{baseUrl}}" ], "path": [ "v2", "scheduled-payments", "scheduleReference", "pay-now" ] } }, "status": "Unprocessable Content", "code": 422, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"success\": false,\n \"message\": \"A payment for this schedule is already processing. Please wait a moment.\",\n \"errors\": {\n \"schedule\": [\n \"A payment for this schedule is already processing. Please wait a moment.\"\n ]\n }\n}" } ] }, { "name": "Retry failed run", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v2/scheduled-payments/scheduleReference/retry", "host": [ "{{baseUrl}}" ], "path": [ "v2", "scheduled-payments", "scheduleReference", "retry" ] }, "description": "Re-run a `failed` schedule now (e.g. after funding your wallet). On success a recurring schedule moves on to its next future date.\n\nDocs: https://docs.paybeta.ng/schedule-payments-retry-failed-run" }, "response": [ { "name": "Success (200)", "originalRequest": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v2/scheduled-payments/scheduleReference/retry", "host": [ "{{baseUrl}}" ], "path": [ "v2", "scheduled-payments", "scheduleReference", "retry" ] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"success\": true,\n \"message\": \"Retry started. Check the schedule shortly for the result.\",\n \"data\": {\n \"reference\": \"SCH-7F3K9QX2AB12\",\n \"service\": \"data\",\n \"service_label\": \"Internet Data\",\n \"biller\": \"mtn_data\",\n \"biller_label\": \"MTN Data\",\n \"biller_code\": \"mtn-1gb-30days\",\n \"product_name\": \"MTN 1GB - 30 Days\",\n \"customer_id\": \"08031234567\",\n \"customer_name\": null,\n \"amount\": 1000,\n \"frequency\": \"monthly\",\n \"frequency_label\": \"Monthly\",\n \"starts_at\": \"2026-11-01T09:00:00+01:00\",\n \"ends_at\": null,\n \"next_run_at\": \"2026-11-01T09:00:00+01:00\",\n \"status\": \"processing\",\n \"failure_reason\": null,\n \"can_retry\": false,\n \"can_cancel\": true,\n \"can_pause\": true,\n \"can_pay_now\": true,\n \"can_resume\": false,\n \"resume_needs_start_at\": false,\n \"paused_at\": null,\n \"can_edit\": true,\n \"archived\": false,\n \"can_reactivate\": false,\n \"can_delete\": false,\n \"reactivation_needs_start_at\": false,\n \"cancelled_at\": null,\n \"total_runs\": 0,\n \"last_run_at\": null,\n \"last_run\": null,\n \"description\": \"Data for Mum\",\n \"summary\": \"Internet Data scheduled for the beneficiary 08031234567\",\n \"created_at\": \"2026-10-05T12:00:00+01:00\"\n }\n}" }, { "name": "Error (422)", "originalRequest": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v2/scheduled-payments/scheduleReference/retry", "host": [ "{{baseUrl}}" ], "path": [ "v2", "scheduled-payments", "scheduleReference", "retry" ] } }, "status": "Unprocessable Content", "code": 422, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"success\": false,\n \"message\": \"Only failed schedules can be retried.\",\n \"errors\": {\n \"schedule\": [\n \"Only failed schedules can be retried.\"\n ]\n }\n}" } ] }, { "name": "Pause", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v2/scheduled-payments/scheduleReference/pause", "host": [ "{{baseUrl}}" ], "path": [ "v2", "scheduled-payments", "scheduleReference", "pause" ] }, "description": "Put a schedule on hold. Nothing is charged until it is resumed.\n\nDocs: https://docs.paybeta.ng/schedule-payments-pause" }, "response": [ { "name": "Success (200)", "originalRequest": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v2/scheduled-payments/scheduleReference/pause", "host": [ "{{baseUrl}}" ], "path": [ "v2", "scheduled-payments", "scheduleReference", "pause" ] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"success\": true,\n \"message\": \"Schedule paused. No payments will be made until you resume it.\",\n \"data\": {\n \"reference\": \"SCH-7F3K9QX2AB12\",\n \"service\": \"data\",\n \"service_label\": \"Internet Data\",\n \"biller\": \"mtn_data\",\n \"biller_label\": \"MTN Data\",\n \"biller_code\": \"mtn-1gb-30days\",\n \"product_name\": \"MTN 1GB - 30 Days\",\n \"customer_id\": \"08031234567\",\n \"customer_name\": null,\n \"amount\": 1000,\n \"frequency\": \"monthly\",\n \"frequency_label\": \"Monthly\",\n \"starts_at\": \"2026-11-01T09:00:00+01:00\",\n \"ends_at\": null,\n \"next_run_at\": null,\n \"status\": \"paused\",\n \"failure_reason\": null,\n \"can_retry\": false,\n \"can_cancel\": true,\n \"can_pause\": false,\n \"can_pay_now\": true,\n \"can_resume\": true,\n \"resume_needs_start_at\": false,\n \"paused_at\": \"2026-10-05T12:30:00+01:00\",\n \"can_edit\": true,\n \"archived\": false,\n \"can_reactivate\": false,\n \"can_delete\": false,\n \"reactivation_needs_start_at\": false,\n \"cancelled_at\": null,\n \"total_runs\": 0,\n \"last_run_at\": null,\n \"last_run\": null,\n \"description\": \"Data for Mum\",\n \"summary\": \"Internet Data scheduled for the beneficiary 08031234567\",\n \"created_at\": \"2026-10-05T12:00:00+01:00\"\n }\n}" } ] }, { "name": "Resume", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v2/scheduled-payments/scheduleReference/resume", "host": [ "{{baseUrl}}" ], "path": [ "v2", "scheduled-payments", "scheduleReference", "resume" ] }, "body": { "mode": "raw", "raw": "{\n \"start_at\": \"{{startAt}}\"\n}", "options": { "raw": { "language": "json" } } }, "description": "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`.\n\nDocs: https://docs.paybeta.ng/schedule-payments-resume" }, "response": [ { "name": "Success (200)", "originalRequest": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v2/scheduled-payments/scheduleReference/resume", "host": [ "{{baseUrl}}" ], "path": [ "v2", "scheduled-payments", "scheduleReference", "resume" ] }, "body": { "mode": "raw", "raw": "{\n \"start_at\": \"{{startAt}}\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"success\": true,\n \"message\": \"Schedule resumed.\",\n \"data\": {\n \"reference\": \"SCH-7F3K9QX2AB12\",\n \"service\": \"data\",\n \"service_label\": \"Internet Data\",\n \"biller\": \"mtn_data\",\n \"biller_label\": \"MTN Data\",\n \"biller_code\": \"mtn-1gb-30days\",\n \"product_name\": \"MTN 1GB - 30 Days\",\n \"customer_id\": \"08031234567\",\n \"customer_name\": null,\n \"amount\": 1000,\n \"frequency\": \"monthly\",\n \"frequency_label\": \"Monthly\",\n \"starts_at\": \"2026-11-01T09:00:00+01:00\",\n \"ends_at\": null,\n \"next_run_at\": \"2026-11-01T09:00:00+01:00\",\n \"status\": \"active\",\n \"failure_reason\": null,\n \"can_retry\": false,\n \"can_cancel\": true,\n \"can_pause\": true,\n \"can_pay_now\": true,\n \"can_resume\": false,\n \"resume_needs_start_at\": false,\n \"paused_at\": null,\n \"can_edit\": true,\n \"archived\": false,\n \"can_reactivate\": false,\n \"can_delete\": false,\n \"reactivation_needs_start_at\": false,\n \"cancelled_at\": null,\n \"total_runs\": 0,\n \"last_run_at\": null,\n \"last_run\": null,\n \"description\": \"Data for Mum\",\n \"summary\": \"Internet Data scheduled for the beneficiary 08031234567\",\n \"created_at\": \"2026-10-05T12:00:00+01:00\"\n }\n}" } ] }, { "name": "Cancel (archive)", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v2/scheduled-payments/scheduleReference/cancel", "host": [ "{{baseUrl}}" ], "path": [ "v2", "scheduled-payments", "scheduleReference", "cancel" ] }, "description": "Stop an `active`, `failed` or `paused` schedule and move it to the archive (`status: cancelled`). It can be re-enabled later.\n\nDocs: https://docs.paybeta.ng/schedule-payments-cancel-archive" }, "response": [ { "name": "Success (200)", "originalRequest": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v2/scheduled-payments/scheduleReference/cancel", "host": [ "{{baseUrl}}" ], "path": [ "v2", "scheduled-payments", "scheduleReference", "cancel" ] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"success\": true,\n \"message\": \"Schedule cancelled and moved to archive.\",\n \"data\": {\n \"reference\": \"SCH-7F3K9QX2AB12\",\n \"service\": \"data\",\n \"service_label\": \"Internet Data\",\n \"biller\": \"mtn_data\",\n \"biller_label\": \"MTN Data\",\n \"biller_code\": \"mtn-1gb-30days\",\n \"product_name\": \"MTN 1GB - 30 Days\",\n \"customer_id\": \"08031234567\",\n \"customer_name\": null,\n \"amount\": 1000,\n \"frequency\": \"monthly\",\n \"frequency_label\": \"Monthly\",\n \"starts_at\": \"2026-11-01T09:00:00+01:00\",\n \"ends_at\": null,\n \"next_run_at\": null,\n \"status\": \"cancelled\",\n \"failure_reason\": null,\n \"can_retry\": false,\n \"can_cancel\": true,\n \"can_pause\": true,\n \"can_pay_now\": true,\n \"can_resume\": false,\n \"resume_needs_start_at\": false,\n \"paused_at\": null,\n \"can_edit\": true,\n \"archived\": true,\n \"can_reactivate\": true,\n \"can_delete\": true,\n \"reactivation_needs_start_at\": false,\n \"cancelled_at\": \"2026-10-05T12:30:00+01:00\",\n \"total_runs\": 0,\n \"last_run_at\": null,\n \"last_run\": null,\n \"description\": \"Data for Mum\",\n \"summary\": \"Internet Data scheduled for the beneficiary 08031234567\",\n \"created_at\": \"2026-10-05T12:00:00+01:00\"\n }\n}" } ] }, { "name": "Re-enable", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v2/scheduled-payments/scheduleReference/reactivate", "host": [ "{{baseUrl}}" ], "path": [ "v2", "scheduled-payments", "scheduleReference", "reactivate" ] }, "body": { "mode": "raw", "raw": "{\n \"start_at\": \"{{startAt}}\"\n}", "options": { "raw": { "language": "json" } } }, "description": "Bring a `cancelled` schedule back to `active`. Same date rules as **Resume** (`reactivation_needs_start_at`). Counts towards the 20 open schedules limit.\n\nDocs: https://docs.paybeta.ng/schedule-payments-re-enable" }, "response": [ { "name": "Success (200)", "originalRequest": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v2/scheduled-payments/scheduleReference/reactivate", "host": [ "{{baseUrl}}" ], "path": [ "v2", "scheduled-payments", "scheduleReference", "reactivate" ] }, "body": { "mode": "raw", "raw": "{\n \"start_at\": \"{{startAt}}\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"success\": true,\n \"message\": \"Schedule re-enabled.\",\n \"data\": {\n \"reference\": \"SCH-7F3K9QX2AB12\",\n \"service\": \"data\",\n \"service_label\": \"Internet Data\",\n \"biller\": \"mtn_data\",\n \"biller_label\": \"MTN Data\",\n \"biller_code\": \"mtn-1gb-30days\",\n \"product_name\": \"MTN 1GB - 30 Days\",\n \"customer_id\": \"08031234567\",\n \"customer_name\": null,\n \"amount\": 1000,\n \"frequency\": \"monthly\",\n \"frequency_label\": \"Monthly\",\n \"starts_at\": \"2026-11-01T09:00:00+01:00\",\n \"ends_at\": null,\n \"next_run_at\": \"2026-11-01T09:00:00+01:00\",\n \"status\": \"active\",\n \"failure_reason\": null,\n \"can_retry\": false,\n \"can_cancel\": true,\n \"can_pause\": true,\n \"can_pay_now\": true,\n \"can_resume\": false,\n \"resume_needs_start_at\": false,\n \"paused_at\": null,\n \"can_edit\": true,\n \"archived\": false,\n \"can_reactivate\": false,\n \"can_delete\": false,\n \"reactivation_needs_start_at\": false,\n \"cancelled_at\": null,\n \"total_runs\": 0,\n \"last_run_at\": null,\n \"last_run\": null,\n \"description\": \"Data for Mum\",\n \"summary\": \"Internet Data scheduled for the beneficiary 08031234567\",\n \"created_at\": \"2026-10-05T12:00:00+01:00\"\n }\n}" } ] }, { "name": "Delete", "request": { "method": "DELETE", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v2/scheduled-payments/scheduleReference", "host": [ "{{baseUrl}}" ], "path": [ "v2", "scheduled-payments", "scheduleReference" ] }, "description": "Permanently delete a `cancelled` schedule and its run history. Transactions it created stay in your transaction history.\n\nDocs: https://docs.paybeta.ng/schedule-payments-delete" }, "response": [ { "name": "Success (200)", "originalRequest": { "method": "DELETE", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v2/scheduled-payments/scheduleReference", "host": [ "{{baseUrl}}" ], "path": [ "v2", "scheduled-payments", "scheduleReference" ] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"success\": true,\n \"message\": \"Schedule permanently deleted.\"\n}" }, { "name": "Error (422)", "originalRequest": { "method": "DELETE", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v2/scheduled-payments/scheduleReference", "host": [ "{{baseUrl}}" ], "path": [ "v2", "scheduled-payments", "scheduleReference" ] } }, "status": "Unprocessable Content", "code": 422, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"success\": false,\n \"message\": \"Cancel this schedule first. Only archived schedules can be deleted.\",\n \"errors\": {\n \"schedule\": [\n \"Cancel this schedule first. Only archived schedules can be deleted.\"\n ]\n }\n}" } ] } ] } ], "description": "## Schedule Payments\n\nSchedule Airtime, Data, Cable TV and Electricity payments that Paybeta charges to your wallet automatically - **once**, or **daily** / **weekly** / **monthly**.\n\n#### Authentication\n\nEvery 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)\n\n### How charging works\n\nNothing 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.\nIf 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.\n\n### Rules\n\n- `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).\n- `ends_at` (optional, recurring only) must be after `start_at`.\n- Up to 20 open schedules (active / processing / failed / paused) per account.\n- Airtime: ₦50 - ₦20,000. Data: bundle ≥ ₦200. Cable TV: ₦500 - ₦80,000. Electricity: ₦1,000 - ₦50,000.\n- Phone numbers: 11 digits starting with 0.\n\n### Schedule statuses\n\n`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.\n\n### Response formats\n\n**Standard Success Response**\n**HTTP Status:** `200 OK` (**or** `201 Created`)\n\n```js\n\n{\n \"status\": \"successful\",\n \"message\": \"Operation completed successfully.\",\n \"data\": {}\n}\n\n```\n\n**List Schedules Success Response**\n**HTTP Status:** `200 OK`\n\n\n```js\n {\n \"status\": \"successful\",\n \"message\": \"Schedules retrieved successfully.\",\n \"data\": [],\n \"meta\": {}\n }\n```\n**Standard Error Response**\n\n```js\n{\n \"status\": \"failed\",\n \"message\": \"Error description here.\",\n \"errors\": {\n \"field_name\": [\n \"Validation or constraint error message.\"\n ]\n }\n}\n```\n\n### HTTP Status Codes\n\n\n| Code | Status | Trigger / Description\n| --- | --- | --- |\n| **401** | Unauthorized | Missing or invalid API key |\n| **404** | Not Found | Requested resource not found |\n| **422** | Unprocessable Entity | Validation failed or action not allowed in current state |\n\nhttps://docs.paybeta.ng/schedule-payments\n\n---\n\n## Create\n\n> **Body**\n\n| Field | Required | Notes |\n|---|---|---|\n| service | yes | `airtime` · `data` · `cabletv` · `electricity` |\n| biller | yes | from **Options** |\n| customer_id | yes | phone number, smartcard number or meter number |\n| code | data / cabletv / electricity | bundle code, or meter type for electricity |\n| amount | airtime / electricity | ignored for data & cable TV (bundle price is used) |\n| frequency | yes | `once` · `daily` · `weekly` · `monthly` |\n| start_at | yes | first run, ≥ 10 minutes from now |\n| ends_at | no | recurring only |\n| description | no | your label, max 100 chars |\n\nEach request in this folder saves the new schedule's reference to `scheduleReference`.\n\n**Body**\n\n| Field | Required | Notes |\n|---|---|---|\n| service | yes | `airtime` · `data` · `cabletv` · `electricity` |\n| biller | yes | from **Options** |\n| customer_id | yes | phone number, smartcard number or meter number |\n| code | data / cabletv / electricity | bundle code, or meter type for electricity |\n| amount | airtime / electricity | ignored for data & cable TV (bundle price is used) |\n| frequency | yes | `once` · `daily` · `weekly` · `monthly` |\n| start_at | yes | first run, ≥ 10 minutes from now |\n| ends_at | no | recurring only |\n| description | no | your label, max 100 chars |\n\nEach request in this folder saves the new schedule's reference to `scheduleReference`.\n\nhttps://docs.paybeta.ng/create" }, { "name": "Wallet", "item": [ { "name": "Balance", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v2/wallet/balance", "host": [ "{{baseUrl}}" ], "path": [ "v2", "wallet", "balance" ] }, "auth": { "type": "noauth" }, "description": "Docs: https://docs.paybeta.ng/wallet-balance" }, "response": [ { "name": "Success (200)", "originalRequest": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v2/wallet/balance", "host": [ "{{baseUrl}}" ], "path": [ "v2", "wallet", "balance" ] }, "auth": { "type": "noauth" } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"successful\",\n \"message\": \"Request processed successfully.\",\n \"data\": {\n \"availableBalance\": 4212.45,\n \"lienAmount\": 0\n }\n}" } ] } ] }, { "name": "Showmax", "item": [ { "name": "Get Bouquets", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v2/showmax/bouquet", "host": [ "{{baseUrl}}" ], "path": [ "v2", "showmax", "bouquet" ] }, "description": "Docs: https://docs.paybeta.ng/showmax-get-bouquets" }, "response": [ { "name": "Success (200)", "originalRequest": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v2/showmax/bouquet", "host": [ "{{baseUrl}}" ], "path": [ "v2", "showmax", "bouquet" ] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"successful\",\n \"message\": \"Request processed successfully.\",\n \"data\": {\n \"packages\": [\n {\n \"code\": \"full\",\n \"description\": \"ShowMax Full - N3,500\",\n \"price\": \"3500.00\"\n },\n {\n \"code\": \"mobile_only\",\n \"description\": \"ShowMax Mobile Only - N1,600\",\n \"price\": \"1600.00\"\n },\n {\n \"code\": \"full_sports_mobile_only\",\n \"description\": \"ShowMax Full Sports Mobile Only - N5,400\",\n \"price\": \"5400.00\"\n }\n ...\n ]\n }\n}" } ] }, { "name": "Payment", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v2/showmax/purchase", "host": [ "{{baseUrl}}" ], "path": [ "v2", "showmax", "purchase" ] }, "description": "Docs: https://docs.paybeta.ng/showmax-payment" }, "response": [] } ] } ] }