@moncashconnect/sdk

Official Node.js / TypeScript SDK for MonCashConnect — the easiest way to integrate MonCash payments in your JavaScript or TypeScript application.

Note: MonCashConnect is not affiliated with Digicel or the official MonCash service.

Requirements

• Node.js 18+ (uses native fetch)
• TypeScript 5+ (optional — full types included)

Installation

npm install @moncashconnect/sdk
# or
pnpm add @moncashconnect/sdk

Quick Start

import { MonCashClient } from "@moncashconnect/sdk";

const client = new MonCashClient(process.env.MCC_SECRET_KEY!);

const payment = await client.createPayment(1500, "ORDER-001", {
  returnUrl:    "https://yoursite.com/payment/success",
  customerName: "Jean Dupont",
});

// Redirect the customer to MonCash
res.redirect(payment.paymentUrl);

Your secret key starts with sk_proj_ — get it from Developer → Projects in your dashboard.

Check Payment Status

const tx = await client.getPaymentStatus("ORDER-001");

console.log(tx.status);    // "pending" | "completed" | "failed"
console.log(tx.netAmount); // Amount after commission deduction

Get Account Balance

const balance = await client.getBalance();

console.log(balance.balanceHtg);      // Total available
console.log(balance.withdrawableHtg); // Can withdraw now

Webhooks

Configure a webhook URL in your project. MonCashConnect sends a signed POST when a payment is finalized.

Always read the raw request body before any JSON.parse().

import { constructEvent, MonCashError } from "@moncashconnect/sdk";

// Express — use express.raw() to get the Buffer before JSON parsing
app.post("/webhooks/moncash", express.raw({ type: "application/json" }), (req, res) => {
  const signature = req.headers["x-mcc-signature"] as string ?? "";
  const timestamp = req.headers["x-mcc-timestamp"] as string ?? "";

  let event;
  try {
    event = constructEvent(req.body, signature, timestamp, process.env.MCC_WEBHOOK_SECRET!);
  } catch (err) {
    if (err instanceof MonCashError) return res.status(err.statusCode).send(err.message);
    return res.status(400).send("Bad request");
  }

  switch (event.event) {
    case "payment.completed":
      await markOrderAsPaid(event.reference);
      break;
    case "payment.failed":
      await markOrderAsFailed(event.reference);
      break;
  }

  res.sendStatus(200); // Always respond 2xx
});

Next.js App Router

// app/api/webhooks/moncash/route.ts
import { constructEvent, MonCashError } from "@moncashconnect/sdk";
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const rawBody  = await req.text();
  const signature = req.headers.get("x-mcc-signature") ?? "";
  const timestamp = req.headers.get("x-mcc-timestamp") ?? "";

  let event;
  try {
    event = constructEvent(rawBody, signature, timestamp, process.env.MCC_WEBHOOK_SECRET!);
  } catch (err) {
    const code = err instanceof MonCashError ? err.statusCode : 400;
    return NextResponse.json({ error: (err as Error).message }, { status: code });
  }

  if (event.event === "payment.completed") {
    // Update DB here
  }

  return NextResponse.json({ ok: true });
}

Error Handling

import { MonCashClient, MonCashError } from "@moncashconnect/sdk";

try {
  const payment = await client.createPayment(500, "ORDER-42");
} catch (err) {
  if (err instanceof MonCashError) {
    console.error(err.message);    // Human-readable error
    console.error(err.statusCode); // HTTP status (400, 401, 409, 429, 502…)
    console.error(err.context);    // Full API response body
  }
}

TypeScript

All types are exported:

import type {
  Payment, TransactionStatus, Balance,
  CreatePaymentOptions, WebhookEvent, ClientOptions
} from "@moncashconnect/sdk";

License

MIT