API Reference

This page documents the primary endpoints available in the StarData Developer API.

Auth & Account

`POST /login/`

Authenticate and receive a JWT token pair.

Request Body:

JSON

{
  "phone_number": "08012345678",
  "pin": "123456"
}

Response:

JSON

{
  "access": "<jwt_access_token>",
  "refresh": "<jwt_refresh_token>"
}

`POST /upgrade/`

Upgrade your account to Developer tier. Requires an active authenticated session (JWT). An upgrade fee (if configured by admin) is deducted from your wallet.

Response (200 OK):

JSON

{
  "message": "Successfully upgraded to developer.",
  "fee_deducted": 500.00
}

Response (400 Bad Request):

JSON

{
  "error": "Insufficient balance. Upgrade fee is ₦500.00."
}

`GET /profile/`

Returns your full developer profile including wallet balance, API keys, and webhook configuration.

Headers: X-API-KEY or Authorization: Bearer <token>

Response (200 OK):

JSON

{
  "user": {
    "id": 1,
    "first_name": "John",
    "last_name": "Doe",
    "phone_number": "08012345678",
    "email": "john@example.com",
    "role": "developer",
    "is_active": true
  },
  "wallet_balance": 15000.00,
  "developer_profile": {
    "webhook_url": "https://yourapp.com/webhook/starboy",
    "webhook_secret": "abc123def456...",
    "is_active": true,
    "created_at": "2024-01-15T10:30:00Z"
  },
  "api_keys": [
    {
      "key": "ak_live_xxxxxxxxxxxxxxxx",
      "mode": "live",
      "is_active": true,
      "created_at": "2024-01-15T10:30:00Z",
      "last_used": "2024-01-20T14:22:00Z"
    },
    {
      "key": "ak_test_xxxxxxxxxxxxxxxx",
      "mode": "sandbox",
      "is_active": true,
      "created_at": "2024-01-15T10:30:00Z",
      "last_used": null
    }
  ]
}

`GET /funding-details/`

Returns bank details for funding your Starboy wallet.

Response (200 OK):

JSON

{
  "bank_name": "First Bank of Nigeria",
  "account_number": "3012345678",
  "account_name": "Starboy VTU Services"
}

`PATCH /webhook/update/`

Request Body:

JSON

{
  "webhook_url": "https://yourapp.com/webhook/starboy"
}

Response (200 OK):

JSON

{
  "message": "Webhook URL updated successfully.",
  "webhook_url": "https://yourapp.com/webhook/starboy",
  "webhook_secret": "abc123def456..."
}

Keep your webhook_secret safe. It is used to verify the authenticity of all incoming webhook payloads via HMAC-SHA256 signature.

`POST /keys/regenerate/`

Invalidates the current key and generates a new one for the specified mode.

Request Body:

JSON

{
  "mode": "live"
}

mode must be "live" or "sandbox".

Response (200 OK):

JSON

{
  "key": "ak_live_yyyyyyyyyyyyyyyyyy",
  "mode": "live",
  "is_active": true,
  "created_at": "2024-02-01T08:00:00Z",
  "last_used": null
}

Service Discovery

All discovery endpoints require authentication.

`GET /services/`

Returns all available service categories and their discovery endpoints.

Response:

JSON

{
  "categories": [
    {"id": "airtime", "name": "Airtime Purchase", "endpoint": "/api/v1/developer/airtime/networks/"},
    {"id": "data", "name": "Data Bundles", "endpoint": "/api/v1/developer/data/networks/"},
    {"id": "electricity", "name": "Electricity Bills", "endpoint": "/api/v1/developer/electricity/services/"},
    {"id": "cable", "name": "Cable TV Subscription", "endpoint": "/api/v1/developer/tv/services/"},
    {"id": "internet", "name": "Internet Subscription", "endpoint": "/api/v1/developer/internet/services/"},
    {"id": "education", "name": "Education Pins", "endpoint": "/api/v1/developer/education/services/"}
  ]
}

`GET /airtime/networks/`

Lists all active airtime networks with pricing.

Response:

JSON

[
  {
    "id": 1,
    "service_id": "mtn",
    "name": "MTN Nigeria",
    "min_amount": 50,
    "max_amount": 50000,
    "normal_discount": 3.0,
    "api_seller_discount": 4.5,
    "normal_price": null,
    "api_seller_price": null
  }
]

For airtime, pricing is percentage-based. The api_seller_discount is the cashback/discount percentage you receive.
Amount charged = face_value - (face_value × discount / 100)

`GET /data/networks/`

Lists all active data network providers.

Response:

JSON

[
  {"id": 1, "service_id": "mtn", "name": "MTN Data"}
]

`GET /data/networks/{network_id}/plans/`

Lists data plans for a given network provider.

Response:

JSON

[
  {
    "id": 42,
    "variation_id": "mtn-1gb-30days",
    "name": "1GB — 30 Days",
    "normal_price": 350.00,
    "api_seller_price": 320.00,
    "plan_type": "data"
  }
]

`GET /tv/services/`

