Get Bill

Retrieve the current status and details of a bill.

GEThttps://api.cashless.co.tz/api/v3/bills/{id}

Path parameters

Parameter	Type	Description
id	string	The bill UUID returned from Create Bill

Response

Returns a BillDto object with the current payment status.

Examples

cURL

curl https://api.cashless.co.tz/api/v3/bills/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: ApiKey YOUR_KEY:YOUR_SECRET"

Node.js (SDK)

const bill = await api.get('a1b2c3d4-e5f6-7890-abcd-ef1234567890');

if (bill.status.name === 'FULLY_PAID') {
  console.log('Payment complete!');
}

Python

response = requests.get(
    'https://api.cashless.co.tz/api/v3/bills/a1b2c3d4-e5f6-7890-abcd-ef1234567890',
    headers={'Authorization': 'ApiKey YOUR_KEY:YOUR_SECRET'}
)
bill = response.json()

if bill['status'] == 'FULLY_PAID':
    print('Payment complete!')

PHP

$ch = curl_init('https://api.cashless.co.tz/api/v3/bills/a1b2c3d4-e5f6-7890-abcd-ef1234567890');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: ApiKey YOUR_KEY:YOUR_SECRET',
    ],
]);
$response = curl_exec($ch);
$bill = json_decode($response, true);

if ($bill['status'] === 'FULLY_PAID') {
    echo 'Payment complete!';
}

Response:

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

Polling for status

After creating a bill, poll this endpoint to check when payment is complete. See Polling vs Webhooks for best practices.

async function waitForPayment(api, billId, maxAttempts = 60) {
  for (let i = 0; i < maxAttempts; i++) {
    const bill = await api.get(billId);
    if (bill.status.name === 'FULLY_PAID') return bill;
    if (bill.status.name === 'PARTIALLY_PAID') {
      console.log('Partial payment received');
    }
    await new Promise(r => setTimeout(r, 5000)); // Wait 5 seconds
  }
  throw new Error('Payment timeout');
}