SDKs & Libraries Overview

Cashfin provides official and community SDKs to help you integrate faster.

Official SDKs

Language	Status	Package
JavaScript/TypeScript	🟡 Coming Soon	@cashfin/node
PHP	🟡 Coming Soon	cashfin/cashfin-php
Python	🟡 Coming Soon	cashfin

Quick Installation

npm

npm install @cashfin/node

yarn

yarn add @cashfin/node

pnpm

pnpm add @cashfin/node

Composer

composer require cashfin/cashfin-php

pip

pip install cashfin  # Coming soon

Quick Start

JavaScript

import Cashfin from "@cashfin/node";

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

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

// Create a product
const product = await cashfin.products.create({
  title: "Premium Widget",
  price: 1999.99,
  stock: 100,
});

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

PHP

<?php
require 'vendor/autoload.php';

use Cashfin\CashfinClient;

$cashfin = new CashfinClient([
    'api_key' => getenv('CASHFIN_API_KEY')
]);

// List products
$products = $cashfin->products->all();

// Create a product
$product = $cashfin->products->create([
    'title' => 'Premium Widget',
    'price' => 1999.99,
    'stock' => 100
]);

// Create M-Pesa payment
$payment = $cashfin->payments->mpesa([
    'amount' => 1000,
    'phone' => '254712345678',
    'reference' => 'ORDER-001'
]);

Python

import cashfin
import os

client = cashfin.Client(api_key=os.environ.get('CASHFIN_API_KEY'))

# List products
products = client.products.list()

# Create a product
product = client.products.create(
    title='Premium Widget',
    price=1999.99,
    stock=100
)

# Create M-Pesa payment
payment = client.payments.mpesa(
    amount=1000,
    phone='254712345678',
    reference='ORDER-001'
)

SDK Features

All SDKs include:

• ✅ Full API Coverage - Access all Cashfin Business API endpoints
• ✅ Type Safety - TypeScript types, PHP docblocks, Python type hints
• ✅ Automatic Retries - Built-in retry logic with exponential backoff
• ✅ Error Handling - Structured error classes for easy handling
• ✅ Pagination Helpers - Easy iteration over paginated results
• ✅ Webhook Verification - Verify webhook signatures

Error Handling

JavaScript

import Cashfin, {
  CashfinError,
  ValidationError,
  AuthenticationError,
} from "@cashfin/node";

try {
  const product = await cashfin.products.create({
    title: "Widget",
    // Missing price
  });
} 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 CashfinError) {
    console.log("API error:", error.message);
  }
}

PHP

<?php
use Cashfin\Exception\ValidationException;
use Cashfin\Exception\AuthenticationException;
use Cashfin\Exception\CashfinException;

try {
    $product = $cashfin->products->create([
        'title' => 'Widget'
        // Missing price
    ]);
} catch (ValidationException $e) {
    echo 'Validation failed: ' . json_encode($e->getErrors());
} catch (AuthenticationException $e) {
    echo 'Invalid API key';
} catch (CashfinException $e) {
    echo 'API error: ' . $e->getMessage();
}

Webhook Handling

JavaScript

import { verifyWebhookSignature } from "@cashfin/node";

app.post("/webhooks/cashfin", (req, res) => {
  const signature = req.headers["x-cashfin-signature"];
  const payload = req.rawBody;

  if (!verifyWebhookSignature(payload, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(401).json({ error: "Invalid signature" });
  }

  const event = JSON.parse(payload);
  // Handle event...

  res.json({ received: true });
});

PHP

<?php
use Cashfin\Webhook;

$signature = $_SERVER['HTTP_X_CASHFIN_SIGNATURE'];
$payload = file_get_contents('php://input');

try {
    $event = Webhook::constructEvent(
        $payload,
        $signature,
        getenv('WEBHOOK_SECRET')
    );

    // Handle event...

} catch (\UnexpectedValueException $e) {
    http_response_code(400);
    exit();
} catch (\Cashfin\Exception\SignatureVerificationException $e) {
    http_response_code(401);
    exit();
}

http_response_code(200);

Community Libraries

These libraries are maintained by the community:

Language	Library	Maintainer
Go	go-cashfin	Community
Ruby	cashfin-ruby	Community
Java	cashfin-java	Community

WARNING

Community libraries are not officially supported. Use at your own discretion.

Contributing

Want to contribute or create an SDK for another language?

1. Check our API Reference for endpoint details
2. Follow our SDK Guidelines
3. Submit your library for review

Getting Help

• 📚 API Documentation
• 💬 Discord Community
• 📧 Developer Support
• 🐛 Report SDK Issues