API Integration Guide

Integrate your platform with USSD Pad using direct HTTP API calls and your platform API key — no SDK required.

1. Get Your API Key

Every platform has a unique API key. You can find and manage it from your platform dashboard.

From Your Dashboard

Log into your Platform Portal
Navigate to Settings → API Settings
Copy your API key. It looks like: ussdpad_sk_...

You can regenerate your API key at any time. The old key will be invalidated immediately.

2. Authenticate Requests

All platform API endpoints require authentication. Pass your API key as a Bearer token in the Authorization header:

# Replace YOUR_API_KEY with your actual key

Authorization: Bearer ussdpad_sk_your_api_key_here

Important: Keep your API key secret. Never expose it in client-side code, version control, or public repositories. If you suspect your key has been compromised, regenerate it immediately from your dashboard.

3. Making API Requests

The base URL for all API endpoints is:

https://ussd.plugbundle.com/api

All endpoints return JSON. Here are examples in different languages:

cURL

# Get platform profile

curl -H "Authorization: Bearer ussdpad_sk_your_api_key_here" \

  https://ussd.plugbundle.com/api/platform/profile

PHP (cURL)

<?php

$apiKey = 'ussdpad_sk_your_api_key_here';

$ch = curl_init('https://ussd.plugbundle.com/api/platform/profile');

curl_setopt($ch, CURLOPT_HTTPHEADER, [

  "Authorization: Bearer $apiKey",

  'Accept: application/json',

]);

curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = json_decode(curl_exec($ch), true);

curl_close($ch);

echo $response['platform']['name'];

PHP (Guzzle)

use Illuminate\Support\Facades\Http;

$response = Http::withToken('ussdpad_sk_your_api_key_here')

    ->get('https://ussd.plugbundle.com/api/platform/profile')

    ->json();

return $response['platform']['name'];

JavaScript (Fetch)

const apiKey = 'ussdpad_sk_your_api_key_here';

const response = await fetch('https://ussd.plugbundle.com/api/platform/profile', {

  headers: {

    'Authorization': `Bearer ${apiKey}`,

    'Accept': 'application/json',

  },

});

const data = await response.json();

console.log(data.platform.name);

Python

import requests

api_key = 'ussdpad_sk_your_api_key_here'

headers = {'Authorization': f'Bearer {api_key}'}

response = requests.get(

    'https://ussd.plugbundle.com/api/platform/profile',

    headers=headers

)

data = response.json()

print(data['platform']['name'])

Node.js (Axios)

const axios = require('axios');

const apiKey = 'ussdpad_sk_your_api_key_here';

const response = await axios.get(

  'https://ussd.plugbundle.com/api/platform/profile',

  { headers: { 'Authorization': `Bearer ${apiKey}` } }

);

console.log(response.data.platform.name);

4. Managing Resellers via API

Create, list, and delete resellers programmatically using your API key.

List Resellers

curl -H "Authorization: Bearer ussdpad_sk_your_api_key_here" \

  https://ussd.plugbundle.com/api/platform/resellers

Create a Reseller

curl -X POST \

  -H "Authorization: Bearer ussdpad_sk_your_api_key_here" \

  -H "Content-Type: application/json" \

  -d '{ "name": "Kwame Mobile Shop", "code_suffix": "1001" }' \

  https://ussd.plugbundle.com/api/platform/resellers

PHP Example: Create Reseller

use Illuminate\Support\Facades\Http;

$response = Http::withToken('ussdpad_sk_your_api_key_here')

    ->post('https://ussd.plugbundle.com/api/platform/resellers', [

        'name' => 'Kwame Mobile Shop',

        'code_suffix' => '1001',

        'phone' => '0241000001',

    ])

    ->json();

if ($response['success']) {

    echo "Reseller created: {$response['reseller']['sub_code']}";

}

5. Fetching Orders via API

Retrieve orders with optional filters by reseller or status.

List All Orders

curl -H "Authorization: Bearer ussdpad_sk_your_api_key_here" \

  https://ussd.plugbundle.com/api/platform/orders

Filter by Status

curl -H "Authorization: Bearer ussdpad_sk_your_api_key_here" \

  "https://ussd.plugbundle.com/api/platform/orders?status=successful"

JavaScript Example: Display Orders

const apiKey = 'ussdpad_sk_your_api_key_here';

async function getOrders() {

  const res = await fetch('https://ussd.plugbundle.com/api/platform/orders', {

    headers: { 'Authorization': `Bearer ${apiKey}` }

  });

  const data = await res.json();

  data.orders.data.forEach(order => {

    console.log(`${order.reference} — ${order.status}`);

  });

}

6. USSD Webhooks & Payment

When a USSD code has a webhook URL, USSD Pad does not run the built-in menu. Instead it POSTs every user step to your endpoint. You return the next screen — including a payment URL when checkout is required.

1. Configure the webhook

An admin sets webhook_url on your USSD code in the Admin Dashboard (Platform → USSD Codes). That URL must accept POST JSON within 15 seconds.

2. Incoming request (from USSD Pad → you)

POST https://your-platform.com/api/ussd/webhook

Content-Type: application/json

{

  "session_id": "uuid",

  "code": "*737*1001#",

  "sub_code": "*737*1001#",

  "input": "1",  // null on first dial

  "step": "root",

  "platform_name": "DataZone GH",

  "reseller_name": "Kwame Store",

  "state": {}

}

3. Your response (menu or payment)

Return HTTP 200 with this Live USSD screen shape:

// Menu screen

{

  "message": "Welcome\n1. Buy Data\n2. Check Order",

  "options": [

    { "id": "1", "label": "Buy Data" },

    { "id": "2", "label": "Check Order" }

  ],

  "is_terminal": false,

  "input_type": "none",

  "input_hint": null,

  "step": "root",

  "payment_url": null,

  "payment_amount": null

}

// Payment screen — opens your gateway in the app

{

  "message": "Pay GHS 10.00 to complete.",

  "options": [],

  "is_terminal": true,

  "input_type": "none",

  "input_hint": null,

  "step": "payment",

  "payment_url": "https://checkout.your-gateway.com/pay/REF",

  "payment_amount": 10.00

}

4. How payment completes

1. Your webhook creates the order / payment intent on your platform.
2. You return payment_url + payment_amount (include reference and phone_number when possible).
3. USSD Pad auto-records the order on your dashboard as processing, and the app opens the payment URL.
4. When your gateway confirms payment, call PATCH /api/platform/orders/{reference} with {"status":"successful"} so revenue updates.

Full contract

See the complete schemas on the API Reference under Platform USSD Webhook.