Lists all active Cable TV providers (DSTV, GOTV, StarTimes).

Response:

JSON

[
  {"id": 1, "service_id": "dstv", "name": "DSTV"}
]

`GET /tv/services/{service_id}/packages/`

Lists cable TV subscription packages for a provider.

Response:

JSON

[
  {
    "id": 10,
    "variation_id": "dstv-compact",
    "name": "DStv Compact",
    "normal_price": 9000.00,
    "api_seller_price": 8750.00
  }
]

`GET /electricity/services/`

Lists all active electricity distribution companies (DISCOs).

Response:

JSON

[
  {"id": 1, "service_id": "ekedc", "name": "Eko Electric (EKEDC)"}
]

`GET /electricity/services/{service_id}/variations/`

Lists meter types/variations for a DISCO (e.g. prepaid, postpaid).

Response:

JSON

[
  {
    "id": 5,
    "variation_id": "ekedc-prepaid",
    "name": "EKEDC Prepaid",
    "min_amount": 500,
    "max_amount": 100000,
    "normal_price": null,
    "api_seller_price": null
  }
]

For electricity, pricing is amount-based with a discount/margin. Pass the desired token amount in the amount field at purchase time.

`GET /internet/services/`

Lists all active internet service providers.

Response:

JSON

[
  {"id": 1, "service_id": "smile", "name": "Smile Communications"}
]

`GET /internet/services/{service_id}/plans/`

Lists internet subscription plans.

Response:

JSON

[
  {
    "id": 20,
    "variation_id": "smile-10gb",
    "name": "10GB Monthly Bundle",
    "normal_price": 4000.00,
    "api_seller_price": 3800.00
  }
]

`GET /education/services/`

Lists available education exam pin types (WAEC, NECO, JAMB).

Response:

JSON

[
  {"id": 1, "service_id": "waec", "name": "WAEC Result Checker"}
]

`GET /education/services/{service_id}/variations/`

Lists education pin variations (scratch card types/quantities).

Response:

JSON

[
  {
    "id": 30,
    "variation_id": "waec-pins",
    "name": "WAEC Result Checker PIN",
    "normal_price": 3500.00,
    "api_seller_price": 3300.00
  }
]

Purchase

`POST /purchase/`

Unified purchase endpoint for all VTU services.

Headers:

HTTP

X-API-KEY: ak_live_...
Content-Type: application/json

Common Fields:

Field	Type	Required	Description
`service_type`	string	✅	One of: `airtime`, `data`, `tv`, `electricity`, `internet`, `education`
`beneficiary`	string	✅	Phone number, smart card no., or meter number
`amount`	number	✅ *	Token amount (for airtime & electricity only)
`reference`	string	❌	Optional custom reference. Auto-generated if omitted

Example: Airtime

JSON

{
  "service_type": "airtime",
  "beneficiary": "08012345678",
  "network_id": 1,
  "amount": 500
}

Example: Data

JSON

{
  "service_type": "data",
  "beneficiary": "08012345678",
  "plan_id": 42,
  "amount": 0
}

amount is ignored for data — price is determined by the selected plan_id.

Example: Cable TV

JSON

{
  "service_type": "tv",
  "beneficiary": "1234567890",
  "variation_id": 10,
  "amount": 0
}

beneficiary = smart card / IUC number. amount is determined by the package.

Example: Electricity

JSON

{
  "service_type": "electricity",
  "beneficiary": "04123456789",
  "variation_id": 5,
  "amount": 5000
}

beneficiary = meter number. amount = token face value in Naira.

Example: Internet

JSON

{
  "service_type": "internet",
  "beneficiary": "08012345678",
  "variation_id": 20,
  "amount": 0
}

Example: Education

JSON

{
  "service_type": "education",
  "beneficiary": "08012345678",
  "variation_id": 30,
  "quantity": 2,
  "amount": 0
}

quantity defaults to 1. Total amount = api_seller_price × quantity.

Success Response (201 Created):

JSON

{
  "status": "success",
  "reference": "DEV-A1B2C3D4E5",
  "purchase_id": 1093,
  "message": "Transaction successful",
  "error": null
}

Pending Response (201 Created):

JSON

{
  "status": "pending",
  "reference": "DEV-A1B2C3D4E5",
  "purchase_id": 1093,
  "message": "Transaction initiated",
  "error": null
}

A pending status means the transaction was queued with the provider. Use the verify endpoint or await a webhook callback.

Failed Response (400 Bad Request):

JSON

{
  "status": "failed",
  "reference": "DEV-A1B2C3D4E5",
  "purchase_id": null,
  "message": "Transaction failed",
  "error": "Insufficient balance"
}

Transaction Verification

`GET /verify/{reference}/`

Retrieve the current status and details of a past transaction.

Response (200 OK):

JSON

{
  "reference": "DEV-A1B2C3D4E5",
  "status": "success",
  "amount": 320.00,
  "beneficiary": "08012345678",
  "type": "data",
  "created_at": "2024-02-01T10:45:00Z",
  "remarks": "1GB — 30 Days data purchased for 08012345678"
}