Lenco Mobile Money for Web (React / Next.js)

Lightweight JavaScript utility to collect mobile money via Lenco from web apps built with React, Next.js, or any modern frontend framework.

⚠️ Security: Always store your Lenco secret key in environment variables (e.g., .env files) and never hardcode it directly in your code. 📝 Note: You must create a Lenco account to obtain your API key before using this package.

Install

npm i lenco-mobile-money-web

Environment Variables

This library requires your Lenco secret key. Copy the example file and update it:

cp .env.example .env

Edit your .env file and replace values with your own credentials from Lenco:

NEXT_PUBLIC_LENCO_SEC_KEY=your-lenco-secret-key

⚠️ Do not commit .env to source control. Only .env.example should be shared.

Quick Start (React / Next.js)

import { processMobileMoneyPayment } from "lenco-mobile-money-web";

async function pay() {
  const result = await processMobileMoneyPayment({
    apiKey: process.env.NEXT_PUBLIC_LENCO_SEC_KEY, // stored in .env
    provider: "mtn", // "mtn" | "airtel" | "zamtel"
    phone: "2609XXXXXXXX",
    amount: 50,
    bearer: "merchant", // or "customer"
    onOTP: async () => {
      // Collect OTP from user via input prompt or modal
      return window.prompt("Enter the OTP sent to your phone:");
    },
    onStatus: (status, payload) => {
      console.log("Status update:", status, payload);
    },
  });

  if (result.success) {
    console.log("Paid!", result);
  } else {
    console.log("Not paid:", result);
  }
}

Options

• provider: "mtn" | "airtel" | "zamtel"
• phone: MSISDN (e.g. 2609...)
• amount: number
• bearer: "merchant" (default) or "customer"
• country: default "zm"
• apiKey: Lenco secret key (use environment variable)
• reference: optional custom reference (defaults to uuid.v4())
• pollInterval: ms between status checks (default 3000)
• maxAttempts: default 40
• onOTP: async ({ reference, provider, phone, amount }) => string
• onStatus: (status, payload) => void
• signal: optional AbortSignal to cancel

Returns

{
  success: boolean,
  status: "pending" | "successful" | "failed" | "otp-required" | "pay-offline",
  reference: string,
  data?: {
    id: string,
    initiatedAt: string,
    completedAt: string | null,
    amount: string,
    fee: string | null,
    bearer: "merchant" | "customer",
    currency: string,
    reference: string,
    lencoReference: string,
    type: "mobile-money",
    status: "pending" | "successful" | "failed" | "otp-required" | "pay-offline",
    source: "api",
    reasonForFailure: string | null,
    settlementStatus: "pending" | "settled" | null,
    settlement: null,
    mobileMoneyDetails: {
      country: string,
      phone: string,
      operator: string,
      accountName: string | null,
      operatorTransactionId: string | null,
    } | null,
    bankAccountDetails: null,
    cardDetails: null,
  },
  error?: string // e.g. "timeout"
}

OTP UI Hint (Web)

Implement onOTP with a modal or a simple input:

const result = await processMobileMoneyPayment({
  // ...
  onOTP: () =>
    new Promise((resolve) => {
      const code = window.prompt("Enter your OTP:");
      resolve(code);
    }),
});

Abort (optional)

const controller = new AbortController();

processMobileMoneyPayment({
  /* ... */,
  signal: controller.signal,
});

// later
controller.abort();

Security Best Practices

• Store your Lenco secret key in environment variables (NEXT_PUBLIC_LENCO_SEC_KEY for Next.js, VITE_LENCO_SEC_KEY for Vite, etc.).
• Never commit or expose your secret key in public repos.
• Only share .env.example for team members.

License

MIT