Schedule Payments›Create

Create - Airtime (one time)

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

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

Send your secret key in the P-API-KEY header. Keep it on your server, never in an app or browser.

Body (JSON)

service string Required

Example: airtime
biller string Required

Example: mtn_vtu
customer_id string Required

Example: 08031234567
amount integer Required

Example: 500
frequency string Required

Example: once
start_at string Required

Example: {{startAt}}
description string Required

Example: Airtime for Dad

Responses

201Success

Request

curl --request POST \
  --url 'https://api.paybeta.ng/v2/scheduled-payments' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'P-API-KEY: YOUR_SECRET_KEY' \
  --data '{
    "service": "airtime",
    "biller": "mtn_vtu",
    "customer_id": "08031234567",
    "amount": 500,
    "frequency": "once",
    "start_at": "{{startAt}}",
    "description": "Airtime for Dad"
}'curl --request POST \
  --url 'https://api.sandbox.paybeta.ng/v2/scheduled-payments' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'P-API-KEY: YOUR_SECRET_KEY' \
  --data '{
    "service": "airtime",
    "biller": "mtn_vtu",
    "customer_id": "08031234567",
    "amount": 500,
    "frequency": "once",
    "start_at": "{{startAt}}",
    "description": "Airtime for Dad"
}'

<?php

use Illuminate\Support\Facades\Http;

$response = Http::withHeaders([
        'Accept' => 'application/json',
        'Content-Type' => 'application/json',
        'P-API-KEY' => 'YOUR_SECRET_KEY',
])->post('https://api.paybeta.ng/v2/scheduled-payments', [
    'service' => 'airtime',
    'biller' => 'mtn_vtu',
    'customer_id' => '08031234567',
    'amount' => 500,
    'frequency' => 'once',
    'start_at' => '{{startAt}}',
    'description' => 'Airtime for Dad',
]);

$data = $response->json();<?php

use Illuminate\Support\Facades\Http;

$response = Http::withHeaders([
        'Accept' => 'application/json',
        'Content-Type' => 'application/json',
        'P-API-KEY' => 'YOUR_SECRET_KEY',
])->post('https://api.sandbox.paybeta.ng/v2/scheduled-payments', [
    'service' => 'airtime',
    'biller' => 'mtn_vtu',
    'customer_id' => '08031234567',
    'amount' => 500,
    'frequency' => 'once',
    'start_at' => '{{startAt}}',
    'description' => 'Airtime for Dad',
]);

$data = $response->json();

const response = await fetch('https://api.paybeta.ng/v2/scheduled-payments', {
  method: 'POST',
  headers: {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "P-API-KEY": "YOUR_SECRET_KEY",
  },
  body: JSON.stringify({
    "service": "airtime",
    "biller": "mtn_vtu",
    "customer_id": "08031234567",
    "amount": 500,
    "frequency": "once",
    "start_at": "{{startAt}}",
    "description": "Airtime for Dad"
  }),
});

const data = await response.json();const response = await fetch('https://api.sandbox.paybeta.ng/v2/scheduled-payments', {
  method: 'POST',
  headers: {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "P-API-KEY": "YOUR_SECRET_KEY",
  },
  body: JSON.stringify({
    "service": "airtime",
    "biller": "mtn_vtu",
    "customer_id": "08031234567",
    "amount": 500,
    "frequency": "once",
    "start_at": "{{startAt}}",
    "description": "Airtime for Dad"
  }),
});

const data = await response.json();

import requests

response = requests.request(
    "POST",
    "https://api.paybeta.ng/v2/scheduled-payments",
    headers={
    "Accept": "application/json",
    "Content-Type": "application/json",
    "P-API-KEY": "YOUR_SECRET_KEY",
    },
    json={
        "service": "airtime",
        "biller": "mtn_vtu",
        "customer_id": "08031234567",
        "amount": 500,
        "frequency": "once",
        "start_at": "{{startAt}}",
        "description": "Airtime for Dad"
    },
)

data = response.json()import requests

response = requests.request(
    "POST",
    "https://api.sandbox.paybeta.ng/v2/scheduled-payments",
    headers={
    "Accept": "application/json",
    "Content-Type": "application/json",
    "P-API-KEY": "YOUR_SECRET_KEY",
    },
    json={
        "service": "airtime",
        "biller": "mtn_vtu",
        "customer_id": "08031234567",
        "amount": 500,
        "frequency": "once",
        "start_at": "{{startAt}}",
        "description": "Airtime for Dad"
    },
)

data = response.json()

POST /v2/scheduled-payments HTTP/1.1
Host: api.paybeta.ng
Accept: application/json
Content-Type: application/json
P-API-KEY: YOUR_SECRET_KEY

{
  "service": "airtime",
  "biller": "mtn_vtu",
  "customer_id": "08031234567",
  "amount": 500,
  "frequency": "once",
  "start_at": "{{startAt}}",
  "description": "Airtime for Dad"
}POST /v2/scheduled-payments HTTP/1.1
Host: api.sandbox.paybeta.ng
Accept: application/json
Content-Type: application/json
P-API-KEY: YOUR_SECRET_KEY

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

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

