U USSD Pad
Get Started Platform Login
← Back to Documentation
Integration Guide

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

  1. Log into your Platform Portal
  2. Navigate to Settings → API Settings
  3. 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. Webhooks

You can set a webhook URL on each USSD code to receive real-time events. When a session completes or an order is created, USSD Pad will send a POST request to your webhook URL with the event payload.

Setting a Webhook

Webhook URLs can be configured from the Admin Dashboard when editing a USSD code. Alternatively, contact the system administrator to set up a webhook endpoint for your platform.

Rate Limits

API requests are rate-limited to 60 requests per minute per API key. If you exceed this limit, you'll receive a 429 Too Many Requests response.