Quickstart

Create your first bill and accept a payment in under 5 minutes.

Prerequisites

• A Cashless merchant account with API credentials (key and secret)
• For testing, use the sandbox environment

Step 1: Create a bill

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": 5000,
    "reference": "ORDER-001",
    "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', 5000, 'ORDER-001')
);

console.log(bill.id);        // Bill UUID
console.log(bill.webPayUrl); // Payment page URL

Node.js (fetch)

const response = await fetch('https://api.cashless.co.tz/api/v3/bills/create', {
  method: 'POST',
  headers: {
    'Authorization': 'ApiKey YOUR_KEY:YOUR_SECRET',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    amount: 5000,
    reference: 'ORDER-001',
    mobile: '0712345678',
  }),
});

const bill = await response.json();
console.log(bill.webPayUrl);

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': 5000,
        'reference': 'ORDER-001',
        'mobile': '0712345678',
    }
)

bill = response.json()
print(bill['webPayUrl'])

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' => 5000,
        'reference' => 'ORDER-001',
        'mobile' => '0712345678',
    ]),
]);

$response = curl_exec($ch);
$bill = json_decode($response, true);
echo $bill['webPayUrl'];

Response:

{
  "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
}

If you provided a mobile number, the customer will receive a USSD push on their phone prompting them to confirm the payment. You can also redirect the customer to the webPayUrl for a web-based payment experience.

Step 2: Check payment status

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');
console.log(bill.status); // FULLY_PAID, PARTIALLY_PAID, or NOT_PAID

Node.js (fetch)

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

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()
print(bill['status'])  # FULLY_PAID, PARTIALLY_PAID, or NOT_PAID

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);
echo $bill['status'];

Step 3: Handle the result

When status is FULLY_PAID, the payment is complete. Fulfill the order.

For production, consider:

• Polling with backoff for checking status
• Webhooks for real-time notifications
• WebPay integration for web-based payment flows