llms.txt for KDA API

The KDA API is an enterprise-grade Virtual Top-Up (VTU) and bill payment infrastructure. This document provides a highly condensed, LLM-friendly specification of the KDA API to help AI agents, coding assistants, and crawlers quickly understand how to interact with our services.

Base URL

https://kda-turbo-web.vercel.app/api/services

Authentication

All API requests must include an Authorization header with a valid Bearer token.

Authorization: Bearer <API_KEY>
Content-Type: application/json

Environments: The environment is determined entirely by the API key prefix. There is no separate sandbox URL.

• Sandbox: Keys starting with kds_test_. Simulates a successful response without deducting real funds.
• Production: Keys starting with kds_live_.

Key Scopes:

• Service Keys: Used for purchasing services (Data, Airtime, TV, etc.).
• Profile Keys: Used for account-level actions (Balance, Transaction History).

Standard Response Format

All endpoints return a standard JSON structure:

{
  "success": true, // or false
  "message": "Human readable message",
  "data": { ... } // Payload on success
}

Failed transactions return standard HTTP status codes (400, 401, 403, 404, 500) with an error payload:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Detailed error message"
  }
}

Core Endpoints

Account Balance

• Endpoint: GET /balance
• Scope: Profile Key
• Response: { success: true, "balance": 5000.00, "mode": "sandbox" }

Fetch Providers & Plans

Every service has a /plans endpoint to fetch available providers and pricing.

• Data: GET /data/plans
• Airtime: GET /airtime/plans
• TV: GET /tv/plans
• Electricity: GET /electricity/plans
• Exams: GET /exam/plans
• Data Cards: GET /data-card/plans
• Recharge Cards: GET /recharge-card/plans

Purchase Services

All purchases are made via POST requests. An idempotencyKey (UUID) is heavily recommended to prevent duplicate charges.

Data Purchase: POST /data

{ "planId": "string", "number": "string", "isPorted": boolean, "idempotencyKey": "uuid" }

Airtime Purchase: POST /airtime

{ "planId": "string", "number": "string", "amount": number, "idempotencyKey": "uuid" }

TV Subscription: POST /tv

{ "planId": "string", "iucNumber": "string", "idempotencyKey": "uuid" }

Electricity Bill: POST /electricity

{ "providerId": "string", "meterNumber": "string", "amount": number, "meterType": "PREPAID|POSTPAID", "idempotencyKey": "uuid" }

Exam PINs: POST /exam

{ "providerId": "string", "quantity": number, "cardName": "string", "idempotencyKey": "uuid" }

Data Card Purchase: POST /data-card

{ "planId": "string", "quantity": number, "cardName": "string", "idempotencyKey": "uuid" }

Recharge Card Purchase: POST /recharge-card

{ "planId": "string", "quantity": number, "cardName": "string", "idempotencyKey": "uuid" }

Transactions History

• Endpoint: GET /transactions
• Query Params: ?page=1&limit=20&type=DATA
• Scope: Profile Key

Idempotency

Provide a unique UUID in the idempotencyKey field for POST requests. If a request is retried with the same key within 24 hours, the API will return the original response without double-charging the wallet.