llms.txt for KDA API

The KDA API is an enterprise-grade Virtual Top-Up (VTU) and bill payment infrastructure. This page is the styled human-readable version — machines should fetch the raw text spec above.

Base URLs

https://app.kdadatasub.name.ng/api/services
https://app.kdadatasub.name.ng/api/profile

HTTPS only, JSON in/out. Every request carries Authorization: Bearer <API_KEY>. There is no separate sandbox host — the key prefix routes the environment.

Authentication

Using your key

curl -X GET https://app.kdadatasub.name.ng/api/profile/balance \
  -H "Authorization: Bearer kds_test_YOUR_API_KEY"

const response = await fetch("https://app.kdadatasub.name.ng/api/profile/balance", {
  headers: { "Authorization": "Bearer kds_test_YOUR_API_KEY" }
});
const data = await response.json();

import requests

response = requests.get(
    "https://app.kdadatasub.name.ng/api/profile/balance",
    headers={"Authorization": "Bearer kds_test_YOUR_API_KEY"},
)
print(response.json())

<?php
$ch = curl_init("https://app.kdadatasub.name.ng/api/profile/balance");
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => ["Authorization: Bearer kds_test_YOUR_API_KEY"],
    CURLOPT_RETURNTRANSFER => true,
]);
$response = curl_exec($ch);
curl_close($ch);

Scopes

One scope per key — create two keys if you need both:

• Services scope → /api/services/* (plans, purchases, verify, test).
• Profile scope → /api/profile/* (balance, transactions, withdraw, test).
• Wrong scope → 403 FORBIDDEN with keyStatus: "FORBIDDEN".
• GET /api/services/test and GET /api/profile/test accept either scope.

Key status

Missing/invalid/disabled key → 401 UNAUTHORIZED with keyStatus. No header at all → 401 without it.

Rate limits

Exhausted → 429 RATE_LIMITED with retryAfterMs plus Retry-After / X-Retry-After headers. Wait before retrying.

Quickstart

curl -X GET https://app.kdadatasub.name.ng/api/services/test \
  -H "Authorization: Bearer kds_test_YOUR_API_KEY"

curl -X GET https://app.kdadatasub.name.ng/api/services/data/plans \
  -H "Authorization: Bearer kds_test_YOUR_API_KEY"

curl -X POST https://app.kdadatasub.name.ng/api/services/data \
  -H "Authorization: Bearer kds_test_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "planId": "kds-data-mtn-sme-v1-003",
    "number": "08012345678",
    "idempotencyKey": "550e8400-e29b-41d4-a716-446655440000",
    "isPorted": false
  }'

Service endpoints

Data/tv without filters group as [{ type, plans[] }] with a count total; filtered/single returns flat rows with type per row.

Purchase payloads

Data — POST /api/services/data

Airtime — POST /api/services/airtime

TV — POST /api/services/tv (verify first)

Verify: POST /api/services/verify/tv with { smartCardNumber, providerId } → { valid, name }.

Electricity — POST /api/services/electricity (verify first)

Exam — POST /api/services/exam

Response pin may join PIN and serial with <=>.

Data / Recharge cards — POST /api/services/data-card, POST /api/services/recharge-card

pin / serial return comma-separated lists matching quantity.

Account endpoints

Withdraw body: { amount (>= 1000), bankCode, accountNumber (10-digit), pin (4-digit), narration? }. Requires Allow Withdrawals on the key, else 412. Accepted requests return PENDING and settle via WITHDRAWAL_SUCCESS / WITHDRAWAL_FAILED.

Pricing and routes

-v1- primary, -v2- secondary, -v3- aggregator (rolling out for Airtime, TV, and Electricity). v2 is usually cheaper for Data/Airtime; v1 for Electricity/NECO. Re-fetch plans — never cache prices long-term. See Plan versions.

Reliability

Webhooks: subscribe per category (Purchase → PURCHASE_SUCCESS / PURCHASE_FAILED; Withdrawal → WITHDRAWAL_SUCCESS / WITHDRAWAL_FAILED). Verify the X-Webhook-Signature HMAC-SHA256 against the raw body before parsing, reject skew over 5 minutes, respond 200 in under 10 seconds. No automatic retries. See Webhooks.

Errors: 400 VALIDATION_ERROR (+ details), 401, 402 INSUFFICIENT_BALANCE, 403, 404, 405, 409 CONFLICT, 412 PRECONDITION_FAILED, 422 TRANSACTION_FAILED (refunded), 429 RATE_LIMITED, 500. See Error handling.

Guide index