airtime-pay

Unified TypeScript SDK for Airtel Money and TNM Mpamba — Malawi's two major mobile money providers. One interface, both providers, full TypeScript types.

Built by Prince Thawani · [email protected]

---

Features

• Single createAirtimePay() factory — swap providers with one config change
• Full TypeScript types — same shape for both providers
• Automatic OAuth2 token refresh (Airtel)
• Malawian phone number normalization — accepts 0888..., 265888..., +265888...
• MKW money utilities — safe tambala arithmetic, MK 1,000.00 formatting
• Built-in retry with exponential backoff
• MockProvider for unit tests — no network, full scenario control
• Zero runtime dependencies

Installation

npm install airtime-pay

Quickstart

import { createAirtimePay } from "airtime-pay";

// ── Airtel Money ───────────────────────────────────────────────────────────────
const airtel = createAirtimePay({
  provider: "airtel",
  clientId: process.env.AIRTEL_CLIENT_ID!,
  clientSecret: process.env.AIRTEL_CLIENT_SECRET!,
});

// ── TNM Mpamba ────────────────────────────────────────────────────────────────
const mpamba = createAirtimePay({
  provider: "mpamba",
  apiKey: process.env.MPAMBA_API_KEY!,
});

// ── Same API for both ─────────────────────────────────────────────────────────
const result = await airtel.pay({
  amount: 100_000,       // MK 1,000 in tambala (1 tambala = MK 0.01)
  currency: "MWK",
  phone: "0888123456",   // any Malawian format accepted
  reference: "ORDER-001",
  description: "Payment for order #001",
});

console.log(result.status);        // "successful" | "pending" | "failed"
console.log(result.transactionId); // provider transaction ID
console.log(result.phone);         // "+265888123456" (normalized)

All methods

// Initiate a payment
const payment = await provider.pay({ amount, phone, reference, description? });

// Check wallet balance
const balance = await provider.balance();
console.log(balance.balance); // in tambala

// Check transaction status
const status = await provider.status(transactionId);

// Refund a transaction
const refund = await provider.refund({ transactionId, amount? }); // amount omit = full refund

Amounts — tambala

All amounts are in tambala (the smallest unit of MKW), the same way Stripe uses cents.

You want	You pass
MK 1,000	100_000
MK 500	50_000
MK 50	5_000

import { toTambala, toKwacha, formatMKW } from "airtime-pay";

toTambala(1000)      // → 100000
toKwacha(100000)     // → 1000
formatMKW(100000)    // → "MK 1,000.00"

Phone numbers

Any Malawian format is accepted — the SDK normalizes to E.164 internally.

import { normalizePhone, detectNetwork } from "airtime-pay";

normalizePhone("0888123456")   // → "+265888123456"
normalizePhone("265888123456") // → "+265888123456"
normalizePhone("+265888123456") // → "+265888123456"

detectNetwork("0888123456")   // → "airtel"
detectNetwork("0999456789")   // → "tnm"

Testing with MockProvider

Use MockProvider in your tests — no network calls, no credentials needed.

import { MockProvider } from "airtime-pay";
import { describe, it, expect, beforeEach } from "vitest";

const mock = new MockProvider({ provider: "mock" });

beforeEach(() => mock.reset());

it("charges a customer", async () => {
  const result = await mock.pay({
    amount: 50_000,
    phone: "0888123456",
    reference: "ORDER-001",
  });
  expect(result.status).toBe("successful");
});

it("handles declined payment", async () => {
  mock.use("insufficientBalance");
  await expect(
    mock.pay({ amount: 50_000, phone: "0888123456", reference: "ORDER-002" })
  ).rejects.toMatchObject({ code: "INSUFFICIENT_BALANCE" });
});

Available scenarios

Scenario	Behaviour
success	Payment succeeds (default)
pending	Payment stays pending
failed	Payment fails
insufficientBalance	Throws INSUFFICIENT_BALANCE
invalidPhone	Throws INVALID_PHONE
timeout	Throws TIMEOUT
networkError	Throws NETWORK_ERROR
duplicate	Throws DUPLICATE_TRANSACTION

mock.use("pending");                              // named scenario
mock.useCustom({ payment: { status: "processing" } }); // custom
mock.setBalance(500_000);                         // set wallet balance

Webhook events in tests

const handler = vi.fn();
mock.on("payment.successful", handler);

await mock.pay({ amount: 10_000, phone: "0888123456", reference: "R1" });

expect(handler).toHaveBeenCalledOnce();
expect(handler.mock.calls[0][0].type).toBe("payment.successful");

// Inspect full history
const events = mock.getEventHistory();

Error handling

import { AirtimePayError } from "airtime-pay";

try {
  await provider.pay({ amount: 10_000, phone: "0888123456", reference: "R1" });
} catch (err) {
  if (err instanceof AirtimePayError) {
    console.log(err.code);       // "INSUFFICIENT_BALANCE"
    console.log(err.provider);   // "airtel" | "mpamba" | "mock"
    console.log(err.statusCode); // 402
    console.log(err.message);    // human-readable message
  }
}

Error codes

Code	Meaning
INVALID_CREDENTIALS	Wrong API key or client secret
INSUFFICIENT_BALANCE	Customer wallet has insufficient funds
INVALID_PHONE	Phone number could not be normalized
TRANSACTION_NOT_FOUND	No transaction with that ID
DUPLICATE_TRANSACTION	Reference already used
REFUND_NOT_ALLOWED	Transaction not in refundable state
INVALID_AMOUNT	Amount is zero, negative, or exceeds original
PROVIDER_ERROR	Provider returned an unexpected error
NETWORK_ERROR	Could not reach the provider API
TIMEOUT	Request exceeded timeout

Docker

# Run tests
docker compose up test

# Watch mode for development
docker compose up dev

# Build production image
docker compose up prod

Project structure

airtime-pay/
├── config/                          # Config types and defaults
├── middlewares/                     # Errors, retry, logger
├── src/
│   ├── payments/interface/types.ts  # All shared domain types
│   └── providers/
│       ├── airtel/AirtelProvider.ts
│       ├── mpamba/MpambaProvider.ts
│       └── mock/MockProvider.ts
├── utils/                           # phone, money, ID helpers
├── tests/
├── .github/workflows/ci.yml        # GitHub Actions CI
├── .env.example
├── docker-compose.yml
├── Dockerfile
└── index.ts                         # Public API

Contributing

See CONTRIBUTING.md — adding a new provider takes about 30 minutes.

License

MIT © Prince Thawani