API Documentation — Netpluse Developers

API Reference

NetPulse Developer API

The NetPulse API lets you deliver Ghana mobile data bundles, purchase WAEC and BECE result checker pins, and manage your wallet from any backend. All endpoints speak JSON, authenticate with a single API key, and settle against your NetPulse wallet balance.

Base URL

netpluse.shop

Auth

x-api-key header

Format

JSON

Getting Started

Authentication

Every request must include your secret API key in the x-api-key header. Keys are created in the developer dashboard and can be revoked at any time.

curl

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

Keep your key secret

Never expose your API key in browser code, mobile apps, or public repositories. Rotate immediately from your developer dashboard if a key is leaked.

Getting Started

Base URL

All endpoints are served over HTTPS from a single stable base URL.

https://netpluse.shop/api/v1

Endpoints are versioned under /api/v1. Breaking changes will ship under a new version prefix so existing integrations keep working.

Getting Started

5 minute quick start

Go from zero to your first successful purchase in five copy-paste steps.

Step 1 — Get your API key

Create one in the developer dashboard. Keys start with np_live_… and are shown only once.

Step 2 — Top up your wallet

Add funds from the NetPulse home page. Every API purchase is debited atomically from your wallet balance.

Step 3 — Test your key

curl

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

json

{ "ok": true }

Step 4 — Browse available products

curl

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

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

Step 5 — Make your first purchase

curl

# Buy a data bundle
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"}'

# Buy a WAEC checker pin
curl -X POST https://netpluse.shop/api/v1/checkers/purchase \
  -H "x-api-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type":"waec","quantity":1}'

Data Bundles

GET/api/v1/packages

List every data bundle available for purchase across MTN, Telecel, and AirtelTigo.

Request

No request body. Pass your API key in the header.

Example request

curl

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

Response 200

json

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

POST/api/v1/purchase

Buy and deliver a data bundle to a Ghana phone number.

Body parameters

Parameter	Type	Required	Description
network	string	Required	One of `MTN`, `Telecel`, `AirtelTigo`.
phoneNumber	string	Required	Ghana mobile number, e.g. 0241234567.
capacity	string	Required	Exact size from `/packages`, e.g. `1GB`.
reference	string	Optional	Idempotency key. Re-sending returns the original order.

Example request

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": 3.70,
  "balance": 8.00
}

Error responses

400Unknown packageCheck the network and capacity match a row from /packages.

402Low balanceTop up your NetPulse wallet.

409Duplicate orderSame reference used within 60 seconds. Reuse the returned reference or wait.

Delivery is asynchronous

status starts as processing and typically settles 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 bundle order.

Example 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.

Result Checkers

Overview

Purchase WAEC and BECE result checker pins programmatically. Pins are returned instantly in the API response and deducted from your NetPulse wallet. You can buy up to 50 pins per request for bulk reseller use cases.

Pins are shown once

Pin serial numbers and codes are returned only in the purchase response. Store them securely — for security, they are never logged or included in errors, and cannot be retrieved from history endpoints.

GET/api/v1/checkers

List available result checker types and current prices.

Example request

curl

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

Response 200

json

{
  "success": true,
  "checkers": [
    {
      "id": "waec",
      "name": "WAEC Result Checker",
      "description": "Check WASSCE results",
      "price": 17.50,
      "available": true
    },
    {
      "id": "bece",
      "name": "BECE Result Checker",
      "description": "Check BECE results",
      "price": 17.50,
      "available": true
    }
  ]
}

Error responses

401Invalid API keyCheck the x-api-key header value.

403Key flaggedContact support to review your account.

429Rate limitSlow down and retry after the retryAfter window.

POST/api/v1/checkers/purchase

Purchase one or more result checker pins in a single call.

Body parameters

Parameter	Type	Required	Description
type	string	Required	`waec` or `bece`.
quantity	integer	Optional	Number of pins. Default 1, max 50 per request (tier-limited).
reference	string	Optional	Your unique ID to prevent duplicates.

Example request

curl

