@lipana/sdk

Official Node.js SDK for the Lipana M-Pesa API. Type-safe, well-documented, and production-ready.

Version: 1.0.2
npm: https://www.npmjs.com/package/@lipana/sdk
Documentation: https://lipana.dev/docs

Installation

npm install @lipana/sdk
# or
yarn add @lipana/sdk
# or
pnpm add @lipana/sdk

Quick Start

import { Lipana } from '@lipana/sdk';

// Initialize the SDK
const lipana = new Lipana({
  apiKey: process.env.LIPANA_SECRET_KEY, // Use secret key for server-side
  environment: 'production' // or 'sandbox' for testing
});

// Create a payment link
const paymentLink = await lipana.paymentLinks.create({
  title: 'Premium Subscription',
  description: 'Monthly subscription to our premium features',
  amount: 5000,
  currency: 'KES',
  allowCustomAmount: false,
  successRedirectUrl: 'https://yourwebsite.com/success'
});

console.log('Payment link created:', paymentLink.url);

// Initiate STK push payment
const stkResponse = await lipana.transactions.initiateStkPush({
  phone: '+254712345678',
  amount: 5000
});

console.log('STK push initiated:', stkResponse.transactionId);

Features

• ✅ Type Safety: Full TypeScript support with autocomplete and type checking
• ✅ Error Handling: Comprehensive error handling with detailed error messages
• ✅ Async/Await: Modern async/await syntax for cleaner, readable code
• ✅ Webhooks: Built-in webhook signature verification utilities

API Reference

Transactions

// List all transactions
const transactions = await lipana.transactions.list({
  status: 'success',
  limit: 50,
  startDate: '2024-01-01',
  endDate: '2024-12-31'
});

// Get a specific transaction
const transaction = await lipana.transactions.retrieve('txn_123456');

// Initiate STK push
const stkResponse = await lipana.transactions.initiateStkPush({
  phone: '+254712345678',
  amount: 5000
});

Payment Links

// Create a payment link
const paymentLink = await lipana.paymentLinks.create({
  title: 'Premium Subscription',
  amount: 5000,
  currency: 'KES'
});

// List payment links
const paymentLinks = await lipana.paymentLinks.list({
  status: 'active',
  limit: 10
});

// Update a payment link
const updatedLink = await lipana.paymentLinks.update('link_123456', {
  status: 'inactive'
});

// Delete a payment link
await lipana.paymentLinks.delete('link_123456');

Webhooks

// Get webhook settings
const settings = await lipana.webhooks.getSettings();

// Update webhook settings
await lipana.webhooks.updateSettings({
  webhookUrl: 'https://yourwebsite.com/webhooks',
  enabled: true
});

// Verify webhook signature
const isValid = lipana.webhooks.verify(
  request.body,
  request.headers['x-lipana-signature'],
  process.env.LIPANA_WEBHOOK_SECRET
);

API Keys

// List all API keys
const apiKeys = await lipana.apiKeys.list();

// Create a new API key
const apiKey = await lipana.apiKeys.create({
  name: 'Production Key',
  environment: 'production'
});

Error Handling

import { Lipana, LipanaError } from '@lipana/sdk';

try {
  const payment = await lipana.transactions.initiateStkPush({
    phone: '+254712345678',
    amount: 5000
  });
} catch (error) {
  if (error instanceof LipanaError) {
    if (error.isAuthenticationError()) {
      console.error('Authentication failed:', error.message);
    } else if (error.isValidationError()) {
      console.error('Validation error:', error.errors);
    } else {
      console.error('Error:', error.message);
    }
  }
}

Configuration

Environment

The SDK supports two environments:

• production: For live transactions
• sandbox: For testing

const lipana = new Lipana({
  apiKey: process.env.LIPANA_SECRET_KEY,
  environment: 'sandbox' // or 'production'
});

Custom Base URL

You can override the default base URL:

const lipana = new Lipana({
  apiKey: process.env.LIPANA_SECRET_KEY,
  baseUrl: 'https://custom-api.example.com/api'
});

Default Base URLs

The SDK automatically uses the correct base URL based on environment:

• Production: https://api.lipana.dev/v1
• Sandbox: https://api-sandbox.lipana.dev/v1

Requirements

• Node.js >= 14.0.0
• TypeScript >= 4.0.0 (optional, but recommended)

License

MIT

Changelog

Version 1.0.2

• ✅ Updated base URLs to use /v1 endpoint
• ✅ Production: https://api.lipana.dev/v1
• ✅ Sandbox: https://api-sandbox.lipana.dev/v1

Version 1.0.1

• ✅ Updated production base URLs
• ✅ Production: https://api.lipana.dev/v1
• ✅ Sandbox: https://api-sandbox.lipana.dev/v1

Version 1.0.0

• 🎉 Initial release
• ✅ Full TypeScript support
• ✅ All API endpoints implemented
• ✅ Webhook signature verification
• ✅ Comprehensive error handling

Support

• Documentation: https://lipana.dev/docs
• npm Package: https://www.npmjs.com/package/@lipana/sdk
• Issues: https://github.com/lipana/lipana-node/issues
• Website: https://lipana.dev