JavaScript / Node.js SDK

The official Cashless SDK for JavaScript and Node.js. Published on npm as @cashless/sdk.

Installation

npm install @cashless/sdk

Quick start

import { cashless } from '@cashless/sdk';

// Initialize (use .sandbox() for testing)
const api = cashless.api.live('YOUR_KEY', 'YOUR_SECRET');

// Create a bill
const bill = await api.issue(
  new cashless.BillParams('0712345678', 5000, 'ORDER-001')
);
console.log(bill.webPayUrl);

// Check payment status
const updated = await api.get(bill.id);
console.log(updated.status.name); // "FULLY_PAID", "PARTIALLY_PAID", or "NOT_PAID"

API

cashless.api.live(key, secret)

Creates a billing API client for the production environment (api.cashless.co.tz).

cashless.api.sandbox(key, secret)

Creates a billing API client for the sandbox environment (api-sandbox.cashless.co.tz).

api.issue(params): Promise<BillDto>

Creates a new bill.

Parameters:

• params -- A cashless.BillParams instance

Returns: Promise<BillDto>

api.get(id): Promise<BillDto>

Retrieves a bill by its UUID.

Parameters:

• id -- Bill UUID string

Returns: Promise<BillDto>

new cashless.BillParams(mobile, amount, reference)

Creates bill parameters.

Parameter	Type	Description
mobile	string | null	Customer phone number (pass null to skip USSD push)
amount	number	Amount in TZS
reference	string	Your unique transaction reference

cashless.BillDto

Property	Type	Description
.id	string	Bill UUID
.mobile	string	Customer phone
.amount	number	Bill amount
.status	Status	Payment status enum
.reference	string	Your reference
.webPayUrl	string	Web payment page URL
.date	number	Creation timestamp

cashless.BillDto.Status

Value	Meaning
FULLY_PAID	Full payment received
PARTIALLY_PAID	Partial payment received
NOT_PAID	No payment yet

TypeScript

The SDK includes TypeScript definitions. Types are available under the cashless namespace:

import { cashless } from '@cashless/sdk';

const api: cashless.BillingAPI = cashless.api.live(key, secret);
const bill: cashless.BillDto = await api.issue(params);

Example: Express.js integration

import express from 'express';
import { cashless } from '@cashless/sdk';

const app = express();
const api = cashless.api.live(process.env.CASHLESS_KEY, process.env.CASHLESS_SECRET);

app.post('/checkout', async (req, res) => {
  const { mobile, amount, orderId } = req.body;

  const bill = await api.issue(
    new cashless.BillParams(mobile || null, amount, orderId)
  );

  // Redirect to payment page, or return bill info
  res.json({
    paymentUrl: bill.webPayUrl,
    billId: bill.id,
  });
});

app.get('/payment-status/:billId', async (req, res) => {
  const bill = await api.get(req.params.billId);
  res.json({ status: bill.status.name });
});