Mozosubz API · v1

Build VTU into anything.

Sell airtime, data, cable, electricity and recharge pins programmatically using a single Connect Key tied to your Mozosubz wallet. Stable JSON, predictable errors, no surprises.

Get a Connect Key Read auth guide

Base URL

https://api.mozosubz.xyz

Auth header

X-Connect-Key: mzsk_…

Introduction

The Mozosubz v1 API lets you charge your Mozosubz wallet for VTU services from any backend. Every endpoint is JSON in / JSON out, every successful purchase is debited atomically from your wallet, and every transaction is recorded against your account just like a UI purchase.

One credential — a Connect Key — replaces signing, signing keys and OAuth.
All amounts are in Naira (NGN).
All timestamps are ISO‑8601 in UTC.
Wallet, key and webhook actions stay on Mozosubz — you never call providers directly.

Authentication

Authenticate every request with a Connect Key in the X-Connect-Key header. Generate one from Settings → Connect Keys. Each user can have one active key at a time; creating a new one revokes the previous.

bash

curl https://api.mozosubz.xyz/v1/balance \
  -H "X-Connect-Key: mzsk_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Treat your key like a password.Store it in your server's environment variables. Never expose it in client code, mobile apps, or browser-visible bundles. If a key is exposed, revoke it from your dashboard immediately.

Errors & rate limits

The API uses standard HTTP status codes. Error responses always include a success: false field and a human‑readable error message.

Field	Type	Description
200	OK	Request succeeded.
400	Bad request	Missing or invalid parameters.
401	Unauthorized	Missing, invalid or revoked key.
402	Payment required	Insufficient wallet balance.
404	Not found	Resource (e.g. transaction) not found.
429	Too many requests	Rate limit exceeded.
500	Server error	Unexpected server error. Safe to retry idempotent calls.

Rate limit: 10,000 requests per key per 24h. Contact support if you need a higher limit for production traffic.

json

{
  "success": false,
  "error": "Insufficient wallet balance"
}

Get balance

GET/v1/balance

Returns the current available balance on the key holder's wallet, in Naira.

bash

curl https://api.mozosubz.xyz/v1/balance \
  -H "X-Connect-Key: $MOZOSUBZ_KEY"

json

{
  "success": true,
  "balance": 12540.75
}

Start a deposit

POST/v1/deposit/start

Create a one‑time virtual account for funding the wallet. The user pays into the returned account number; once Mozosubz receives Monnify's webhook, the wallet is credited (net of processing fee) automatically. Poll /v1/verify with the returned paymentReference to detect when the deposit lands.

Field	Type	Description
amountrequired	number	Amount to deposit, NGN. Min ₦100, max ₦1,000,000.

bash

curl https://api.mozosubz.xyz/v1/deposit/start \
  -H "X-Connect-Key: $MOZOSUBZ_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 5000 }'

json

{
  "success": true,
  "paymentReference": "MOZO_a1b2c3d4_1731000000000_xyz",
  "amount": 5000,
  "processingFee": 50,
  "netAmount": 4950,
  "accountNumber": "1234567890",
  "bankName": "Wema Bank",
  "accountName": "MOZOSUBZ-USER",
  "expiresAt": "2026-05-17T09:20:00.000Z"
}

List transactions

GET/v1/transactions

Returns the key holder's service transactions, newest first.

Field	Type	Description
limit	number	1–100, default 20.
offset	number	Pagination offset, default 0.
category	string	AIRTIME, DATA, CABLE, ELECTRICITY, RECHARGE_PIN.
status	string	SUCCESS, FAILED, PENDING.

bash

curl "https://api.mozosubz.xyz/v1/transactions?limit=10&category=DATA" \
  -H "X-Connect-Key: $MOZOSUBZ_KEY"

json

{
  "success": true,
  "transactions": [
    {
      "transaction_id": "TX-1731000000000-abcd",
      "category": "DATA",
      "service_id": "mtn-data",
      "service_name": "MTN Data",
      "amount": 1200,
      "phone": "08012345678",
      "status": "SUCCESS",
      "description": "MTN 2GB · 30 days",
      "balance_before": 5000,
      "balance_after": 3800,
      "created_at": "2026-05-17T08:55:12.000Z"
    }
  ],
  "pagination": { "limit": 10, "offset": 0, "total": 42, "hasMore": true }
}

Verify a transaction

POST/v1/verify

Look up either a service transaction_id or a deposit paymentReference. Only transactions belonging to the key holder are returned.

Field	Type	Description
referencerequired	string	transaction_id or paymentReference.

bash

curl https://api.mozosubz.xyz/v1/verify \
  -H "X-Connect-Key: $MOZOSUBZ_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "reference": "MOZO_a1b2c3d4_1731000000000_xyz" }'

json

{
  "success": true,
  "type": "deposit",
  "transaction": {
    "payment_reference": "MOZO_a1b2c3d4_1731000000000_xyz",
    "amount": 5000,
    "net_amount": 4950,
    "status": "SUCCESS",
    "paid_at": "2026-05-17T09:01:33.000Z"
  }
}

