MK DATA Developer Platform API
Welcome to the official MK DATA API documentation. Our REST service empowers fintech platforms, mobile apps, and VTU aggregators to vend automated Nigerian telecom data bundles, purchase airtime top-ups, and verify real-time status with sub-second execution speeds and wholesale agent rates.
API Keys & Authorization Header
All API requests must include your live production key in the HTTP Authorization header using the standard Bearer scheme.
Every request authenticated with your API key automatically receives the discounted wholesale Agent Price from our database catalog, regardless of your consumer portal level.
Idempotency-Key & Safe Retries
To prevent double-billing caused by network timeouts or dropped sockets, you can pass an Idempotency-Key header or provide a custom tx_id in your payload.
If a request is retried with the same transaction key within 24 hours, MK DATA returns the identical cached response with header X-Idempotent-Replay: true without debiting your wallet balance a second time.
Check Wallet Balance
Returns your current live wallet balance and wholesale developer account tier.
curl -X GET "https://mkdatasub.com/api/v1/balance" \ -H "Authorization: Bearer YOUR_API_KEY"
{
"success": true,
"balance": 24500.00,
"currency": "NGN",
"tier": "agent",
"pricing": "wholesale"
}List Active Data Plans
Retrieves all active data plans with their numeric plan_id, numeric network code, and real-time wholesale agent prices. Optional query parameter ?network=1|2|3|4 filters the catalog.
curl -X GET "https://mkdatasub.com/api/v1/data/plans?network=1" \ -H "Authorization: Bearer YOUR_API_KEY"
{
"success": true,
"count": 48,
"data": [
{
"plan_id": 82,
"network": 1,
"network_name": "MTN",
"name": "MTN SME 1GB",
"type": "SME",
"size": "1GB",
"validity": "30 Days",
"price": 285.00
},
{
"plan_id": 83,
"network": 1,
"network_name": "MTN",
"name": "MTN SME 2GB",
"type": "SME",
"size": "2GB",
"validity": "30 Days",
"price": 570.00
}
]
}Purchase Mobile Data
The network field must always be an integer number, not a text string:
| Field | Type | Requirement | Description |
|---|---|---|---|
| network | integer | Required | Numeric ID: 1 (MTN), 2 (GLO), 3 (AIRTEL), 4 (9MOBILE). |
| plan_id | integer | Required | Numeric plan ID from the database catalog (e.g. 82, 5, 174). |
| number | string | Required | 11-digit recipient phone number (e.g. "08012345678"). |
| tx_id | string | Recommended | Your unique merchant reference for idempotency tracking and status query. |
curl -X POST "https://mkdatasub.com/api/v1/data/purchase" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"network": 1,
"plan_id": 82,
"number": "08012345678",
"tx_id": "MKD-TX-171800123456"
}'{
"success": true,
"status": "SUCCESS",
"reference": "MKD-DATA-171800123456",
"requestId": "MKD-TX-171800123456",
"amount": 285.00,
"balance": 10215.00,
"phone": "08012345678",
"network": 1,
"network_name": "MTN",
"plan": "MTN SME 1GB",
"message": "Data vending successful."
}Purchase Airtime Top-Up
Instantly credit airtime to any Nigerian phone number. Accepts numeric network: 1 (MTN), 2 (GLO), 3 (AIRTEL), or 4 (9MOBILE).
curl -X POST "https://mkdatasub.com/api/v1/airtime/purchase" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"network": 1,
"amount": 1000,
"number": "08012345678",
"tx_id": "MKD-AIR-171800998877"
}'{
"success": true,
"status": "SUCCESS",
"reference": "MKD-AIR-171800998877",
"amount_charged": 970.00,
"discount_applied": 30.00,
"new_balance": 9245.00,
"phone": "08012345678",
"network": 1,
"network_name": "MTN"
}Requery Transaction Status
Query the final state of any transaction by passing your MK DATA reference or client-side request_id.
curl -X GET "https://mkdatasub.com/api/v1/transactions/MKD-DATA-171800123456" \ -H "Authorization: Bearer YOUR_API_KEY"
HMAC Signature Verification
Every webhook notification sent to your configured endpoint includes a signature header: X-MK-Signature: t=1718000000,v1=abc123.... Verify this signature to ensure payloads are authentic and unhampered:
import crypto from "crypto";
export function verifyWebhook(secret: string, signatureHeader: string, rawBody: string): boolean {
const parts = signatureHeader.split(",");
const timestamp = parts.find((p) => p.startsWith("t="))?.replace("t=", "");
const signature = parts.find((p) => p.startsWith("v1="))?.replace("v1=", "");
if (!timestamp || !signature) return false;
const signedPayload = `${timestamp}.${rawBody}`;
const expected = crypto.createHmac("sha256", secret).update(signedPayload).digest("hex");
return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}Numeric Network Codes Reference Table
All API mutation payloads require the network to be specified as an integer code. Refer to this canonical table:
| Network Name | Numeric ID (Integer) | Supported Vending Types | Status |
|---|---|---|---|
| MTN Nigeria | 1 | SME, Corporate Gifting, Gifting, Airtime | Operational |
| Globacom (GLO) | 2 | Corporate Gifting, Airtime | Operational |
| Airtel Nigeria | 3 | Corporate Gifting, Airtime | Operational |
| 9mobile Nigeria | 4 | Corporate Gifting, Airtime | Operational |
HTTP Status & Error Reference
| Status | Error Code | Description | Remediation |
|---|---|---|---|
| 400 | BAD_REQUEST | Validation failure (e.g. invalid phone number format or missing plan ID). | Check payload structure and phone regex. |
| 401 | UNAUTHORIZED | Missing or revoked API key in Authorization header. | Regenerate live key in Developer Keys tab. |
| 402 | INSUFFICIENT_FUNDS | Account balance is lower than wholesale purchase cost. | Fund developer wallet via virtual account. |
| 409 | CONCURRENT_MUTATION | Another purchase transaction is currently locking this wallet. | Retry request with exponential backoff. |
| 429 | RATE_LIMIT_EXCEEDED | Exceeded standard limit of 60 requests/minute. | Throttle batch throughput. |