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

buydata.space

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://buydata.space/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://buydata.space/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://buydata.space/api/v1/ping

json

{ "ok": true }

Step 4 — Browse available products

curl

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

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

Step 5 — Make your first purchase

curl

# Buy a data bundle
curl -X POST https://buydata.space/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://buydata.space/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. MTN Mashup offers are returned separately under mashup.

Request

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

Example request

curl

curl -H "x-api-key: YOUR_KEY" \
  "https://buydata.space/api/v1/packages"

Response 200

json

{
  "packages": [
    {
      "network": "MTN",
      "capacity": "1GB",
      "price": 3.70,
      "validity": "30 Days"
    }
  ],
  "mashup": [
    {
      "product": "mashup",
      "network": "MTN",
      "capacity": "10",
      "id": "mashup-10",
      "size": "Mashup 10GB",
      "price": 14.27,
      "validity": "30 days",
      "allowances": {
        "dataAllowance": "511 MB",
        "mtnMinutes": 176,
        "otherMinutes": 22,
        "sms": 45,
        "validityDays": 30
      }
    }
  ]
}

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`.
product	string	Optional	Use `mashup` for MTN Mashup; omit for ordinary data.
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://buydata.space/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"
}'

MTN Mashup

Mashup combo packs are bought through this same endpoint — send product: "mashup" with the capacity identifier from the catalogue. The full request, response and error reference lives in the MTN Mashup section.

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://buydata.space/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.

MTN Mashup

Overview

Mashup is an MTN-only combo pack: data, on-net minutes, other-network minutes and SMS in a single purchase. It runs on your existing API key, wallet and endpoints — there is no separate Mashup API, key or balance.

Mashup rows come back on GET /api/v1/packages in their own mashup array, never mixed with ordinary data rows. Buy with POST /api/v1/purchase and track with GET /api/v1/order-status/{reference}.

Availability

Mashup only appears in the catalogue while it is enabled and its API selling price is configured. Premium and Special Access API accounts never see or buy Mashup.

Catalogue row

json

{
  "product": "mashup",
  "network": "MTN",
  "capacity": "10",
  "id": "mashup-10",
  "size": "Mashup 10GB",
  "price": 14.27,
  "validity": "30 days",
  "allowances": {
    "dataAllowance": "511 MB",
    "mtnMinutes": 176,
    "otherMinutes": 22,
    "sms": 45,
    "validityDays": 30
  }
}

Capacity is an identifier, not a data size

capacity such as "10" identifies the package — it is not the data allowance. The real contents ship with every row in allowances: dataAllowance, mtnMinutes, otherMinutes, sms and validityDays. Always read them from the live catalogue.

POST/api/v1/purchase

Buy an MTN Mashup combo pack. Same endpoint as ordinary data — the only difference is product: mashup.

Body parameters

Parameter	Type	Required	Description
product	string	Required	Always `mashup` for a Mashup order.
network	string	Required	Always `MTN`. Mashup is not offered on other networks.
capacity	string	Required	Package identifier from the catalogue, e.g. `10`, `20`, `30`.
phoneNumber	string	Required	Ghana mobile number to receive the combo pack.
reference	string	Optional	Idempotency key. Re-sending returns the original order.

Example request

curl

curl -X POST https://buydata.space/api/v1/purchase \
  -H "x-api-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "product": "mashup",
  "network": "MTN",
  "capacity": "10",
  "phoneNumber": "0241234567",
  "reference": "my-mashup-ref-001"
}'

Response 200

json

{
  "reference": "my-mashup-ref-001",
  "status": "processing",
  "price": 14.27,
  "balance": 8.00
}

Error responses

400Mashup unavailableMashup is disabled, its API price is not configured, or the capacity is not in the catalogue.

400Mashup requires the MTN networkSend network: MTN.

402Low balanceTop up your NetPulse wallet.

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

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

Track a Mashup order exactly like a data order — the same endpoint and the same statuses apply.

Example request

curl

curl -H "x-api-key: YOUR_KEY" \
  "https://buydata.space/api/v1/order-status/my-mashup-ref-001"

Response 200

json

{
  "reference": "my-mashup-ref-001",
  "network": "MTN",
  "capacity": "Mashup 10GB",
  "status": "completed",
  "createdAt": "2026-06-15T10:24:00.000Z"
}

Mashup orders return the same status values as data orders, so one tracker covers both products.

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://buydata.space/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://buydata.space/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://buydata.space/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://buydata.space/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://buydata.space/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://buydata.space/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://buydata.space/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"
}