Buy airtime

POST/v1/airtime/purchase

Charges the wallet and tops up the recipient line.

Field	Type	Description
serviceIDrequired	string	mtn, airtel, glo, 9mobile (or etisalat).
amountrequired	number	Naira amount. Min ₦50.
phonerequired	string	Recipient phone number, 11 digits.
requestID	string	Optional client‑side idempotency key (echoed back).

bash

curl https://api.mozosubz.xyz/v1/airtime/purchase \
  -H "X-Connect-Key: $MOZOSUBZ_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "serviceID": "mtn",
    "amount": 200,
    "phone": "08012345678"
  }'

json

{
  "success": true,
  "message": "Airtime purchase successful",
  "transactionId": "TX-1731000000000-abcd",
  "balanceBefore": 5000,
  "balanceAfter": 4800
}

Data plans

GET/v1/data/plans

Returns the live data plan catalog for the requested network (sourced from the same VTU provider that powers the Mozosubz dashboard).

Field	Type	Description
networkrequired	string	mtn, airtel, glo, 9mobile (or etisalat).

bash

curl "https://api.mozosubz.xyz/v1/data/plans?network=mtn" \
  -H "X-Connect-Key: $MOZOSUBZ_KEY"

json

{
  "success": true,
  "network": "mtn",
  "plans": [
    { "name": "MTN 1GB · 30 days", "price": 750 },
    { "name": "MTN 2GB · 30 days", "price": 1200 }
  ]
}

Buy data

POST/v1/data/purchase

Field	Type	Description
serviceIDrequired	string	mtn, airtel, glo, 9mobile (or etisalat).
planrequired	string	Plan id (key) returned by /v1/data/plans.
phonerequired	string	Recipient phone number.
amountrequired	number	Plan price in NGN — must match the catalog.
planDisplayName	string	Optional readable plan name for receipts.
requestID	string	Optional client‑side idempotency key.

bash

curl https://api.mozosubz.xyz/v1/data/purchase \
  -H "X-Connect-Key: $MOZOSUBZ_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "serviceID": "mtn",
    "plan": "mtn-2gb-30",
    "phone": "08012345678",
    "amount": 1200
  }'

Cable plans

GET/v1/cable/plans

Field	Type	Description
providerrequired	string	dstv, gotv, startimes.

bash

curl "https://api.mozosubz.xyz/v1/cable/plans?provider=dstv" \
  -H "X-Connect-Key: $MOZOSUBZ_KEY"

Subscribe cable

POST/v1/cable/subscribe

Field	Type	Description
serviceIDrequired	string	dstv, gotv, startimes.
planrequired	string	Package id from /v1/cable/plans.
customerIDrequired	string	Smartcard / IUC number.
phonerequired	string	Subscriber phone number.
amountrequired	number	Package price in NGN — must match the catalog.
requestID	string	Optional idempotency key.

bash

curl https://api.mozosubz.xyz/v1/cable/subscribe \
  -H "X-Connect-Key: $MOZOSUBZ_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "serviceID": "dstv",
    "plan": "dstv-padi",
    "customerID": "1234567890",
    "phone": "08012345678",
    "amount": 2500
  }'

Pay electricity

POST/v1/electricity/purchase

Field	Type	Description
serviceIDrequired	string	Disco code (e.g. ikeja-electric, eko-electric, ibadan-electric).
variation_coderequired	string	prepaid or postpaid.
customerIDrequired	string	Meter number.
amountrequired	number	Amount in NGN. Min ₦500.
phonerequired	string	Customer phone number.
requestID	string	Optional idempotency key.

bash

curl https://api.mozosubz.xyz/v1/electricity/purchase \
  -H "X-Connect-Key: $MOZOSUBZ_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "serviceID": "ikeja-electric",
    "variation_code": "prepaid",
    "customerID": "1234567890",
    "amount": 2000,
    "phone": "08012345678"
  }'

Successful prepaid responses include a token you can show to the customer.

Generate recharge pins

POST/v1/pins/generate

Field	Type	Description
networkrequired	string	mtn, airtel, glo, 9mobile.
valuerequired	string	Denomination per pin in NGN, e.g. "100", "200".
numberrequired	string	Number of pins to generate, 1–50.

bash

curl https://api.mozosubz.xyz/v1/pins/generate \
  -H "X-Connect-Key: $MOZOSUBZ_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "network": "mtn",
    "value": "200",
    "number": "5"
  }'

json

{
  "success": true,
  "transactionId": "TX-1731000000000-abcd",
  "pins": [
    { "pin": "1234567890123456", "serial": "SR-0001" }
  ],
  "totalCost": 1000,
  "balanceAfter": 4000
}

Need help integrating?

Reach out on WhatsApp and we'll get you live on the API.

Chat on WhatsApp