Malipopay Node.js SDK

Official Node.js SDK for the Malipopay payment platform. Accept payments via Mobile Money (M-Pesa, Airtel Money, Mixx/YAS, Halopesa, T-Pesa), Bank Transfer (CRDB, NMB), USSD, and Card (Visa, Mastercard) in Tanzania.

Installation

npm install malipopay

Quick Start

import { Malipopay } from "malipopay";

const client = new Malipopay("your-api-key");

// Collect payment via mobile money
const payment = await client.payments.collect({
  description: "Order #1234",
  amount: 10000,
  phoneNumber: "255712345678",
});

console.log(payment.reference); // "PAY-abc123"

Configuration

const client = new Malipopay("your-api-key", {
  environment: "uat",        // "production" (default) or "uat"
  timeout: 30000,            // Request timeout in ms (default: 30000)
  retries: 2,                // Auto-retry on 5xx/429 (default: 2)
  webhookSecret: "whsec_...", // For webhook signature verification
});

Usage

Payments

// Collect payment
const payment = await client.payments.collect({
  description: "Order #1234",
  amount: 10000,
  phoneNumber: "255712345678",
});

// Disburse funds
const payout = await client.payments.disburse({
  description: "Salary payment",
  amount: 50000,
  phoneNumber: "255712345678",
});

// Verify payment status
const status = await client.payments.verify("PAY-abc123");

// Search payments
const results = await client.payments.search({
  status: "COMPLETED",
  from: "2026-01-01",
  to: "2026-03-31",
});

// Create payment link
const link = await client.payments.createLink({
  amount: 25000,
  phoneNumber: "255712345678",
});

Customers

// Create customer
const customer = await client.customers.create({
  phoneNumber: "255712345678",
  firstname: "John",
  lastname: "Doe",
  email: "[email protected]",
});

// Search customers
const customers = await client.customers.search({ query: "John" });

// Verify customer
const verified = await client.customers.verify("255712345678");

Invoices

// Create invoice
const invoice = await client.invoices.create({
  customer: "customer-id",
  items: [
    { description: "Web Development", quantity: 1, unitPrice: 500000 },
  ],
  dueDate: "2026-05-01",
  currency: "TZS",
  taxRate: 18,
});

// Record payment against invoice
await client.invoices.recordPayment({
  invoiceId: "invoice-id",
  amount: 500000,
  reference: "PAY-abc123",
});

Products

const product = await client.products.create({
  name: "Monthly Subscription",
  price: 25000,
  currency: "TZS",
  category: "subscription",
});

Transactions

const transactions = await client.transactions.list();
const tx = await client.transactions.get("tx-id");
const search = await client.transactions.search({ status: "COMPLETED" });

Account

const balance = await client.account.transactions();
const reconciliation = await client.account.reconciliation();

SMS

// Send single SMS
await client.sms.send({
  sender: "MALIPOPAY",
  phoneNumber: "255712345678",
  message: "Your payment was received!",
});

// Send bulk SMS
await client.sms.sendBulk({
  sender: "MALIPOPAY",
  phoneNumber: ["255712345678", "255713456789"],
  message: "Special offer!",
});

Reference Data

const banks = await client.references.banks();
const currencies = await client.references.currencies();
const countries = await client.references.countries();

Webhook Handling

import { Malipopay } from "malipopay";

const client = new Malipopay("your-api-key", {
  webhookSecret: "whsec_your_secret",
});

// Verify and parse webhook
const event = client.webhooks.constructEvent(
  rawBody,                              // request body as string or Buffer
  req.headers["x-malipopay-signature"], // signature header
);

switch (event.type) {
  case "payment.completed":
    console.log("Payment completed:", event.data);
    break;
  case "payment.failed":
    console.log("Payment failed:", event.data);
    break;
}

Express Middleware

import express from "express";
import { webhookMiddleware } from "malipopay";

const app = express();

app.post(
  "/webhooks",
  express.raw({ type: "application/json" }),
  webhookMiddleware({ secret: "whsec_your_secret" }),
  (req, res) => {
    const event = req.malipopayEvent;
    console.log("Event:", event.type);
    res.json({ received: true });
  }
);

Error Handling

import { Malipopay, AuthenticationError, ValidationError } from "malipopay";

try {
  await client.payments.collect({ ... });
} catch (err) {
  if (err instanceof AuthenticationError) {
    console.error("Invalid API key");
  } else if (err instanceof ValidationError) {
    console.error("Validation failed:", err.message, err.fields);
  }
}

Error types: AuthenticationError (401), PermissionError (403), NotFoundError (404), ValidationError (422), RateLimitError (429), ApiError (5xx), ConnectionError (network).

Requirements

• Node.js 18+
• Malipopay API key (get one here)

License

MIT

See Also

| SDK | Install | |-----|---------| | Node.js | npm install malipopay | | Python | pip install malipopay | | PHP | composer require malipopay/malipopay-php | | Java | Maven / Gradle | | .NET | dotnet add package Malipopay | | Ruby | gem install malipopay |

API Reference | OpenAPI Spec | Test Scenarios