Skip to main content

cURL Examples

Quick copy-paste cURL commands for testing the Cashless API.

Create a bill​

With mobile number (triggers USSD push)​

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

Without mobile number (web payment only)​

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

Sandbox​

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

Get bill status​

curl https://api.cashless.co.tz/api/v3/bills/BILL_ID_HERE \
  -H "Authorization: ApiKey YOUR_KEY:YOUR_SECRET"

Using environment variables​

# Set once
export CASHLESS_KEY="your_key"
export CASHLESS_SECRET="your_secret"
export CASHLESS_URL="https://api.cashless.co.tz"  # or api-sandbox.cashless.co.tz

# Create bill
curl -X POST ${CASHLESS_URL}/api/v3/bills/create \
  -H "Authorization: ApiKey ${CASHLESS_KEY}:${CASHLESS_SECRET}" \
  -H "Content-Type: application/json" \
  -d '{"amount": 5000, "reference": "ORDER-001", "mobile": "0712345678"}'

# Check status
curl ${CASHLESS_URL}/api/v3/bills/YOUR_BILL_ID \
  -H "Authorization: ApiKey ${CASHLESS_KEY}:${CASHLESS_SECRET}"

Poll for payment (bash script)​

#!/bin/bash
BILL_ID="$1"
while true; do
  STATUS=$(curl -s ${CASHLESS_URL}/api/v3/bills/${BILL_ID} \
    -H "Authorization: ApiKey ${CASHLESS_KEY}:${CASHLESS_SECRET}" | \
    python3 -c "import sys,json; print(json.load(sys.stdin)['status'])")

  echo "Status: $STATUS"

  if [ "$STATUS" = "FULLY_PAID" ]; then
    echo "Payment complete!"
    break
  fi

  sleep 5
done