Features

Core Features

• Secure payment initialization (Web & Mobile)
• Payment verification
• Split payments & subaccounts
• Bank transfers (single & bulk)
• Direct charge (Telebirr, M-Pesa, etc.)
• Refund processing
• Webhook signature verification

Developer Experience

• Full TypeScript support with type definitions
• Input validation with Zod
• Automatic retry logic with exponential backoff for failed requests
• Request/response logging & debug mode
• Request cancellation support (AbortSignal)
• Comprehensive error handling
• 85%+ test coverage

Installation

# NPM
npm install chapa-nodejs

# Yarn
yarn add chapa-nodejs

# PNPM
pnpm add chapa-nodejs

Quick Start

import { Chapa } from 'chapa-nodejs';

// Initialize with your secret key
const chapa = new Chapa({
  secretKey: process.env.CHAPA_SECRET_KEY,
});

// Initialize a payment
const tx_ref = await chapa.genTxRef();
const response = await chapa.initialize({
  first_name: 'John',
  last_name: 'Doe',
  email: '[email protected]',
  currency: 'ETB',
  amount: '1000',
  tx_ref: tx_ref,
  callback_url: 'https://your-site.com/callback',
  return_url: 'https://your-site.com/return',
});

// Verify payment
const verification = await chapa.verify({ tx_ref });

Configuration Options

const chapa = new Chapa({
  secretKey: 'your-secret-key', // Required
  webhookSecret: 'your-webhook-secret', // Optional: for webhook verification
  logging: true, // Optional: enable request/response logging
  debug: true, // Optional: detailed debug information
  retries: 3, // Optional: retry failed requests (default: 0)
  retryDelay: 2000, // Optional: delay between retries in ms (default: 1000)
  timeout: 30000, // Optional: request timeout in ms (default: 30000)
});

Request Cancellation

All async methods support cancellation via AbortSignal:

const controller = new AbortController();
const timeoutId = setTimeout(() => controller.abort(), 5000);

try {
  const response = await chapa.initialize(
    {
      first_name: 'John',
      last_name: 'Doe',
      email: '[email protected]',
      currency: 'ETB',
      amount: '1000',
      tx_ref: chapa.genTxRef(),
      return_url: 'https://example.com/return',
    },
    controller.signal
  );
} catch (error) {
  if (error.name === 'AbortError') {
    // Request was cancelled
  }
} finally {
  clearTimeout(timeoutId);
}

Documentation

Payment Operations

const response = await chapa.initialize({
  first_name: 'John',
  last_name: 'Doe',
  email: '[email protected]',
  phone_number: '0911234567',
  currency: 'ETB',
  amount: '1000',
  tx_ref: await chapa.genTxRef(),
  callback_url: 'https://example.com/callback',
  return_url: 'https://example.com/return',
  customization: {
    title: 'Payment for Order #123',
    description: 'Thank you for your purchase',
  },
});

const response = await chapa.verify({
  tx_ref: 'TX-XXXXXXXXXXXXX',
});

if (response.data.status === 'success') {
  // Payment successful
}

// Configure with webhook secret
const chapa = new Chapa({
  secretKey: 'your-secret-key',
  webhookSecret: 'your-webhook-secret',
});

// In your webhook endpoint
app.post('/webhook', (req, res) => {
  const signature = req.headers['x-chapa-signature'] as string;
  const rawBody = req.body; // ensure this is the raw body string
  const isValid = chapa.verifyWebhook(rawBody, signature);

  if (isValid) {
    // Process webhook
    res.status(200).send('OK');
  } else {
    res.status(401).send('Invalid signature');
  }
});

Bank Operations

const banks = await chapa.getBanks();

const response = await chapa.transfer({
  account_name: 'John Doe',
  account_number: '1234567890',
  amount: '1000',
  currency: 'ETB',
  reference: 'REF-123',
  bank_code: 128,
});

const response = await chapa.bulkTransfer({
  title: 'Monthly Payroll',
  currency: 'ETB',
  bulk_data: [
    {
      account_name: 'Employee 1',
      account_number: '1234567890',
      amount: '5000',
      reference: 'PAYROLL-001',
      bank_code: 128,
    },
    // ... more transfers
  ],
});

Subaccounts & Split Payments

import { SplitType } from 'chapa-nodejs';

const response = await chapa.createSubaccount({
  business_name: 'My Business',
  account_name: 'John Doe',
  bank_code: 128,
  account_number: '1234567890',
  split_type: SplitType.PERCENTAGE,
  split_value: 0.05, // 5%
});

const response = await chapa.initialize({
  // ... other payment details
  subaccounts: [
    {
      id: 'subaccount-id',
      split_type: SplitType.FLAT,
      split_value: 100,
    },
  ],
});

Direct Charge

const response = await chapa.directCharge({
  mobile: '0911234567',
  currency: 'ETB',
  amount: '100',
  tx_ref: await chapa.genTxRef(),
  type: 'telebirr',
});

Refunds

const response = await chapa.refund({
  tx_ref: 'TX-XXXXXXXXXXXXX',
  reason: 'Customer request',
  amount: '1000', // Optional: partial refund
});

Utility Functions

// Default: TX-XXXXXXXXXXXXXXX
const ref1 = chapa.genTxRef();

// Custom prefix
const ref2 = chapa.genTxRef({ prefix: 'ORDER' });

// No prefix
const ref3 = chapa.genTxRef({ removePrefix: true });

// Custom size
const ref4 = chapa.genTxRef({ size: 20 });

Error Handling

import { HttpException } from 'chapa-nodejs';

try {
  const response = await chapa.initialize({...});
} catch (error) {
  if (error instanceof HttpException) {
    console.error(`Error ${error.status}: ${error.message}`);
  }
}

TypeScript Support

Full TypeScript support with comprehensive type definitions:

import {
  Chapa,
  InitializeOptions,
  InitializeResponse,
  VerifyResponse,
  SplitType,
} from 'chapa-nodejs';

Requirements

• Node.js >= 18.0.0
• TypeScript >= 5.0 (for TypeScript projects)

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Contributors

How to Contribute

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

Project Stats

Activity Graph

Star History

Testing

# Run tests
pnpm test

# Run tests with coverage
pnpm test:coverage

# Run tests in watch mode
pnpm test:watch

Security

Please see our Security Policy for reporting vulnerabilities.

Changelog

See CHANGELOG.md for release history.

License

MIT © Fireayehu Zekarias

Links

• Chapa Official Website
• Chapa API Documentation
• GitHub Repository
• NPM Package
• Issue Tracker

Support

• Email: [email protected]
• Report a Bug
• Request a Feature
• Ask a Question