Skip to main content

Python

There is no official Python SDK yet. Use the requests library to interact with the Cashless API directly.

Installation​

pip install requests

Create a bill​

import requests

API_KEY = 'YOUR_KEY'
API_SECRET = 'YOUR_SECRET'
BASE_URL = 'https://api.cashless.co.tz'  # or https://api-sandbox.cashless.co.tz

def create_bill(amount, reference, mobile=None):
    payload = {
        'amount': amount,
        'reference': reference,
    }
    if mobile:
        payload['mobile'] = mobile

    response = requests.post(
        f'{BASE_URL}/api/v3/bills/create',
        headers={
            'Authorization': f'ApiKey {API_KEY}:{API_SECRET}',
            'Content-Type': 'application/json',
        },
        json=payload,
    )
    response.raise_for_status()
    return response.json()

bill = create_bill(5000, 'ORDER-001', '0712345678')
print(f"Payment URL: {bill['webPayUrl']}")

Check payment status​

def get_bill(bill_id):
    response = requests.get(
        f'{BASE_URL}/api/v3/bills/{bill_id}',
        headers={
            'Authorization': f'ApiKey {API_KEY}:{API_SECRET}',
        },
    )
    response.raise_for_status()
    return response.json()

bill = get_bill('a1b2c3d4-e5f6-7890-abcd-ef1234567890')
print(f"Status: {bill['status']}")  # FULLY_PAID, PARTIALLY_PAID, or NOT_PAID

Poll for payment​

import time

def wait_for_payment(bill_id, timeout=300, interval=5):
    """Poll until payment is complete or timeout is reached."""
    elapsed = 0
    while elapsed < timeout:
        bill = get_bill(bill_id)
        if bill['status'] == 'FULLY_PAID':
            return bill
        time.sleep(interval)
        elapsed += interval
    raise TimeoutError(f'Payment not completed within {timeout}s')

Django example​

# views.py
from django.http import JsonResponse
from django.views.decorators.http import require_POST
import json

@require_POST
def checkout(request):
    data = json.loads(request.body)
    bill = create_bill(
        amount=data['amount'],
        reference=data['order_id'],
        mobile=data.get('mobile'),
    )
    return JsonResponse({
        'payment_url': bill['webPayUrl'],
        'bill_id': bill['id'],
    })

def payment_status(request, bill_id):
    bill = get_bill(bill_id)
    return JsonResponse({'status': bill['status']})