API Reference

The Cashless API is a RESTful API for creating and managing payment bills. All requests and responses use JSON.

Base URLs

Environment	URL
Production	https://api.cashless.co.tz
Sandbox	https://api-sandbox.cashless.co.tz

Authentication

All requests require the Authorization header:

Authorization: ApiKey YOUR_KEY:YOUR_SECRET

See Authentication for details.

Endpoints

Method	Path	Description
POST	/api/v3/bills/create	Create a bill
GET	/api/v3/bills/\{id\}	Get bill status

Request format

Send JSON in the request body with Content-Type: application/json:

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

Response format

Responses are JSON. A successful bill creation returns:

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

Error responses

Errors return a JSON object with an error field:

{
  "error": "Invalid api key or api secret"
}

Common error scenarios:

Scenario	Error message
Invalid credentials	Invalid api key or api secret
Missing required field	amount is required
Bill not found	Bill with id \{id\} not found
Merchant not found	Merchant profile not found