AfriLink OSS

The Unified Open-Source SDK for African Mobile Money Payments

One interface. Six networks. 30+ African countries.

Stop writing separate integrations for every mobile money provider. AfriLink OSS gives every African developer a single, consistent API to collect payments, send disbursements, check balances, and verify transactions — across all major African mobile money networks.

Installation · Quick Start · Providers · API Reference · Contributing

---

Why AfriLink OSS?

African developers building fintech products face a painful reality: every mobile money provider has a different API, different auth flow, different webhook format, and different error codes. You end up writing and maintaining six different integrations for one product.

AfriLink OSS solves this. One unified SDK. One consistent interface. Swap providers by changing a single config value.

// Before AfriLink OSS — maintaining 6 different integrations
// After AfriLink OSS — one interface for all of them
const client = afrilink.init({ provider: 'mtn', country: 'UG', ... });
const client = afrilink.init({ provider: 'mpesa', country: 'KE', ... });
const client = afrilink.init({ provider: 'airtel', country: 'TZ', ... });
// Same 4 methods work on all three

---

Supported Providers

Provider	Countries	Methods	Status
MTN MoMo	UG, GH, RW, ZM, CM, CI, BJ, GN + 12 more	collect, disburse, balance, verify	Live
M-Pesa (Safaricom)	KE, TZ, MZ, CD, LS, GH, EG	collect, disburse, balance, verify	Live
Airtel Money	UG, KE, TZ, RW, MW, ZM, MG, CD	collect, disburse, balance, verify	Live
Orange Money	CI, SN, ML, CM, GN, MG, MR + 10 more	collect, disburse	In Progress
Vodacom M-Pesa	TZ, ZA, MZ	collect, disburse, balance, verify	In Progress
Wave	SN, CI, ML, BF, UG	collect, verify	In Progress

Coverage: 30+ African countries across 6 networks

---

Installation

npm install afrilink-oss

Or with yarn:

yarn add afrilink-oss

---

Quick Start

1. Set up environment variables

cp .env.example .env
# Fill in your API keys from your provider's developer portal

2. Initialize and use

const afrilink = require('afrilink-oss');

const client = afrilink.init({
  provider: 'mtn',        // 'mtn' | 'mpesa' | 'airtel' | 'orange' | 'vodacom' | 'wave'
  country: 'UG',          // ISO country code
  apiKey: process.env.MTN_API_KEY,
  apiSecret: process.env.MTN_API_SECRET,
  environment: 'sandbox'  // 'sandbox' | 'production'
});

// Collect a payment from a customer
const payment = await client.collect({
  phone: '256771234567',
  amount: 5000,
  currency: 'UGX',
  reference: 'ORDER-001',
  callbackUrl: 'https://yourapp.com/webhook'
});

// Send money to a customer
const payout = await client.disburse({
  phone: '256771234567',
  amount: 5000,
  currency: 'UGX',
  reference: 'PAYOUT-001',
  note: 'Salary payment'
});

// Check wallet balance
const balance = await client.balance();

// Verify a transaction
const status = await client.verify({ transactionId: 'TXN123456' });

---

API Reference

afrilink.init(config)

Parameter	Type	Required	Description
provider	string	Yes	mtn, mpesa, airtel, orange, vodacom, wave
country	string	Yes	ISO 3166-1 alpha-2 country code (e.g. UG, KE, GH)
apiKey	string	Yes	Your provider API key
apiSecret	string	Yes	Your provider API secret
environment	string	Yes	sandbox or production

---

client.collect(options)

Initiate a payment request from a customer's mobile money wallet.

Parameter	Type	Required	Description
phone	string	Yes	Customer phone number with country code
amount	number	Yes	Amount to collect
currency	string	Yes	ISO currency code (UGX, KES, GHS, etc.)
reference	string	Yes	Your unique transaction reference
callbackUrl	string	No	Webhook URL for async status updates

---

client.disburse(options)

Send money from your wallet to a customer.

Parameter	Type	Required	Description
phone	string	Yes	Recipient phone number with country code
amount	number	Yes	Amount to send
currency	string	Yes	ISO currency code
reference	string	Yes	Your unique transaction reference
note	string	No	Payment note/narration

