Rukkystore SMM - API Documentation

API Documentation

Use this API to place orders, check order status, list services, and check balance.

Quick Start

Open your dashboard → Developer Portal and create an API key.
Store the key server-side (ENV/secret manager). Never expose it in frontend JS.
Call the API with HTTPS from your backend server.
Use action=services to fetch valid service IDs, min/max, and rate.
Place orders with action=add, then poll with action=status.

Base URL

https://www.rukkystore.com/api/v1

HTTP Method: POST | Response: JSON

Authentication

Your API key is like a password. Keep it secret.

You can send the key in the request body (key=...) or as a header (recommended).

X-API-KEY: YOUR_API_KEY

key=YOUR_API_KEY

If you revoke a key, it stops working immediately.

Security Notes

Use HTTPS only. Do not send API keys over plain HTTP in production.
Use scoped API keys to limit allowed actions (services/add/status/balance).
Requests are rate-limited to reduce abuse and brute forcing.
Order status can only be fetched for orders that belong to your account.

Actions

Action	Description	Required Fields
services	List all services	key, action
add	Place a new order	key, action, service, link, quantity
status	Get order status	key, action, order
balance	Get account balance	key, action
vtu_data_plans	List VTU data plans	key, action, service_id
vtu_sme_plans	List VTU SME plans	key, action, network
vtu_cable_plans	List VTU cable plans	key, action, service_id
vtu_electric_discos	List VTU electricity discos	key, action
vtu_cable_verify	Verify cable smartcard	key, action, service_id, customer_id
vtu_electricity_verify	Verify electricity meter	key, action, service_name, meter_type, meter_number
vtu_airtime	Buy airtime	key, action, service_name, phone, amount, pin
vtu_data	Buy data	key, action, plan_id, phone, pin
vtu_sme	Buy SME data	key, action, plan_id, phone, pin
vtu_cable	Subscribe cable	key, action, plan_id, customer_id, phone, pin
vtu_electricity	Buy electricity	key, action, service_name, meter_type, meter_number, phone, amount, pin
vtu_education	Buy education pin (WAEC)	key, action, phone, amount, pin
vtu_recharge_card	Print recharge card	key, action, card_network, value, quantity, pin
vtu_status	Get VTU transaction status	key, action, trx

Order Status Values

pending processing completed cancelled refunded partial

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

Examples

cURL: services

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

cURL: add order

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

cURL: order status

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

cURL: balance

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

cURL: VTU data plans

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

cURL: VTU buy data

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

cURL: VTU status

curl -X POST "https://www.rukkystore.com/api/v1" -H "X-API-KEY: YOUR_API_KEY" -d "action=vtu_status&trx=XXXX"

PHP Example File

https://www.rukkystore.com/assets/php_api_example.txt

VTU Quick Start

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

VTU Responses

VTU purchase endpoints return a consistent response.

{
  "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": "..." } ]
}

Webhooks (VTU Callbacks)

Create a webhook in Developer Portal and subscribe to VTU events.

Headers sent to your webhook URL:

X-Webhook-Event: vtu.success
X-Webhook-Signature: <hmac_sha256(payload_json, webhook_secret)>

Supported VTU events:

vtu.status_changed
vtu.processing
vtu.success
vtu.failed

Example payload:

{
  "event": "vtu.success",
  "occurred_at": "2026-04-05T12:00:00Z",
  "vtu": {
    "id": 1,
    "trx": "TRX_STRING",
    "category": "data",
    "service_name": "mtn-data",
    "phone": "08012345678",
    "amount": 123.45,
    "base_amount": 120.00,
    "profit_amount": 3.45,
    "provider": "strowallet",
    "provider_ref": "ABC123",
    "status": "success",
    "meta": {},
    "created_at": "2026-04-05T12:00:00Z",
    "updated_at": "2026-04-05T12:00:05Z"
  }
}

Common Errors

Invalid api key: key is wrong or revoked.
This API key is not allowed for this action: your key scope does not include the requested action.
Please follow the limit: quantity outside min/max range.
Insufficient balance: not enough funds or minimum balance would be violated.