telebirr-ussd

🚀 And that's it. Do your thing and Give us a star if this helped you.🚀

Telebirr USSD Node.js Client

A Node.js client library for interacting with the Telebirr USSD payment service. This package provides a simple and type-safe way to integrate Telebirr USSD payments into your Node.js applications.

Features

• TypeScript support with full type definitions
• Push and pull payment operations
• Payment status checking
• Automatic retries for failed requests
• Comprehensive error handling
• Configurable logging
• Input validation
• Promise-based API

Installation

npm install telebirr-ussd

Quick Start

import { TelebirrUSSD } from 'telebirr-ussd';

// Create a new client instance
const client = new TelebirrUSSD({
  baseURL: 'https://api.ethiotelecom.et',
  apiKey: 'your-api-key',
});

// Initiate a push payment
const response = await client.push({
  amount: 100,
  phone: '0912345678',
  reference: 'ORDER-123',
  description: 'Payment for order #123',
});

console.log('Payment initiated:', response);

Configuration

The client accepts the following configuration options:

interface TelebirrConfig {
  baseURL: string; // Base URL for the API
  apiKey: string; // Your API key
  timeout?: number; // Request timeout in milliseconds (default: 30000)
  maxRetries?: number; // Maximum number of retries (default: 3)
  retryDelay?: number; // Delay between retries in milliseconds (default: 1000)
}

API Reference

Push Payment

Initiate a push payment request to a customer's phone number.

async push(request: PushRequest): Promise<PushResponse>

interface PushRequest {
  amount: number;       // Payment amount
  phone: string;        // Recipient's phone number
  reference: string;    // Unique reference number
  description?: string; // Optional payment description
}

Pull Payment

Initiate a pull payment request from a customer's phone number.

async pull(request: PullRequest): Promise<PullResponse>

interface PullRequest {
  amount: number;       // Payment amount
  phone: string;        // Customer's phone number
  reference: string;    // Unique reference number
  description?: string; // Optional payment description
}

Check Payment Status

Check the status of a payment using its reference number.

async status(request: StatusRequest): Promise<StatusResponse>

interface StatusRequest {
  reference: string;    // Payment reference number
}

Error Handling

The client uses a custom error class TelebirrRequestError for all API-related errors. You can catch and handle these errors in your application:

try {
  const response = await client.push({
    amount: 100,
    phone: '0912345678',
    reference: 'ORDER-123',
  });
} catch (error) {
  if (error instanceof TelebirrRequestError) {
    console.error('Payment failed:', error.message);
  }
}

Input Validation

The client includes built-in validation for all input parameters:

• Phone numbers must be valid Ethiopian mobile numbers (starting with 09)
• Amounts must be greater than 0 and not exceed 1,000,000 ETB
• Reference numbers must be between 3 and 50 characters and contain only letters, numbers, underscores, and hyphens

Logging

The client includes a built-in logger that can be configured to output debug information:

import { Logger, LogLevel } from 'telebirr-ussd';

// Configure the logger
const logger = new Logger({
  level: LogLevel.DEBUG,
  prefix: '[MyApp]',
  enableConsole: true,
});

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

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