API Reference

Base URL: https://developers.rukkyhub.com/api/v1. All requests use POST with Content-Type: application/x-www-form-urlencoded. Authentication via X-API-KEY header.

SMM Actions

VTU Actions

Gift Card Actions

Service Codes (service_name / service_id)

Use these values for the service_name or service_id parameter when querying plans or placing VTU orders:

Category	service_name / service_id	Description
Airtime	mtn, glo, airtel, etisalat	Network codes for airtime purchase (action=vtu_airtime)
Data Plans	mtn-data, glo-data, airtel-data, etisalat-data	List data plans per network (action=vtu_data_plans, service_id=)
SME Data	mtn, glo, airtel, etisalat	List SME plans per network (action=vtu_sme_plans, network=)
Cable TV	dstv-cable, gotv-cable, startimes-cable	List cable plans (action=vtu_cable_plans, service_id=)
Electricity	ikeja-electric, eko-electric, abuja-electric, kano-electric, portharcourt-electric, ibadan-electric, kaduna-electric, jos-electric, enugu-electric, benin-electric, yola-electric	Disco names for electricity (action=vtu_electric_discos returns available discos)
Education	waec	WAEC pin purchase (action=vtu_education)
Recharge Card	mtn, glo, airtel, etisalat	Network for recharge card printing (action=vtu_recharge_card, card_network=)

Provider

All VTU services are processed through a third-party API. The provider field in responses indicates the upstream provider, along with a provider_ref when available.

cURL Examples

List SMM services:

curl -X POST https://developers.rukkyhub.com/api/v1 \
  -H "X-API-KEY: YOUR_API_KEY" \
  -d "action=services"

Place SMM order:

curl -X POST https://developers.rukkyhub.com/api/v1 \
  -H "X-API-KEY: YOUR_API_KEY" \
  -d "action=add&service=123&link=https://example.com&quantity=1000"

Bulk orders:

curl -X POST https://developers.rukkyhub.com/api/v1 \
  -H "X-API-KEY: YOUR_API_KEY" \
  -d 'action=add_bulk&orders=[{"service":123,"link":"https://example.com","quantity":1000},{"service":124,"link":"https://example.com/2","quantity":500}]'

Check order status:

curl -X POST https://developers.rukkyhub.com/api/v1 \
  -H "X-API-KEY: YOUR_API_KEY" \
  -d "action=status&order=4488"

Check balance:

curl -X POST https://developers.rukkyhub.com/api/v1 \
  -H "X-API-KEY: YOUR_API_KEY" \
  -d "action=balance"

Buy airtime (MTN N100):

curl -X POST https://developers.rukkyhub.com/api/v1 \
  -H "X-API-KEY: YOUR_API_KEY" \
  -d "action=vtu_airtime&service_name=mtn&phone=08012345678&amount=100&pin=1234"

List MTN data plans:

curl -X POST https://developers.rukkyhub.com/api/v1 \
  -H "X-API-KEY: YOUR_API_KEY" \
  -d "action=vtu_data_plans&service_id=mtn-data"

Buy data (plan_id from vtu_data_plans):

curl -X POST https://developers.rukkyhub.com/api/v1 \
  -H "X-API-KEY: YOUR_API_KEY" \
  -d "action=vtu_data&plan_id=1&phone=08012345678&pin=1234"

Buy SME data:

curl -X POST https://developers.rukkyhub.com/api/v1 \
  -H "X-API-KEY: YOUR_API_KEY" \
  -d "action=vtu_sme&plan_id=1&phone=08012345678&pin=1234"

Subscribe DSTV cable:

curl -X POST https://developers.rukkyhub.com/api/v1 \
  -H "X-API-KEY: YOUR_API_KEY" \
  -d "action=vtu_cable&plan_id=1&customer_id=12345678901&phone=08012345678&pin=1234"

Buy electricity token:

curl -X POST https://developers.rukkyhub.com/api/v1 \
  -H "X-API-KEY: YOUR_API_KEY" \
  -d "action=vtu_electricity&service_name=ikeja-electric&meter_type=prepaid&meter_number=12345678901&phone=08012345678&amount=2000&pin=1234"

Buy WAEC pin:

