API Reference

Integrate SimHosting into your application. All endpoints require authentication via API keys from your merchant dashboard.

Base URL: https://app.paylux.com.ng/api/v1

Authentication

Every request must include your API keys as headers:

X-Public-Key: pk_live_xxxxxxxxxxxx
X-Secret-Key: sk_live_xxxxxxxxxxxx

Generate keys from Dashboard → API Keys. Use pk_test_ / sk_test_ for sandbox mode (no real transactions, no wallet charges).

💡 Idempotency: Include X-Idempotency-Key header with a unique string to prevent duplicate transactions on retries.

Wallet

GET/wallet/balance

Returns your current wallet balance.

Response

{"status": "success", "balance": 15000.00, "bonus_balance": 500.00, "currency": "NGN"}

Airtime

POST/airtime

Purchase airtime for any Nigerian network.

Parameter	Type		Description
network	string	required	mtn, glo, airtel, or 9mobile
phone	string	required	Nigerian phone number (08012345678)
amount	number	required	Amount in Naira (min 50)

// Request
{"network": "mtn", "phone": "08012345678", "amount": 500}

// Response
{"status": "success", "reference": "TX202609281200ABCDE", "amount": 500, "phone": "08012345678", "network": "mtn"}

Data

GET/data/plans

List available data plans. Filter by network with ?network=mtn

{"status": "success", "plans": [{"plan_id": "1", "network": "mtn", "name": "MTN SME 1GB", "volume": "1GB", "validity": "30 days", "price": 250}], "count": 27}

POST/data

Parameter	Type		Description
plan_id	string	required	From /data/plans response
phone	string	required	Nigerian phone number

Cable TV

POST/cable

Parameter	Type		Description
provider	string	required	dstv, gotv, or startimes
smart_card	string	required	Smart card / IUC number
package_code	string	required	Package code
phone	string	required	Phone number
amount	number	required	Amount in Naira

Electricity

POST/electricity

Parameter	Type		Description
disco	string	required	ekedc, ikedc, aedc, phed, eedc, kedco, ibedc, bedc, yedc
meter_number	string	required	Meter number
meter_type	string	required	prepaid or postpaid
amount	number	required	Amount in Naira (min 500)
phone	string	required	Phone number

Success response includes token and units fields for prepaid meters.

Bulk SMS

POST/sms

Parameter	Type		Description
sender	string	required	Sender name (max 11 chars)
recipients	array	required	Array of phone numbers
message	string	required	SMS text (160 chars = 1 page)

Transactions

GET/transactions

List your transactions. Params: ?page=1&per_page=20&status=success&type=airtime

GET/transactions/{reference}

Get a single transaction by reference.

Webhooks

SimHosting sends HMAC-SHA256 signed webhooks to your registered URL after each transaction.

Verify with header X-SimHosting-Signature using your webhook secret.

Events

Event	Description
transaction.success	Transaction completed successfully
transaction.failed	Transaction failed

// Webhook payload
{
  "event": "transaction.success",
  "data": {"reference": "TX...", "type": "airtime", "amount": 500, "status": "success"},
  "timestamp": "2026-09-28T16:00:00+01:00"
}

Error Codes

Code	Meaning
400	Bad request / Transaction failed
401	Invalid API keys
403	Account suspended or no API access
404	Not found
405	Method not allowed
422	Validation error
429	Rate limit exceeded

Rate Limits

Limits are per API key, per minute, based on your membership tier.

Tier	Rate Limit
API Client	120 req/min
Enterprise	300 req/min

Response headers: X-RateLimit-Limit, X-RateLimit-Remaining, Retry-After