USSD Pad 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"
}
// Response — payment screen (opens gateway in the app)
{
  "success": true,
  "session_id": "uuid-v4",
  "message": "Payment Required\n\nAmount: GHS 10.00\n\nTap Pay Now to complete payment.",
  "options": [],
  "is_terminal": true,
  "input_type": "none",
  "step": "payment",
  "payment_url": "https://checkout.your-gateway.com/pay/abc123",
  "payment_amount": 10.00
}

When payment_url is present, the mobile app opens that URL so the user can complete payment on your gateway.

Platform USSD Webhook (Custom Flow)

If your USSD code has a webhook_url, USSD Pad forwards every session step to your server. You control the menus and return a payment URL when checkout is needed.

What USSD Pad POSTs to you

Method: POST · Content-Type: application/json · Timeout: 15s · No signature headers today

{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "code": "*737*1001#",
  "main_code": "*737#",
  "sub_code": "*737*1001#",
  "input": "1",
  "step": "root",
  "platform_name": "DataZone GH",
  "reseller_id": 12,
  "reseller_name": "Kwame Store",
  "code_suffix": "1001",
  "is_reseller": true,
  "state": {}
}

input is null on the first dial. step is the server-side step from the previous response. Sub-codes inherit the main code webhook by default — your platform uses reseller_id / code_suffix to load that reseller’s storefront prices and credit their profit. You do not need a separate endpoint per reseller unless you set one.

What you must return (HTTP 2xx JSON)

{
  "message": "Select a package:",
  "options": [
    { "id": "1", "label": "1GB — GHS 5" },
    { "id": "2", "label": "2GB — GHS 10" }
  ],
  "is_terminal": false,
  "input_type": "none",
  "input_hint": null,
  "step": "packages",
  "payment_url": null,
  "payment_amount": null
}

input_type: none, phone, email, or text.

Trigger payment in the USSD app

Return a terminal payment screen with your gateway checkout URL:

{
  "message": "Pay GHS 10.00 to complete your order.",
  "options": [],
  "is_terminal": true,
  "input_type": "none",
  "input_hint": null,
  "step": "payment",
  "payment_url": "https://checkout.your-gateway.com/pay/ORDER_REF",
  "payment_amount": 10.00
}

Flow: USSD Pad → your webhook → you create the order on your side → you return payment_url (+ optional reference, phone_number, package_name) → the app opens your gateway. USSD Pad automatically records that checkout as a platform order. When payment completes on your side, PATCH /api/platform/orders/{reference} with status=successful so dashboard revenue updates.

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 POST PATCH /api/platform/orders

Order Management

List, create, and update orders. When your USSD webhook returns payment_url, USSD Pad auto-records a pending order. After your gateway confirms payment, call PATCH /api/platform/orders/{reference} with {"status":"successful"} so revenue appears on your dashboard.

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.