Create Bill

Create a new payment bill. If a mobile number is provided, a USSD push is automatically sent to the customer's phone.

POSThttps://api.cashless.co.tz/api/v3/bills/create

Request body

Field	Type	Required	Description
amount	number	Yes	Bill amount in local currency (TZS)
reference	string	Yes	Your unique reference for this transaction (e.g., order ID)
mobile	string	No	Customer's mobile number in national format (e.g., 0712345678). If provided, triggers a USSD push.

Response

Returns a BillDto object.

Field	Type	Description
id	string	Unique bill identifier (UUID)
mobile	string	Customer's mobile number
amount	number	Bill amount
status	string	Payment status: NOT_PAID, PARTIALLY_PAID, or FULLY_PAID
reference	string	Your reference from the request
webPayUrl	string	URL to the web payment page for this bill
date	number	Bill creation timestamp (Unix milliseconds)

Examples

cURL

curl -X POST https://api.cashless.co.tz/api/v3/bills/create \
  -H "Authorization: ApiKey YOUR_KEY:YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 15000,
    "reference": "INV-2024-0042",
    "mobile": "0712345678"
  }'

Node.js (SDK)

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

const api = cashless.api.live('YOUR_KEY', 'YOUR_SECRET');

const bill = await api.issue(
  new cashless.BillParams('0712345678', 15000, 'INV-2024-0042')
);

console.log(bill.id);         // "a1b2c3d4-..."
console.log(bill.webPayUrl);  // "https://webpay.cashless.co.tz?bill=..."
console.log(bill.status);     // NOT_PAID

Python

import requests

response = requests.post(
    'https://api.cashless.co.tz/api/v3/bills/create',
    headers={
        'Authorization': 'ApiKey YOUR_KEY:YOUR_SECRET',
        'Content-Type': 'application/json',
    },
    json={
        'amount': 15000,
        'reference': 'INV-2024-0042',
        'mobile': '0712345678',
    }
)
bill = response.json()

PHP

$ch = curl_init('https://api.cashless.co.tz/api/v3/bills/create');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: ApiKey YOUR_KEY:YOUR_SECRET',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'amount' => 15000,
        'reference' => 'INV-2024-0042',
        'mobile' => '0712345678',
    ]),
]);
$response = curl_exec($ch);
$bill = json_decode($response, true);

Response:

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

Without a mobile number

If you omit mobile, no USSD push is sent. Instead, redirect the customer to the webPayUrl where they can enter their mobile number and pay.

curl -X POST https://api.cashless.co.tz/api/v3/bills/create \
  -H "Authorization: ApiKey YOUR_KEY:YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"amount": 15000, "reference": "INV-2024-0042"}'