NETPLUG API Documentation

Base URL: https://YOUR-NETPLUG-API-HOST/api/developer

To access the NETPLUG API, you'll need an API key. Include it in your request headers as:

X-API-Key: your_api_key_here

API Key Management

API keys are managed while signed in to your NETPLUG account (on the API Keys page, which uses these endpoints with your login token):

POST /api/developer/generate-api-key

{
  "name": "My API Key",
  "expiresIn": 365  // Optional: Days until expiry
}

GET /api/developer/api-keys

DELETE /api/developer/api-keys/:id

POST https://YOUR-NETPLUG-API-HOST/api/developer/purchase

Buys a data bundle for a phone number. The price is your reseller price for the package (see Data Packages) and is charged to your NETPLUG wallet; any price sent in the request is ignored. The order is accepted immediately with status processing and delivered in the background.

Request Body:

{
  "phoneNumber": "0501234567",  // Recipient's phone number (Telecel number)
  "network": "TELECEL",         // Network identifier (see options below)
  "capacity": "5",              // Data capacity in GB
  "gateway": "wallet",          // Required; the wallet is always charged
  "reference": "my-order-123"   // Optional: your idempotency key (1-64 chars: letters,
                                //   digits, . _ : -). It can also be sent as the
                                //   Idempotency-Key header.
}

Supported Networks:

• YELLO - MTN Ghana
• TELECEL - Telecel Ghana
• at (or AT_PREMIUM) - AirtelTigo Ghana. The package list uses at.

The phone number must belong to the selected network. Capacity must be one of the listed package sizes.

Idempotency (recommended):

Send your own unique reference with every purchase. If a request times out, send the same request again with the same reference: NETPLUG returns the original order (HTTP 200, "duplicate": true) and never charges twice. Reusing a reference for a different phone number, network or capacity is rejected with HTTP 409.

Success Response (201):

{
  "status": "success",
  "data": {
    "purchaseId": "665f1e5b3e6b398123456789",
    "orderReference": "NP-0123456789ABCDEF01234567", // NETPLUG order reference
    "reference": "my-order-123",                     // your reference, if sent
    "transactionReference": "TRX-...",
    "network": "TELECEL",
    "capacity": "5",
    "mb": "5000",
    "phoneNumber": "0501234567",
    "price": 23.00,
    "orderStatus": "processing",
    "createdAt": "2026-01-01T12:00:00.000Z",
    "completedAt": null,
    "remainingBalance": 177.00
  }
}

Error Response:

{
  "status": "error",
  "message": "Error message description"
}

To get available data packages for a specific network, use the GET /api/developer/data-packages endpoint:

GET https://YOUR-NETPLUG-API-HOST/api/developer/data-packages?network=TELECEL

No API key is needed for this endpoint. Prices are your reseller prices in GHS.

Response:

{
  "status": "success",
  "data": [
    {
      "capacity": "5",
      "mb": "5000",
      "price": "23.00",
      "network": "TELECEL"
    },
    {
      "capacity": "10",
      "mb": "10000",
      "price": "35.50", 
      "network": "TELECEL"
    },
    // More packages...
  ]
}

You can also get packages for all networks at once:

GET https://YOUR-NETPLUG-API-HOST/api/developer/data-packages

Response (All Networks):

{
  "status": "success",
  "data": {
    "TELECEL": [
      // Vodafone packages
    ],
    "YELLO": [
      // MTN packages
    ],
    "at": [
      // AirtelTigo packages
    ]
  }
}

Order status

GET https://YOUR-NETPLUG-API-HOST/api/developer/order-status/:reference

:reference can be the orderReference, your own reference or the purchaseId. Only your own orders are visible. The response data has the same fields as the purchase response.

orderStatus values

• processing - accepted and being delivered. Keep checking; do not buy again.
• completed - delivered.
• refunded - delivery failed and the price was returned to your wallet automatically.
• failed - delivery failed and is being reviewed; contact support if it does not change.

There are no callbacks: check the order status (for example every 30-60 seconds) until it is final.

Wallet balance

GET https://YOUR-NETPLUG-API-HOST/api/developer/balance

{
  "status": "success",
  "data": { "walletBalance": 177.00, "currency": "GHS" }
}

Purchases are limited per account (all of your API keys share one limit). The standard tier allows 10 purchases per minute, 50 per hour and 200 per day; accounts on the enterprise tier have the per-minute limit only. A repeated request with the same reference does not count. When a limit is reached the API answers HTTP 429 with a Retry-After header (seconds) and nothing is charged.

