Sell airtime and data from your product.

Quickstart

All requests use JSON and the base URL https://topupnest.com.ng/api/v1. Send your secret key from a secure backend:

Authorization: Bearer tn_live_your_secret_key
Content-Type: application/json

/plans

Return all enabled data plans. Filter with ?network=MTN, Airtel, Glo or T2.

curl "https://topupnest.com.ng/api/v1/plans?network=MTN" \
  -H "Authorization: Bearer $TOPUPNEST_API_KEY"

{
  "success": true,
  "data": [{
    "id": "plan-id", "network": "MTN", "name": "1GB SME",
    "category": "SME", "validity": "30 days", "amount": 550,
    "currency": "NGN"
  }]
}

/orders

Create a purchase. request_id must be a new UUID. Repeating the same UUID returns the original order and does not charge twice.

Data request

{
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "service": "data", "network": "MTN",
  "phone": "08012345678", "plan_id": "plan-id"
}

Airtime request

{
  "request_id": "550e8400-e29b-41d4-a716-446655440001",
  "service": "airtime", "network": "Airtel",
  "phone": "08012345678", "amount": 200
}

Amounts are expressed in naira. Airtime supports ₦100 to ₦50,000.

/orders/{reference}

Check an order using the UUID supplied as request_id.

curl "https://topupnest.com.ng/api/v1/orders/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer $TOPUPNEST_API_KEY"

{
  "success": true,
  "data": {
    "reference": "550e8400-e29b-41d4-a716-446655440000",
    "service": "data", "network": "MTN", "phone": "08012345678",
    "amount": 550, "charged_amount": 530, "currency": "NGN", "status": "delivered"
  }
}

Statuses and errors

Orders may be delivered, pending, refunded, failed or insufficient_balance. Pending creation returns HTTP 202; poll the status route until the state changes.

{
  "success": false,
  "error": { "code": "invalid_request", "message": "network must be MTN, Airtel, Glo or T2." }
}