Developer Reference

Alheri Data Developer API

Welcome to the Alheri Data Plug Developer Platform. Our REST APIs allow software developers, telecom aggregators, and fintech resellers to automate data bundle purchases, query live transaction states, and monitor wallet balances programmatically.

Instant Delivery

Automated sub-5s direct gateway top-ups for MTN, Airtel, Glo & 9mobile.

Zero Overdrafts

Atomic database balance debits with comprehensive double-spend protection.

Agent Pricing

All developers automatically receive discounted wholesale reseller rates.

Security

Authentication

Every API request requires an API key starting with the prefix ALD_. You can generate and rotate your keys inside the client app at Quick Services > API Keys.

Pass your API key in the standard HTTP Authorization header with the Bearer scheme, or using the custom x-api-key header.

Authorization Header Format

Authorization: Bearer ALD_9xK2_wM7p-V8qL1zR4_T3yU6bF0_eA5sD8_jH2mN9-kL0
# or alternative custom header:
x-api-key: ALD_9xK2_wM7p-V8qL1zR4_T3yU6bF0_eA5sD8_jH2mN9-kL0

Important Security Notice: Keep your API keys confidential. Do not embed keys in client-side applications (mobile APKs or web frontend JavaScript). Always route API requests from your own secure backend server.

Environment

Base URL & Network Codes

All REST API requests are served over HTTPS from the production endpoint:

Production Base URL

https://alheridata.com/api/v1

Supported Network Identifiers

networkId	Network Name	Available Types	Status
1	MTN	SME, Corporate Gifting, Direct	Active
2	GLO	Corporate Gifting, Direct	Active
3	9MOBILE	SME, Corporate Gifting	Active
4	AIRTEL	Corporate Gifting, Direct	Active

Wholesale Partner Rates

Automated Agent Pricing

All developer accounts integrated via the API automatically enjoy **Agent Tier (Wholesale Pricing)** on every data plan. You do not need to apply or manually request an account upgrade—our backend automatically calculates and charges the lowest wholesale rate for all API transactions.

GET/data/plans

Fetch Data Plans

Returns the complete catalog of active data bundles with size, validity, and your partner wholesale agent price.

Query Parameters

Parameter	Type	Required	Description
networkId	integer	Optional	Filter plans by network: `1` (MTN), `2` (GLO), `3` (9MOBILE), `4` (AIRTEL).

Example Request

GET https://alheridata.com/api/v1/data/plans?networkId=1

curl -X GET "https://alheridata.com/api/v1/data/plans?networkId=1" \
  -H "Authorization: Bearer ALD_your_api_key"

Sample JSON Response (200 OK)

{
  "status": "SUCCESS",
  "count": 4,
  "networkFilter": 1,
  "plans": [
    {
      "planId": "mtn-sme-500mb",
      "networkId": 1,
      "network": "MTN",
      "name": "MTN SME 500MB",
      "size": "500MB",
      "validity": "30 Days",
      "category": "SME",
      "price": 140.00
    },
    {
      "planId": "mtn-sme-1gb",
      "networkId": 1,
      "network": "MTN",
      "name": "MTN SME 1.0GB",
      "size": "1GB",
      "validity": "30 Days",
      "category": "SME",
      "price": 275.00
    },
    {
      "planId": "mtn-sme-2gb",
      "networkId": 1,
      "network": "MTN",
      "name": "MTN SME 2.0GB",
      "size": "2GB",
      "validity": "30 Days",
      "category": "SME",
      "price": 550.00
    }
  ]
}

POST/data/purchase

Purchase Data Bundle

Submits an immediate data top-up request. Debits your developer balance atomically and dispatches the bundle directly to the recipient phone number.

Request Body (JSON)

Field	Type	Required	Description
planId	string	Required	The plan identifier obtained from the `/data/plans` endpoint (e.g. `"mtn-sme-1gb"`).
phone	string	Required	The recipient 11-digit Nigerian mobile number (e.g. `"08012345678"`).
reference	string	Recommended	Your unique client-side transaction reference string for idempotency and status queries (e.g. `"MY-APP-TX-00921"`).

