SDKs & Libraries Overview

Cashfin provides an official SDK for Node.js with full TypeScript support. PHP and Python SDKs are coming soon.

Official SDKs

Language	Status	Package	Version
JavaScript/TypeScript	Available	@cashfinbusiness/node	1.1.0
PHP	Coming Soon	cashfin/cashfin-php	—
Python	Coming Soon	cashfin-business	—

Installation

npm

npm install @cashfinbusiness/node

yarn

yarn add @cashfinbusiness/node

pnpm

pnpm add @cashfinbusiness/node

Quick Start

import Cashfin from "@cashfinbusiness/node";

const cashfin = new Cashfin({
  apiKey: process.env.CASHFIN_API_KEY!,
});

// List products
const products = await cashfin.products.list();

// Create a checkout order
const order = await cashfin.orders.checkout({
  customeremail: "[email protected]",
  items: [{ itemid: "product-id", quantity: 1, rate: 1999.99 }],
});
console.log(`Payment link: ${order.paymentlink.shorturl}`);

// Initiate M-Pesa payment
const payment = await cashfin.payments.mpesa({
  amount: 1000,
  phone: "254712345678",
  referenceid: "ORDER-001",
});

SDK Features

• Full API Coverage — Shop, Payments, CRM, Purchases, and Marketing
• TypeScript First — Complete type definitions for every method and response
• Automatic Retries — Built-in retry logic with exponential backoff
• Structured Error Handling — Typed error classes for every failure scenario
• Auto-Pagination — Async iterators for seamless pagination
• Webhook Verification — Verify webhook signatures with one call
• Zero Dependencies — Uses only Node.js built-in modules

Error Handling

import Cashfin, {
  CashfinError,
  ValidationError,
  AuthenticationError,
  NotFoundError,
  RateLimitError,
} from "@cashfinbusiness/node";

try {
  const product = await cashfin.products.create({ title: "Widget" });
} catch (error) {
  if (error instanceof ValidationError) {
    console.log("Validation failed:", error.errors);
  } else if (error instanceof AuthenticationError) {
    console.log("Invalid API key");
  } else if (error instanceof NotFoundError) {
    console.log("Resource not found");
  } else if (error instanceof RateLimitError) {
    console.log(`Retry after ${error.retryAfter} seconds`);
  } else if (error instanceof CashfinError) {
    console.log("API error:", error.message, error.statusCode);
  }
}

Webhook Handling

import { constructWebhookEvent } from "@cashfinbusiness/node";

app.post("/webhooks/cashfin", express.raw({ type: "application/json" }), (req, res) => {
  const signature = req.headers["x-cashfin-signature"] as string;
  const payload = req.body.toString();

  try {
    const event = constructWebhookEvent(payload, signature, process.env.WEBHOOK_SECRET!);

    switch (event.type) {
      case "payment.completed":
        console.log("Payment completed:", event.data);
        break;
      case "order.completed":
        console.log("Order completed:", event.data);
        break;
      case "invoice.paid":
        console.log("Invoice paid:", event.data);
        break;
    }

    res.json({ received: true });
  } catch {
    res.status(401).json({ error: "Invalid webhook" });
  }
});

Next Steps

• JavaScript/TypeScript SDK — Full SDK reference with examples for every resource
• API Reference — Explore the raw HTTP API

Getting Help

• API Documentation
• Developer Support
• Report SDK Issues