---

client.balance()

Returns current wallet balance. No parameters required.

---

client.verify({ transactionId })

Check the status of any transaction by its ID.

---

afrilink.parseWebhook(provider, body, headers)

Normalize webhook payloads from any provider into one standard format:

app.post('/webhook', (req, res) => {
  const event = afrilink.parseWebhook('mtn', req.body, req.headers);
  // Returns: { transactionId, status, amount, currency, phone, provider, timestamp, raw }
  res.sendStatus(200);
});

---

Environment Variables

# MTN MoMo — https://momodeveloper.mtn.com
MTN_API_KEY=
MTN_API_SECRET=
MTN_SUBSCRIPTION_KEY=
MTN_ENVIRONMENT=sandbox

# M-Pesa Safaricom — https://developer.safaricom.co.ke
MPESA_CONSUMER_KEY=
MPESA_CONSUMER_SECRET=
MPESA_SHORTCODE=
MPESA_PASSKEY=
MPESA_ENVIRONMENT=sandbox

# Airtel Money — https://developer.airtel.africa
AIRTEL_CLIENT_ID=
AIRTEL_CLIENT_SECRET=
AIRTEL_ENVIRONMENT=sandbox

# Orange Money — https://developer.orange.com
ORANGE_CLIENT_ID=
ORANGE_CLIENT_SECRET=

# Vodacom M-Pesa — https://openapi.vodacom.com
VODACOM_CLIENT_ID=
VODACOM_CLIENT_SECRET=

# Wave — https://wave.com/en/developers
WAVE_API_KEY=

---

Get Your Sandbox API Keys

Provider	Developer Portal	Approval Time
MTN MoMo	https://momodeveloper.mtn.com	Instant
M-Pesa	https://developer.safaricom.co.ke	Instant
Airtel Money	https://developer.airtel.africa	24-48 hours
Orange Money	https://developer.orange.com	24-72 hours
Vodacom	https://openapi.vodacom.com	48-72 hours
Wave	https://wave.com/en/developers	Varies

---

Error Handling

const { AfriLinkError, AuthError, NetworkError, ValidationError } = require('afrilink-oss');

try {
  await client.collect({ phone, amount, currency, reference });
} catch (err) {
  if (err instanceof AuthError) {
    console.log('Invalid API credentials');
  } else if (err instanceof ValidationError) {
    console.log('Invalid parameters:', err.message);
  } else if (err instanceof NetworkError) {
    console.log('Network/provider error:', err.statusCode);
  }
  // All errors include: message, code, provider, statusCode, raw
}

---

Roadmap

• MTN MoMo (Uganda, Ghana, Rwanda + 12 countries)
• M-Pesa Safaricom (Kenya, Tanzania + 5 countries)
• Airtel Money (Uganda, Kenya, Tanzania + 5 countries)
• Orange Money (17 Francophone African countries)
• Vodacom M-Pesa (Tanzania, South Africa, Mozambique)
• Wave (Senegal, Ivory Coast, Mali, Burkina Faso, Uganda)
• PalmPay (Nigeria)
• Moov Money (Benin, Togo, Niger)
• TypeScript types
• Python SDK
• Webhook signature verification
• Retry logic with exponential backoff

---

Contributing

AfriLink OSS is built for African developers, by African developers. Contributions are what make this project grow — every PR matters.

How to contribute

1. Fork the repository
2. Create your feature branch: git checkout -b feat/add-wave-provider
3. Commit your changes: git commit -m 'feat: add Wave Money provider'
4. Push to the branch: git push origin feat/add-wave-provider
5. Open a Pull Request

Good first issues

• Add a new provider (Orange Money, Wave, PalmPay)
• Add TypeScript type definitions
• Improve test coverage
• Add a new country to an existing provider
• Improve documentation or examples

See CONTRIBUTING.md for detailed guidelines.

---

Community

• Found a bug? Open an issue
• Have an idea? Start a discussion
• Find this useful? Give us a star — it helps other African developers find this project

---

License

MIT (c) 2026 AfriLink OSS Contributors

Built with love for Africa's developer community