Mozosubz SDK

Buy cheap data and airtime in Nigeria programmatically via the Mozosubz V1 API.

Purchases process synchronously in milliseconds — the API response you get back is the final transaction status (success, transaction_id, amount, and your new wallet balance). No polling or webhooks needed.

| Method | Endpoint | |---|---| | getDataPlans(service) | GET /api/v1/data/plans?service=... | | buyData({ service, planId, phone }) | POST /api/v1/data/purchase | | buyAirtime({ network, amount, phone }) | POST /api/v1/airtime/purchase |

Install

npm install mozosubz-sdk

Zero dependencies. Node 18+.

Quick start

const { Mozosubz } = require('mozosubz-sdk');

const client = new Mozosubz({ apiKey: process.env.MOZOSUBZ_API_KEY });

// 1. Fetch plans in real-time (docs: never hardcode plan IDs)
const { plans } = await client.getDataPlans('mtn_sme');

// 2. Buy data — response is the final status
const order = await client.buyData({
  service: 'mtn_sme',
  planId: plans[0].id,
  phone: '08012345678',
});
console.log(order.transaction_id, order.balance_after);

// 3. Buy airtime (minimum ₦50)
await client.buyAirtime({ network: 'mtn', amount: 100, phone: '08012345678' });

Get your Connect Key (format connect_...) from the API Keys page on mozosubz.xyz — the SDK sends it in the X-Connect-Key header for you.

Data services

mtn_sme, mtn_datashare, mtn_gifting, mtn_awoof, glo_data, glo_sme, airtel_sme, airtel_gifting, etisalat_data

Also available as constants: Mozosubz.DATA_SERVICES.MTN_SME, etc.

Airtime networks

mtn, glo, airtel, etisalat (9mobile)

Error handling

All failures throw MozosubzError with helpers mapped to the documented status codes:

const { MozosubzError } = require('mozosubz-sdk');

try {
  await client.buyData({ service: 'mtn_sme', planId: 'plan_1', phone: '08012345678' });
} catch (err) {
  if (err instanceof MozosubzError) {
    if (err.isAuthError) {                  // 401 — bad/missing key
    } else if (err.isInsufficientBalance) { // 402 — fund your wallet
    } else if (err.isRateLimited) {         // 429 — 10,000 requests/day limit
    } else {
      console.error(err.status, err.message); // 400, 500, or network failure (status null)
    }
  }
}

Safety choices

• Purchases are never auto-retried. A network failure mid-purchase is ambiguous — retrying could double-charge your wallet. Only the read-only getDataPlans retries (2× by default).
• Phone numbers are validated client-side (08012345678 form) before any request is sent.
• Airtime below the documented ₦50 minimum is rejected locally.

Notes

• Rate limit: 10,000 requests/day.
• Keep your key server-side only — never ship it in client-side code.
• Base URL: https://mozosubz.xyz/api/v1 (overridable via new Mozosubz({ baseUrl })).