npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

airtel-money-node-sdk

v1.2.0

Published

A Node.js SDK to integrate with Airtel Money API

Readme

Airtel Money Node SDK

This SDK provides a streamlined integration for Airtel Money payments in Node.js applications, offering both v1 and v2 API versions, token caching, and a retry-based polling mechanism for payment status tracking.

Features

  • Dual API Version Support: Seamless support for both API versions (v1 and v2), including version-based request and response handling.
  • Bearer Token Caching: Implements token caching to optimize API requests and reduce load on authentication services.
  • AES and RSA Encryption: Utilizes AES for data encryption and RSA for secure key exchange in v2 API.
  • Retry Mechanism: Includes configurable retry and timeout settings for polling payment status.
  • Comprehensive Error Handling: Detailed error logging with full response data, headers, and status codes.

Prerequisites

  • Node.js (>= 14.x)
  • NPM or Yarn
  • Airtel Money API access (sandbox or production)

Installation

Install the package in your Node.js project:

npm install airtel-money-node-sdk

Configuration

  1. Copy the env.example file to .env:
cp env.example .env
  1. Update the .env file with your actual values:
# Airtel API Configuration
AIRTEL_API_BASE_URL=https://openapiuat.airtel.africa  # Sandbox URL
# AIRTEL_API_BASE_URL=https://openapi.airtel.africa   # Production URL

# OAuth2 Credentials
CLIENT_ID=your_client_id_here
CLIENT_SECRET=your_client_secret_here
GRANT_TYPE=client_credentials

# Country and Currency Configuration
COUNTRY=UG
CURRENCY=UGX

# API Version (1 or 2)
AIRTEL_API_VERSION=1

# Polling and Retry Configuration
DEFAULT_MAX_RETRIES=5
DEFAULT_POLLING_INTERVAL_MS=5000
POLLING_TIMEOUT=30000

Usage

1. Initialize Payment

To start a payment, call the initiateAirtelPayment function with the payment amount, recipient's phone number, and a reference.

const { initiateAirtelPayment } = require('airtel-money-node-sdk');

async function makePayment() {
    try {
        const amount = '100.00';
        const msisdn = '977XXXXXX';  // Recipient's phone number without country code
        const reference = 'Invoice #12345';  // Reference for the payment

        const paymentStatus = await initiateAirtelPayment(amount, msisdn, reference);
        console.log('Final Payment Status:', paymentStatus);
        
        // paymentStatus will contain:
        // { status: 'SUCCESS' | 'FAILED', data: responseData }
        
    } catch (error) {
        console.error('Payment initiation failed:', error.message);
    }
}

makePayment();

### 2. Poll Payment Status

To check the status of an existing payment without creating a new one, use the `pollPaymentStatus` function:

```javascript
const { pollPaymentStatus } = require('airtel-money-node-sdk');

async function checkPaymentStatus() {
    try {
        const transactionId = 'your_transaction_id_here';
        const status = await pollPaymentStatus(transactionId);
        console.log('Payment Status:', status);
        
        // status will contain:
        // { status: 'SUCCESS' | 'FAILED' | 'PENDING' | 'UNKNOWN', data: responseData, message: string }
        
    } catch (error) {
        console.error('Status check failed:', error.message);
    }
}

checkPaymentStatus();

### 2. API Version Support

The SDK automatically handles both v1 and v2 API requests based on the `AIRTEL_API_VERSION` environment variable:

- **V1 API**: Simple JSON payload with direct transaction ID usage
- **V2 API**: Encrypted payload using AES-256-CBC encryption with RSA key exchange

### 3. Payment Status Polling

The SDK includes an intelligent polling mechanism that:
- Automatically polls payment status based on the configured `DEFAULT_MAX_RETRIES` and `DEFAULT_POLLING_INTERVAL_MS`
- Uses exponential backoff (interval increases with each retry)
- Returns final status: `SUCCESS` (TS), `FAILED` (TF), or throws error on timeout

### 4. Bearer Token Management

The SDK automatically:
- Caches bearer tokens until expiry (minus 60-second buffer)
- Refreshes tokens when needed
- Handles OAuth2 authentication seamlessly

## Environment Variables

| Variable | Description | Default | Required |
|----------|-------------|---------|----------|
| `AIRTEL_API_BASE_URL` | Airtel API base URL | - | Yes |
| `CLIENT_ID` | OAuth2 client ID | - | Yes |
| `CLIENT_SECRET` | OAuth2 client secret | - | Yes |
| `GRANT_TYPE` | OAuth2 grant type | `client_credentials` | Yes |
| `COUNTRY` | Country code (e.g., UG) | - | Yes |
| `CURRENCY` | Currency code (e.g., UGX) | - | Yes |
| `AIRTEL_API_VERSION` | API version (1 or 2) | `1` | No |
| `DEFAULT_MAX_RETRIES` | Maximum polling retries | `5` | No |
| `DEFAULT_POLLING_INTERVAL_MS` | Base polling interval (ms) | `5000` | No |
| `POLLING_TIMEOUT` | API request timeout (ms) | `30000` | No |
| `RSA_PUBLIC_KEY` | API v2 RSA public key | Your Public Key | Yes |

## Error Handling

The SDK provides comprehensive error handling:
- All API errors are logged with full response details
- Automatic retry mechanism for failed requests
- Detailed error messages for debugging
- Graceful handling of network timeouts

## API Endpoints

The SDK interacts with the following Airtel Money API endpoints:

- **Authentication**: `POST /auth/oauth2/token`
- **V1 Payments**: `POST /merchant/v1/payments/`
- **V2 Payments**: `POST /merchant/v2/payments/`
- **V1 Status**: `GET /standard/v1/payments/{transactionId}`
- **V2 Status**: `GET /standard/v1/payments/{reference}`
- **RSA Keys**: `GET /v1/rsa/encryption-keys` (V2 only)

## Contributing

Contributions are welcome! Please read the [CONTRIBUTING.md](./CONTRIBUTING.md) file for detailed guidelines before submitting a pull request or opening an issue.

## License

This project is licensed under the MIT License. See the LICENSE file for details.