PadoData API v1

Build with the Fastest
Data Reseller API

Integrate automated data bundle delivery directly into your app. Buy at our wholesale prices, resell at your own margins.

Authentication

Pass your API key in the headers of every request to authenticate.

Headers
x-api-key: your_api_key_here

Base URL

All API requests must be made over HTTPS to our v1 endpoint.

Production URL
https://padodatagh.com/api/v1

Core Endpoints

Available Offers

Fetch the real-time list of all available data bundles and their current pricing.

GET/offers
Response JSON
{
  "success": true,
  "data": [
    {
      "offer_id": "9342-a2b1...",
      "name": "MTN 1GB",
      "network": "mtn",
      "volume": 1000,
      "offer_slug": "mtn_master_beneficiary_portal",
      "price": 6.50,
      "description": "1GB Non-expiry"
    }
  ]
}

Place an Order

Purchase a data bundle instantly. The cost is deducted directly from your wallet balance.

POST/order/:network

Request Body

{
  "phone": "024XXXXXXX",
  "volume": 1000,
  "offer_slug": "mtn_master_beneficiary_portal",
  "reference": "YOUR_UNIQUE_ID_123", // Optional
  "webhookUrl": "https://yoursite.com/webhook" // Optional
}

Success Response

{
  "success": true,
  "message": "Order received",
  "orderId": "abc-123-def",
  "reference": "YOUR_UNIQUE_ID_123",
  "status": "processing"
}

Check Order Status

Check the real-time status of an order using our Order ID or your custom Merchant Reference.

GET/order/status/:id
Response JSON
{
  "success": true,
  "data": {
    "orderId": "abc-123-def",
    "reference": "YOUR_UNIQUE_ID_123",
    "status": "completed",
    "network": "mtn",
    "volume_gb": 1,
    "phone": "024XXXXXXX",
    "created_at": "2024-01-01T12:00:00Z"
  }
}

Check Wallet Balance

Programmatically check your current available wallet balance to ensure sufficient funds before ordering.

GET/balance
Response JSON
{
  "success": true,
  "data": {
    "balance": 150.50,
    "currency": "GHS",
    "updated_at": "2024-01-01T12:00:00Z"
  }
}

Order History

Fetch a paginated list of your most recent data bundle orders.

GET/history?limit=50
Response JSON
{
  "success": true,
  "data": [
    {
      "orderId": "abc-123-def",
      "reference": "MERCHANT_REF_1",
      "network": "mtn",
      "volume_gb": 1,
      "price": 6.50,
      "status": "completed",
      "phone": "024XXXXXXX",
      "created_at": "2024-01-01T12:00:00Z"
    }
  ],
  "meta": {
    "total": 150,
    "limit": 50
  }
}

Send SMS (Requires Approval)

Send custom SMS messages to your customers. Requires manual application approval in the developer dashboard.

POST/sms

Request Body

{
  "recipients": "0241234567, 0551234567",
  "message": "Your transaction was successful!"
}

Costs 0.10 GHS per 160 characters per recipient, automatically deducted from your wallet balance.

Success Response

{
  "success": true,
  "data": {
    "reference": "SMS-API-...",
    "cost": 0.20,
    "recipients": 2,
    "pages": 1,
    "sender_id": "JestSMS",
    "status": "dispatched"
  }
}
Recommended Approach

Use Webhooks

Instead of polling the status endpoint, we highly recommend setting up a Webhook URL. We will send a POST request to your server the exact moment an order status changes to completed or rejected.

Configure Webhooks
Webhook Payload Example
{
  "orderId": "abc-123-def",
  "reference": "YOUR_UNIQUE_ID_123",
  "status": "completed",
  "network": "mtn",
  "volume_gb": 1,
  "phone": "024XXXXXXX",
  "completed_at": "2024-01-01T12:00:05Z"
}

Common Response Codes

401

Unauthorized

Your API key is missing, invalid, or has been revoked. Ensure that you are passing your active key correctly in the x-api-key header.

402

Payment Required

Your wallet balance is insufficient to process this order. You must top up your wallet via the dashboard before attempting to purchase this bundle.

400

Bad Request

The request body is malformed or missing required parameters. Double-check that your JSON payload includes all necessary fields like phone and offer_slug.

404

Not Found

The requested resource could not be found. This usually happens if you provide an invalid offer_slug or query an orderId that doesn't belong to you.

502

Bad Gateway

The upstream telecommunications provider is unreachable or experiencing downtime. Your order might be delayed; monitor your webhooks for final status updates.