API Documentation — Netpluse Developers

Getting Started

The Netpluse API lets you automate data bundle purchases, check your wallet balance, and look up order status from any backend. It's a simple REST API with JSON requests and responses.

Base URL

https://netpluse.shop

Quick start

Generate an API key from your developer dashboard.
Top up your wallet at netpluse.shop.
Call GET /api/v1/ping to verify your key.
Call GET /api/v1/packages for available bundles.
Call POST /api/v1/purchase to deliver data.

Authentication

Every request must include your API key in the x-api-key header. Keys are issued from the developer dashboard and shown only once at creation — store them securely.

header

x-api-key: np_live_xxxxxxxxxxxxxxxx

Requests without a valid, active key return 401 Unauthorized. Never embed API keys in client-side code — call the API from your server only.

GET

/api/v1/ping

Test that your API key is valid and active.

Request

curl

curl -H "x-api-key: YOUR_KEY" \
  https://netpluse.shop/api/v1/ping

Response 200

json

{
  "ok": true,
  "owner": "uuid"
}

Errors

401 — Invalid or inactive API key.

GET

/api/v1/balance

Get your current wallet balance in GHS.

Request

curl

curl -H "x-api-key: YOUR_KEY" \
  https://netpluse.shop/api/v1/balance

Response 200

json

{
  "balance": 12.50,
  "currency": "GHS"
}

GET

/api/v1/packages

List all available data bundles with current prices.

Request

curl

curl -H "x-api-key: YOUR_KEY" \
  https://netpluse.shop/api/v1/packages

Response 200

json

{
  "packages": [
    {
      "network": "MTN",
      "capacity": "1GB",
      "price": 4.50,
      "validity": "30 Days"
    }
  ]
}

POST

/api/v1/purchase

Purchase and deliver a data bundle to a phone number.

Request body

Name	Type	Required	Description
network	string	Yes	One of "MTN", "Telecel", "AirtelTigo".
phoneNumber	string	Yes	Ghana mobile number, e.g. 0241234567.
capacity	string	Yes	Exact size from /packages, e.g. "1GB".
reference	string	No	Your idempotency key. Re-sending the same reference returns the original order.

Example

curl

curl -X POST https://netpluse.shop/api/v1/purchase \
  -H "x-api-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "network": "MTN",
    "phoneNumber": "0241234567",
    "capacity": "1GB",
    "reference": "my-ref-001"
  }'

Response 200

json

{
  "reference": "NPAPI-1234-abc",
  "status": "processing",
  "price": 4.50,
  "balance": 8.00
}

Errors

400 — Unknown package or invalid network.
401 — Invalid API key.
402 — Insufficient wallet balance.
409 — Duplicate order (same reference within 1 minute).

Deliveries process asynchronously. Status starts as processing and typically moves to completed within ~4 seconds. Poll /order-status for the final state.

GET

/api/v1/order-status/{reference}

Check the current status of a previously created order.

Request

curl

curl -H "x-api-key: YOUR_KEY" \
  https://netpluse.shop/api/v1/order-status/NPAPI-1234-abc

Response 200

json

{
  "reference": "NPAPI-1234-abc",
  "network": "MTN",
  "capacity": "1GB",
  "status": "completed",
  "createdAt": "2026-06-15T10:24:00.000Z"
}

status transitions from processing to completed or failed.

Error Codes

All errors return JSON with an error field describing the problem.

Name	Type	Required	Description
400	Bad Request	No	Invalid input, unknown package, or malformed JSON.
401	Unauthorized	No	Missing, invalid, or revoked API key.
402	Payment Required	No	Wallet balance too low to complete the purchase.
404	Not Found	No	Order reference does not exist.
409	Conflict	No	Duplicate purchase with the same reference within 1 minute.
429	Too Many Requests	No	Rate limit exceeded — slow down and retry.
500	Server Error	No	Unexpected server error. Safe to retry purchases with the same reference.

Rate Limits

The API enforces fair-use rate limits per API key to keep deliveries fast for everyone.

Read endpoints (/ping, /balance, /packages, /order-status): up to 60 requests / minute.
Purchase endpoint: up to 30 requests / minute, with duplicate-reference protection within a 1-minute window.

Exceeding a limit returns 429 Too Many Requests. Back off and retry after a short delay. Need higher limits? Contact support from your dashboard.