String body = """
    {
      "service": "airtime",
      "biller": "mtn_vtu",
      "customer_id": "08031234567",
      "amount": 500,
      "frequency": "once",
      "start_at": "{{startAt}}",
      "description": "Airtime for Dad"
    }
    """;

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.paybeta.ng/v2/scheduled-payments"))
    .header("Accept", "application/json")
    .header("Content-Type", "application/json")
    .header("P-API-KEY", "YOUR_SECRET_KEY")
    .method("POST", HttpRequest.BodyPublishers.ofString(body))
    .build();

HttpResponse<String> response = HttpClient.newHttpClient()
    .send(request, HttpResponse.BodyHandlers.ofString());

System.out.println(response.body());import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

String body = """
    {
      "service": "airtime",
      "biller": "mtn_vtu",
      "customer_id": "08031234567",
      "amount": 500,
      "frequency": "once",
      "start_at": "{{startAt}}",
      "description": "Airtime for Dad"
    }
    """;

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.sandbox.paybeta.ng/v2/scheduled-payments"))
    .header("Accept", "application/json")
    .header("Content-Type", "application/json")
    .header("P-API-KEY", "YOUR_SECRET_KEY")
    .method("POST", HttpRequest.BodyPublishers.ofString(body))
    .build();

HttpResponse<String> response = HttpClient.newHttpClient()
    .send(request, HttpResponse.BodyHandlers.ofString());

System.out.println(response.body());

using System.Net.Http;
using System.Text;

using var client = new HttpClient();
var request = new HttpRequestMessage(new HttpMethod("POST"), "https://api.paybeta.ng/v2/scheduled-payments");
request.Headers.TryAddWithoutValidation("Accept", "application/json");
request.Headers.TryAddWithoutValidation("P-API-KEY", "YOUR_SECRET_KEY");
request.Content = new StringContent(
    """
    {
      "service": "airtime",
      "biller": "mtn_vtu",
      "customer_id": "08031234567",
      "amount": 500,
      "frequency": "once",
      "start_at": "{{startAt}}",
      "description": "Airtime for Dad"
    }
    """,
    Encoding.UTF8,
    "application/json");

var response = await client.SendAsync(request);
var data = await response.Content.ReadAsStringAsync();
Console.WriteLine(data);using System.Net.Http;
using System.Text;

using var client = new HttpClient();
var request = new HttpRequestMessage(new HttpMethod("POST"), "https://api.sandbox.paybeta.ng/v2/scheduled-payments");
request.Headers.TryAddWithoutValidation("Accept", "application/json");
request.Headers.TryAddWithoutValidation("P-API-KEY", "YOUR_SECRET_KEY");
request.Content = new StringContent(
    """
    {
      "service": "airtime",
      "biller": "mtn_vtu",
      "customer_id": "08031234567",
      "amount": 500,
      "frequency": "once",
      "start_at": "{{startAt}}",
      "description": "Airtime for Dad"
    }
    """,
    Encoding.UTF8,
    "application/json");

var response = await client.SendAsync(request);
var data = await response.Content.ReadAsStringAsync();
Console.WriteLine(data);