curl -X POST https://developers.rukkyhub.com/api/v1 \
  -H "X-API-KEY: YOUR_API_KEY" \
  -d "action=vtu_education&phone=08012345678&amount=5000&pin=1234"

Print recharge card (MTN N100 x2):

curl -X POST https://developers.rukkyhub.com/api/v1 \
  -H "X-API-KEY: YOUR_API_KEY" \
  -d "action=vtu_recharge_card&card_network=mtn&value=100&quantity=2&pin=1234"

Check VTU status:

curl -X POST https://developers.rukkyhub.com/api/v1 \
  -H "X-API-KEY: YOUR_API_KEY" \
  -d "action=vtu_status&trx=TRX_STRING"

List gift card types:

curl -X POST https://developers.rukkyhub.com/api/v1 \
  -H "X-API-KEY: YOUR_API_KEY" \
  -d "action=giftcard_cards"

Submit gift card trade (with image files):

curl -X POST https://developers.rukkyhub.com/api/v1 \
  -H "X-API-KEY: YOUR_API_KEY" \
  -F "action=giftcard_trade" \
  -F "giftcard_type_id=1" \
  -F "amount=100" \
  -F "type=ecode" \
  -F "code=CARD_CODE_HERE" \
  -F "images[]=@/path/to/front.jpg" \
  -F "images[]=@/path/to/back.jpg"

List your gift card trades:

curl -X POST https://developers.rukkyhub.com/api/v1 \
  -H "X-API-KEY: YOUR_API_KEY" \
  -d "action=giftcard_trades"

Response Format

SMM services response:

[
  {
    "service": 123,
    "name": "Instagram Followers - High Quality",
    "rate": 0.50,
    "min": 100,
    "max": 10000,
    "category": "Instagram"
  }
]

SMM order response:

{
  "order": 98765,
  "service": 123,
  "link": "https://instagram.com/username",
  "quantity": 1000,
  "price": 5.00,
  "status": "pending",
  "remains": 1000
}

VTU purchase response:

{
  "status": "success",
  "category": "airtime",
  "trx": "TRX_STRING",
  "provider_ref": "REF_IF_ANY",
  "amount": "105.00",
  "balance": "1000.00",
  "currency": "NGN",
  "message": "optional error/success message",
  "cards": [ { "pin": "...", "serial": "..." } ]
}

Order status response:

{
  "order": 98765,
  "status": "Completed",
  "start_count": 500,
  "remains": 0
}

Error response:

{
  "error": "Insufficient balance"
}

// or

{
  "errors": {
    "service": ["The selected service is invalid."]
  }
}

Order Status Values

Status mapping: pending(0), processing(1), completed(2), cancelled(3), refunded(4), partial(5).

Pricing & Discounts

• SMM: action=services returns rates already adjusted by your plan's SMM discount percentage.
• VTU: Pricing uses the configured VTU base + profit. VTU API discounts are configured per plan and per VTU category (airtime, data, SME, cable, electricity, education, recharge card). Discounts reduce only the profit portion (never below base cost).
• Admin: SMM discount is set inside API Access Plans. VTU reseller discounts are set in Global Settings per plan.

VTU Quick Start

1. Create an API key in the Developer Portal. Enable the needed VTU scopes (vtu_data_plans, vtu_data, vtu_status, etc.).
2. Fetch plans using action=vtu_data_plans / vtu_sme_plans / vtu_cable_plans.
3. Purchase using action=vtu_data / vtu_sme / vtu_cable / vtu_airtime / vtu_electricity.
4. Use action=vtu_status to check the transaction status by trx.
5. Optionally enable webhooks (vtu.success / vtu.failed) for auto callbacks.

Good vs Bad Integration

Bad Example (Do NOT do this)

Never expose your API key in frontend JavaScript or public HTML.

<script>
fetch("https://developers.rukkyhub.com/api/v1", {
  method: "POST",
  headers: { "Content-Type": "application/x-www-form-urlencoded" },
  body: "action=services&key=YOUR_API_KEY"
}).then(r => r.json()).then(console.log);
</script>

Good Example (Backend PHP using cURL + header)