curl -X POST https://netpluse.shop/api/v1/checkers/purchase \
  -H "x-api-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "waec",
  "quantity": 1
}'

Bulk request — 5 BECE pins

curl

curl -X POST https://netpluse.shop/api/v1/checkers/purchase \
  -H "x-api-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "bece",
  "quantity": 5,
  "reference": "reseller-2026-06-23"
}'

Response 200

json

{
  "success": true,
  "reference": "NPCHK-1712345678901-abc123",
  "type": "waec",
  "quantity": 1,
  "unit_price": 17.50,
  "total_cost": 17.50,
  "balance_after": 45.00,
  "pins": [
    {
      "serial": "123456789",
      "pin": "987654321",
      "expires": "2026-12-31"
    }
  ]
}

Error responses

400Unavailable / over capChecker disabled, out of stock, or above your tier's max pins per request.

402Insufficient balanceunit_price × quantity exceeds wallet. Top up and retry.

409Duplicate referenceOriginal order returned under the `original` field.

429Rate limitSlow down. See tier limits in the Rate Limits section.

GET/api/v1/checkers/{reference}

Look up a previous checker purchase by reference. Only the buyer can read their own pins.

Example request

curl

curl -H "x-api-key: YOUR_KEY" \
  "https://netpluse.shop/api/v1/checkers/NPCHK-1712345678901-abc123"

Response 200

json

{
  "success": true,
  "reference": "NPCHK-1712345678901-abc123",
  "type": "waec",
  "status": "completed",
  "quantity": 1,
  "unit_price": 17.50,
  "total_cost": 17.50,
  "pins": [
    { "serial": "123456789", "pin": "987654321", "expires": "2026-12-31" }
  ],
  "created_at": "2026-06-23T15:00:00.000Z"
}

Error responses

404Not foundReference does not exist or does not belong to your account.

GET/api/v1/checkers/history

List your checker purchases made via the API. Pins are not included — fetch them from the single-reference endpoint.

Query parameters

Parameter	Type	Required	Description
type	string	Optional	Filter by `waec` or `bece`.
limit	integer	Optional	Results per page. Default 20, max 100.
page	integer	Optional	Page number. Default 1.

Example request

curl

curl -H "x-api-key: YOUR_KEY" \
  "https://netpluse.shop/api/v1/checkers/history?type=waec&limit=20&page=1"

Response 200

json

{
  "success": true,
  "total": 45,
  "page": 1,
  "limit": 20,
  "purchases": [
    {
      "reference": "NPCHK-1712345678901-abc123",
      "type": "waec",
      "quantity": 1,
      "total_cost": 17.50,
      "status": "completed",
      "created_at": "2026-06-23T15:00:00.000Z"
    }
  ]
}

Wallet

GET/api/v1/balance

Return the current wallet balance for the authenticated API key.

Example request

curl

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

Response 200

json

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

Utilities

GET/api/v1/ping

Confirm connectivity and validate that your API key is active.

Example request

curl

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

Response 200

json

{ "ok": true }

Errors

Error codes

All error responses return JSON with an error (or success: false) field describing the problem.

400Bad requestCheck your request body and parameters.

401UnauthorizedCheck your API key is correct.

402Low balanceTop up your NetPulse wallet.

403ForbiddenKey is flagged. Contact support.

404Not foundCheck the reference or endpoint URL.

409DuplicateReference already used. Check history.

429Rate limitSlow down requests. Check the retryAfter field.

500Server errorTry again. Contact support if it persists.

Errors

Rate limits

Rate limits are enforced per API key. Bundle purchases and checker purchases are counted separately.

Data bundle purchases

Tier	Per minute	Per hour	Per day
Starter	10	50	200
Business	50	500	2,000
Enterprise	∞	∞	∞

Result checker purchases

Tier	Per minute	Per hour	Max pins / request
Starter	5	20	5
Business	30	200	20
Enterprise	∞	∞	50

Rate limit response

json

{
  "error": "Rate limit exceeded",
  "retryAfter": 60,
  "tier": "starter",
  "upgradeMessage": "Contact support to upgrade to Business tier"
}