package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.paybeta.ng/v2/scheduled-payments", strings.NewReader(`{
  "service": "airtime",
  "biller": "mtn_vtu",
  "customer_id": "08031234567",
  "amount": 500,
  "frequency": "once",
  "start_at": "{{startAt}}",
  "description": "Airtime for Dad"
}`))
	req.Header.Set("Accept", "application/json")
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("P-API-KEY", "YOUR_SECRET_KEY")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	data, _ := io.ReadAll(res.Body)
	fmt.Println(string(data))
}package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.sandbox.paybeta.ng/v2/scheduled-payments", strings.NewReader(`{
  "service": "airtime",
  "biller": "mtn_vtu",
  "customer_id": "08031234567",
  "amount": 500,
  "frequency": "once",
  "start_at": "{{startAt}}",
  "description": "Airtime for Dad"
}`))
	req.Header.Set("Accept", "application/json")
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("P-API-KEY", "YOUR_SECRET_KEY")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	data, _ := io.ReadAll(res.Body)
	fmt.Println(string(data))
}

require "net/http"
require "json"

uri = URI("https://api.paybeta.ng/v2/scheduled-payments")
request = Net::HTTP::Post.new(uri)
request["Accept"] = "application/json"
request["Content-Type"] = "application/json"
request["P-API-KEY"] = "YOUR_SECRET_KEY"
request.body = <<~'JSON'
  {
    "service": "airtime",
    "biller": "mtn_vtu",
    "customer_id": "08031234567",
    "amount": 500,
    "frequency": "once",
    "start_at": "{{startAt}}",
    "description": "Airtime for Dad"
  }
JSON

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") do |http|
  http.request(request)
end

data = JSON.parse(response.body)require "net/http"
require "json"

uri = URI("https://api.sandbox.paybeta.ng/v2/scheduled-payments")
request = Net::HTTP::Post.new(uri)
request["Accept"] = "application/json"
request["Content-Type"] = "application/json"
request["P-API-KEY"] = "YOUR_SECRET_KEY"
request.body = <<~'JSON'
  {
    "service": "airtime",
    "biller": "mtn_vtu",
    "customer_id": "08031234567",
    "amount": 500,
    "frequency": "once",
    "start_at": "{{startAt}}",
    "description": "Airtime for Dad"
  }
JSON

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") do |http|
  http.request(request)
end

data = JSON.parse(response.body)

import okhttp3.MediaType.Companion.toMediaType
import okhttp3.OkHttpClient
import okhttp3.Request
import okhttp3.RequestBody.Companion.toRequestBody

val client = OkHttpClient()
val body = """
    {
      "service": "airtime",
      "biller": "mtn_vtu",
      "customer_id": "08031234567",
      "amount": 500,
      "frequency": "once",
      "start_at": "{{startAt}}",
      "description": "Airtime for Dad"
    }
""".trimIndent().toRequestBody("application/json".toMediaType())

val request = Request.Builder()
    .url("https://api.paybeta.ng/v2/scheduled-payments")
    .method("POST", body)
    .addHeader("Accept", "application/json")
    .addHeader("Content-Type", "application/json")
    .addHeader("P-API-KEY", "YOUR_SECRET_KEY")
    .build()

client.newCall(request).execute().use { response ->
    println(response.body?.string())
}import okhttp3.MediaType.Companion.toMediaType
import okhttp3.OkHttpClient
import okhttp3.Request
import okhttp3.RequestBody.Companion.toRequestBody

val client = OkHttpClient()
val body = """
    {
      "service": "airtime",
      "biller": "mtn_vtu",
      "customer_id": "08031234567",
      "amount": 500,
      "frequency": "once",
      "start_at": "{{startAt}}",
      "description": "Airtime for Dad"
    }
""".trimIndent().toRequestBody("application/json".toMediaType())

val request = Request.Builder()
    .url("https://api.sandbox.paybeta.ng/v2/scheduled-payments")
    .method("POST", body)
    .addHeader("Accept", "application/json")
    .addHeader("Content-Type", "application/json")
    .addHeader("P-API-KEY", "YOUR_SECRET_KEY")
    .build()

client.newCall(request).execute().use { response ->
    println(response.body?.string())
}

import Foundation

var request = URLRequest(url: URL(string: "https://api.paybeta.ng/v2/scheduled-payments")!)
request.httpMethod = "POST"
request.setValue("application/json", forHTTPHeaderField: "Accept")
request.setValue("application/json", forHTTPHeaderField: "Content-Type")
request.setValue("YOUR_SECRET_KEY", forHTTPHeaderField: "P-API-KEY")
request.httpBody = #"""
{
  "service": "airtime",
  "biller": "mtn_vtu",
  "customer_id": "08031234567",
  "amount": 500,
  "frequency": "once",
  "start_at": "{{startAt}}",
  "description": "Airtime for Dad"
}
"""#.data(using: .utf8)

let (data, _) = try await URLSession.shared.data(for: request)
print(String(data: data, encoding: .utf8)!)import Foundation

var request = URLRequest(url: URL(string: "https://api.sandbox.paybeta.ng/v2/scheduled-payments")!)
request.httpMethod = "POST"
request.setValue("application/json", forHTTPHeaderField: "Accept")
request.setValue("application/json", forHTTPHeaderField: "Content-Type")
request.setValue("YOUR_SECRET_KEY", forHTTPHeaderField: "P-API-KEY")
request.httpBody = #"""
{
  "service": "airtime",
  "biller": "mtn_vtu",
  "customer_id": "08031234567",
  "amount": 500,
  "frequency": "once",
  "start_at": "{{startAt}}",
  "description": "Airtime for Dad"
}
"""#.data(using: .utf8)

let (data, _) = try await URLSession.shared.data(for: request)
print(String(data: data, encoding: .utf8)!)

import 'package:http/http.dart' as http;

final response = await http.post(
  Uri.parse('https://api.paybeta.ng/v2/scheduled-payments'),
  headers: {
    'Accept': 'application/json',
    'Content-Type': 'application/json',
    'P-API-KEY': 'YOUR_SECRET_KEY',
  },
  body: r'''
{
  "service": "airtime",
  "biller": "mtn_vtu",
  "customer_id": "08031234567",
  "amount": 500,
  "frequency": "once",
  "start_at": "{{startAt}}",
  "description": "Airtime for Dad"
}
''',
);

print(response.body);import 'package:http/http.dart' as http;

final response = await http.post(
  Uri.parse('https://api.sandbox.paybeta.ng/v2/scheduled-payments'),
  headers: {
    'Accept': 'application/json',
    'Content-Type': 'application/json',
    'P-API-KEY': 'YOUR_SECRET_KEY',
  },
  body: r'''
{
  "service": "airtime",
  "biller": "mtn_vtu",
  "customer_id": "08031234567",
  "amount": 500,
  "frequency": "once",
  "start_at": "{{startAt}}",
  "description": "Airtime for Dad"
}
''',
);

print(response.body);

Response

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