U USSD Pad
Get Started Platform Login
← Back to Documentation
API Reference

API Reference

Complete reference for the USSD Pad backend API endpoints.

Authentication

Platform API endpoints use API key authentication. Pass your key as a Bearer token in the Authorization header:

Authorization: Bearer ussdpad_sk_your_api_key_here

You can find your API key in the Platform Portal under Settings → API Settings.

Try it with cURL

curl -H "Authorization: Bearer ussdpad_sk_your_api_key_here" \
  https://ussd.plugbundle.com/api/platform/profile

Base URL

https://ussd.plugbundle.com/api

All endpoints return JSON. Public endpoints (codes, lookup, session) require no authentication.

Public API (App-facing)

GET /api/codes

List All Registered Codes

Returns all active USSD codes with platform information. Used by the mobile app to build its registry cache.

// Response
{
  "success": true,
  "codes": [
    {
      "code": "*737#",
      "platform_name": "DataZone GH",
      "type": "main"
    }
  ]
}
POST /api/lookup

Look Up a Code

Find which platform owns a specific USSD code. Uses POST to handle # characters which break in URLs.

// Request
{ "code": "*737#" }
// Response
{
  "success": true,
  "code": {
    "code": "*737#",
    "type": "main",
    "platform_name": "DataZone GH",
    "reseller_name": null,
    "is_active": true
  }
}
POST /api/session

Handle USSD Session

The main endpoint called by the mobile app when a user dials a code. Routes to the correct platform's menu flow.

// Request (first call — no session yet)
{ "code": "*737#" }
// Response — root menu
{
  "success": true,
  "session_id": "uuid-v4",
  "platform_name": "DataZone GH",
  "message": "Welcome to DataZone GH\nSelect a service:",
  "options": [
    { "id": "buy_data", "label": "Buy Data Bundle" },
    { "id": "check_balance", "label": "Check Balance" },
    { "id": "check_order", "label": "Check Order Status" }
  ],
  "is_terminal": false,
  "input_type": "none",
  "step": "root"
}

Subsequent calls include session_id, input (user selection), and step (current step from previous response).

// Request — user selects option 1
{
  "code": "*737#",
  "session_id": "uuid-v4",
  "input": "1",
  "step": "root"
}

Platform API (Authenticated)

Authenticate with your API key as a Bearer token in the Authorization header. Get your key from the Platform Portal → Settings → API Settings.

GET /api/platform/profile

Platform Profile

Get your platform's info, stats, API key, and main USSD code.

GET /api/platform/secret

Get API Key Info

Returns your current API key and when it was created.

POST /api/platform/secret/cycle

Regenerate API Key

Invalidates your current key and generates a new one. Previous key will stop working immediately.

GET POST DELETE /api/platform/resellers

Reseller Management

CRUD operations for resellers. POST creates a reseller with auto-generated sub-code. Requires a name and code_suffix.

GET /api/platform/orders

Order Management

List orders with optional filters by reseller_id and status.

Error Handling

{
  "success": false,
  "message": "Description of the error."
}

Common HTTP status codes: 200 success, 401 missing/invalid API key, 404 not found, 422 validation error, 429 rate limit exceeded, 500 server error.