<?php
$apiUrl = "https://developers.rukkyhub.com/api/v1";
$apiKey = getenv("SMM_API_KEY");
$apiOrigin = getenv("SMM_API_ORIGIN");

$ch = curl_init($apiUrl);
$headers = [
  "X-API-KEY: {$apiKey}",
  "Accept: application/json",
];
if (!empty($apiOrigin)) {
  $headers[] = "X-API-ORIGIN: {$apiOrigin}";
}
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_POSTFIELDS => http_build_query(["action" => "services"]),
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CONNECTTIMEOUT => 10,
  CURLOPT_TIMEOUT => 20,
  CURLOPT_HTTPHEADER => $headers,
]);
$raw = curl_exec($ch);
$http = (int) curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($raw === false) { throw new Exception(curl_error($ch)); }
curl_close($ch);

$data = json_decode($raw, true);
if (!is_array($data)) { throw new Exception("Invalid JSON"); }
if ($http >= 400 || isset($data["error"]) || isset($data["errors"])) { throw new Exception($raw); }
print_r($data);

Good Example (Server-side Node.js fetch)

const apiUrl = "https://developers.rukkyhub.com/api/v1";
const apiKey = process.env.SMM_API_KEY;

const params = new URLSearchParams({ action: "services" });
const res = await fetch(apiUrl, {
  method: "POST",
  headers: {
    "X-API-KEY": apiKey,
    "Content-Type": "application/x-www-form-urlencoded",
    "Accept": "application/json"
  },
  body: params
});
const data = await res.json();
if (!res.ok || data.error || data.errors) throw new Error(JSON.stringify(data));
console.log(data);

VTU Responses

VTU purchase endpoints return a consistent response. Status values: success, failed, processing, pending.

{
  "status": "success|failed|processing|pending",
  "category": "data|sme|airtime|cable|electricity|education|recharge_card",
  "trx": "TRX_STRING",
  "provider_ref": "REFERENCE_IF_ANY",
  "amount": "123.45",
  "balance": "1000.00",
  "currency": "NGN",
  "message": "optional error/success message",
  "cards": [ { "pin": "...", "serial": "..." } ]
}

Gift Card Responses

giftcard_cards returns an array of available gift card types:

[
  {
    "id": 1,
    "card": "Apple iTunes",
    "type": "US $50",
    "currency": "USD",
    "rate": 0.85,
    "ecode_rate": 0.82,
    "min_amount": 10,
    "max_amount": 500
  }
]

giftcard_trade returns:

{
  "status": "success",
  "message": "Gift card trade submitted successfully",
  "trade_id": 1
}

giftcard_trades returns a paginated list of your submitted trades with status (pending, approved, rejected, etc.). KYC must be completed to withdraw gift card trade earnings.

Background Jobs & Cron

The system runs automated background jobs via a cron endpoint to keep services up to date. Set up your cron to hit this URL every minute:

* * * * * curl -s https://developers.rukkyhub.com/cron >/dev/null 2>&1

The cron performs the following tasks:

• Process pending orders — Sends queued SMM orders to upstream API providers.
• Sync provider services & rates — Fetches latest service lists and pricing from all connected API providers.
• Refill processing — Sends drip-feed refill orders and checks refill status.
• Check provider health — Monitors API provider balances and connectivity, alerts on failures.
• SLA breach monitoring — Detects orders exceeding expected delivery time and flags them.
• Fraud detection — Runs fraud analysis on suspicious activity patterns.
• Service quality monitoring — Tracks service delivery quality metrics.
• Subscription expiry — Checks child panel and API access subscriptions and marks expired ones.
• Churn analysis — Daily analysis of user churn risk factors.

PHP Example File

Download a complete PHP API integration example:

https://developers.rukkyhub.com/assets/php_api_example.txt

Security Notes

• Use HTTPS only. Do not send API keys over plain HTTP.
• Use scoped API keys to limit allowed actions.
• Requests are rate-limited per API plan.
• You can restrict keys to IPs/domains using the whitelist feature in Developer Portal.
• If you enforce a Domain whitelist, send X-API-ORIGIN / Origin header, or pass origin= / domain= in the request body.
• Order status can only be fetched for orders that belong to your account.
• A 4-digit pin is required for all VTU purchase actions. Set your pin in your account security settings.