Data Models

BillParams

The request body for creating a bill.

Field	Type	Required	Description
amount	number	Yes	Payment amount in local currency (TZS)
reference	string	Yes	Your unique identifier for this transaction
mobile	string	No	Customer's phone number in national format (e.g., 0712345678). When provided, triggers a USSD push to the customer's phone.

JSON example:

{
  "amount": 5000,
  "reference": "ORDER-001",
  "mobile": "0712345678"
}

Node.js SDK:

new cashless.BillParams('0712345678', 5000, 'ORDER-001')
// or without mobile:
new cashless.BillParams(null, 5000, 'ORDER-001')

BillDto

The response object returned when creating or retrieving a bill.

Field	Type	Description
id	string	Unique bill identifier (UUID). Use this to check payment status.
mobile	string	Customer's mobile number
amount	number	Bill amount
status	Status	Current payment status (see below)
reference	string	Your reference from the creation request
webPayUrl	string	URL to the hosted payment page. Redirect customers here or embed in your UI.
date	number	Bill creation timestamp in Unix milliseconds

JSON example:

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "mobile": "0712345678",
  "amount": 5000.0,
  "status": "NOT_PAID",
  "reference": "ORDER-001",
  "webPayUrl": "https://webpay.cashless.co.tz?bill=a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "date": 1708185600000
}

Status

The payment status of a bill.

Value	Description
NOT_PAID	No payment has been received
PARTIALLY_PAID	Some payment received, but less than the bill amount
FULLY_PAID	The full amount has been paid

In the Node.js SDK, status is accessed as an enum:

const bill = await api.get(billId);

// Access status name
bill.status.name  // "FULLY_PAID", "PARTIALLY_PAID", or "NOT_PAID"

// Compare with enum values
if (bill.status === cashless.BillDto.Status.FULLY_PAID) {
  // Payment complete
}