Example Request Payload

curl -X POST "https://alheridata.com/api/v1/data/purchase" \
  -H "Authorization: Bearer ALD_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "planId": "mtn-sme-1gb",
    "phone": "08012345678",
    "reference": "MY-APP-TX-00921"
  }'

Sample Successful Response (200 OK)

{
  "status": "SUCCESS",
  "message": "Data bundle top-up completed successfully.",
  "transactionId": "MY-APP-TX-00921",
  "reference": "MY-APP-TX-00921",
  "phone": "08012345678",
  "network": "MTN",
  "amount": 275.00,
  "balanceBefore": 15000.00,
  "balanceAfter": 14725.00,
  "createdAt": "2026-08-29T15:30:00.000Z"
}

GET/data/status/:reference

Query Transaction Status

Lookup the live status of any transaction using either your custom partner reference string or internal transaction ID. Crucial for handling upstream network timeouts safely without double spending.

Example Request

curl -X GET "https://alheridata.com/api/v1/data/status/MY-APP-TX-00921" \
  -H "Authorization: Bearer ALD_your_api_key"

Sample Response (200 OK)

{
  "status": "SUCCESS",
  "transaction": {
    "id": "c7a8e1b4-4b5c-48d9-9f7e-123456789abc",
    "reference": "MY-APP-TX-00921",
    "type": "DATA",
    "network": "MTN",
    "phone": "08012345678",
    "amount": 275.00,
    "status": "SUCCESS",
    "balanceBefore": 15000.00,
    "balanceAfter": 14725.00,
    "description": "1.0GB MTN SME Top-up to 08012345678",
    "createdAt": "2026-08-29T15:30:00.000Z"
  }
}

GET/user/balance

Check Developer Wallet Balance

Returns the current available NGN balance and account details for the authenticated developer key.

Example Request

curl -X GET "https://alheridata.com/api/v1/user/balance" \
  -H "Authorization: Bearer ALD_your_api_key"

Sample Response (200 OK)

{
  "status": "SUCCESS",
  "data": {
    "userId": "usr_9981a2b3",
    "name": "Abubakar Data Reseller",
    "phone": "08012345678",
    "balance": 24500.50,
    "currency": "NGN",
    "role": "AGENT",
    "status": "ACTIVE"
  }
}

Reliability

Idempotency & Timeout Handling

To guarantee zero double charges when dealing with mobile network latency:

Unique References: Always supply your own unique reference on purchase requests. If a request with an existing reference is repeated, the API safely returns the original transaction record without charging your balance a second time.

In-Flight Timeout Safeguard: If an upstream telco takes longer than 25 seconds to confirm delivery, the API transitions the transaction to PROCESSING status. Simply poll /data/status/:reference until the final status is reached.

HTTP Statuses

Standard Error Codes Reference

All error responses return a standardized JSON format with an error_code and clear actionable message.

HTTP Code	error_code	Description
400	MISSING_REQUIRED_FIELDS	Missing `planId` or `phone` in request body.
400	INVALID_PHONE_NUMBER	Recipient phone is not a valid 11-digit Nigerian mobile number.
401	UNAUTHORIZED	Missing or malformed Authorization header.
401	INVALID_API_KEY	Provided API key does not exist or does not match any active developer key.
402	INSUFFICIENT_BALANCE	Developer wallet balance is lower than the wholesale cost of the plan.
403	API_KEY_BANNED	API key has been suspended by administration.
404	PLAN_NOT_FOUND	Requested `planId` does not exist or is currently deactivated.
404	TRANSACTION_NOT_FOUND	No transaction exists with the queried reference or ID.
409	REQUEST_IN_PROGRESS	A request with this reference is already in progress. Poll status.
429	RATE_LIMIT_EXCEEDED	Exceeded 60 requests/minute rate limit. Back off and retry.
500	GATEWAY_FAILED	Upstream telecom network error. Balance is automatically refunded.