HTTP status codes

• 201 - order accepted (processing)
• 200 - repeated request: the original order is returned
• 400 - invalid input, unknown package, phone/network mismatch, insufficient wallet balance or network out of stock
• 401 - missing, invalid, inactive or expired API key
• 404 - order not found (order status)
• 409 - reference already used for a different order
• 429 - rate limit reached (see Retry-After)
• 503 - service temporarily unavailable; nothing was charged, try again later

Test the Data Purchase API with your own API key:

Next.js Example:

// pages/api/purchase-data.js
import axios from 'axios';

export default async function handler(req, res) {
  if (req.method !== 'POST') {
    return res.status(405).json({ message: 'Method not allowed' });
  }

  const { phoneNumber, network, capacity } = req.body;
  
  // Validate required fields
  if (!phoneNumber || !network || !capacity) {
    return res.status(400).json({ 
      message: 'Missing required fields' 
    });
  }

  try {
    const response = await axios.post(
      process.env.NETPLUG_API_BASE + '/purchase', // e.g. https://YOUR-NETPLUG-API-HOST/api/developer
      {
        phoneNumber,
        network,
        capacity,
        gateway: 'wallet',
        reference: req.body.reference // your unique order id (safe retries)
      },
      {
        headers: {
          'Content-Type': 'application/json',
          'X-API-Key': process.env.NETPLUG_API_KEY // keep the key on your server only
        }
      }
    );

    return res.status(201).json(response.data);
  } catch (error) {
    console.error('NETPLUG API Error:', error.response?.data || error.message);
    
    return res.status(error.response?.status || 500).json({
      message: 'Failed to purchase data bundle',
      details: error.response?.data || error.message
    });
  }
}

Node.js Example:

// data-service.js
const axios = require('axios');

class NetplugService {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.baseUrl = 'https://YOUR-NETPLUG-API-HOST/api/developer';
    this.httpClient = axios.create({
      baseURL: this.baseUrl,
      headers: {
        'Content-Type': 'application/json',
        'X-API-Key': this.apiKey
      }
    });
  }

  async purchaseData(phoneNumber, network, capacity, reference) {
    try {
      const response = await this.httpClient.post('/purchase', {
        phoneNumber,
        network,
        capacity,
        gateway: 'wallet',
        reference
      });
      
      return response.data;
    } catch (error) {
      console.error('NETPLUG API Error:', error.response?.data || error.message);
      throw error;
    }
  }

  async getOrderStatus(reference) {
    const response = await this.httpClient.get(`/order-status/${encodeURIComponent(reference)}`);
    return response.data;
  }

  async getDataPackages(network = null) {
    try {
      const url = network ? `/data-packages?network=${network}` : '/data-packages';
      const response = await this.httpClient.get(url);
      
      return response.data;
    } catch (error) {
      console.error('Failed to fetch data packages:', error.response?.data || error.message);
      throw error;
    }
  }
}

module.exports = NetplugService;

Python Example:

# netplug_client.py
import requests

class NetplugClient:
    def __init__(self, api_key):
        self.api_key = api_key
        self.base_url = 'https://YOUR-NETPLUG-API-HOST/api/developer'
        self.headers = {
            'Content-Type': 'application/json',
            'X-API-Key': api_key
        }
    
    def purchase_data(self, phone_number, network, capacity, reference):
        """Purchase a data bundle; reference = your unique order id (safe retries)."""
        url = f"{self.base_url}/purchase"
        payload = {
            'phoneNumber': phone_number,
            'network': network,
            'capacity': capacity,
            'gateway': 'wallet',
            'reference': reference
        }
        
        response = requests.post(url, json=payload, headers=self.headers)
        response.raise_for_status()  # Raise exception for 4XX/5XX responses
        
        return response.json()
    
    def get_data_packages(self, network=None):
        """Get available data packages, optionally filtered by network."""
        url = f"{self.base_url}/data-packages"
        if network:
            url += f"?network={network}"
        
        response = requests.get(url, headers=self.headers)
        response.raise_for_status()
        
        return response.json()

# Usage example
if __name__ == "__main__":
    client = NetplugClient("your_api_key_here")
    
    # Get MTN data packages
    mtn_packages = client.get_data_packages("YELLO")
    print(mtn_packages)
    
    # Purchase data bundle
    result = client.purchase_data("0501234567", "TELECEL", "5", "order-1001")
    print(result)