Muongozo wa API

Kuanza

API hii inakuwezesha kuanzisha malipo ya simu na kufuatilia muamala. Tumia X-API-Key ya site yako kwa kila ombi.

Prerequisites

• Valid API Key from admin panel
• Customer phone number (Tanzania format: 255XXXXXXXXX)
• Ebook product ID (with PDF uploaded in admin)

Uthibitishaji

All API requests require an API key. Include it in the request headers:

X-API-Key: your_api_key_here

Getting Your API Key

1. Login to Admin Panel
2. Navigate to "All Sites" section
3. Copy the API key for your site
4. Keep it secure! Don't share it publicly

Endpoints

Tengeneza malipo

Initiate a mobile money payment. Customer will receive a USSD push on their phone.

Request Parameters

Example Request

fetch('https://sai.co.tz/api-proxy.php/create-payment', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'X-API-Key': 'your_api_key_here'
    },
    body: JSON.stringify({
        phone_number: '255712345678',
        amount: 5000,
        product_id: 1,
        customer_name: 'John Doe',
        customer_email: 'john@example.com'
    })
})
.then(res => res.json())
.then(data => {
    if(data.success) {
        console.log('Transaction ID:', data.transaction_id);
        alert('Payment initiated! Check your phone.');
    }
});

Response

{
    "success": true,
    "transaction_id": 123,
    "status": "pending",
    "message": "Payment initiated. Customer will receive USSD push."
}

Hali ya muamala

Check the status of a payment transaction.

Example Request

fetch('https://sai.co.tz/api-proxy.php/transaction/123', {
    method: 'GET',
    headers: {
        'X-API-Key': 'your_api_key_here'
    }
})
.then(res => res.json())
.then(data => {
    console.log('Status:', data.status);
    if(data.status === 'completed') {
        // Fulfill order
    }
});

Response

{
    "transaction_id": 123,
    "status": "completed",
    "amount": 5000,
    "currency": "TZS",
    "created_at": "2026-04-07 10:30:00",
    "completed_at": "2026-04-07 10:32:00"
}

Status Values

Webhooks

Mtoa huduma wa malipo hutuma matukio kwenye https://sai.co.tz/webhook.php (tunaweka URL hii kiotomatiki wakati wa malipo). Server yako inasasisha hali ya muamala na lazima irudishe HTTP 200.

Envelope example (simplified)

{
    "type": "payment.completed",
    "data": {
        "reference": "pi_...",
        "status": "completed",
        "metadata": { "gateway_transaction_id": "..." }
    }
}

Makosa ya kawaida

Example Error Response

{
    "error": "Invalid or missing API key"
}

Mifano ya msimbo

// Complete JavaScript example
async function initiatePayment() {
    const response = await fetch('https://sai.co.tz/api-proxy.php/create-payment', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
            'X-API-Key': 'your_api_key_here'
        },
        body: JSON.stringify({
            phone_number: document.getElementById('phone').value,
            amount: document.getElementById('amount').value,
            product_id: 1,
            customer_name: document.getElementById('name').value,
            customer_email: document.getElementById('email').value
        })
    });
    
    const data = await response.json();
    
    if (data.success) {
        // Poll for status
        checkStatus(data.transaction_id);
    }
}

async function checkStatus(transactionId) {
    const interval = setInterval(async () => {
        const response = await fetch(`https://sai.co.tz/api-proxy.php/transaction/${transactionId}`, {
            headers: { 'X-API-Key': 'your_api_key_here' }
        });
        const data = await response.json();
        
        if (data.status === 'completed') {
            clearInterval(interval);
            alert('Payment successful!');
            // Redirect or update UI
        } else if (data.status === 'failed') {
            clearInterval(interval);
            alert('Payment failed. Please try again.');
        }
    }, 5000); // Check every 5 seconds
}

<?php
// PHP example
$ch = curl_init('https://sai.co.tz/api-proxy.php/create-payment');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'X-API-Key: your_api_key_here'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'phone_number' => '255712345678',
    'amount' => 5000,
    'product_id' => 1,
    'customer_name' => 'John Doe',
    'customer_email' => 'john@example.com'
]));

$response = curl_exec($ch);
$data = json_decode($response, true);

if ($data['success']) {
    echo "Transaction ID: " . $data['transaction_id'];
}
?>

# Python example
import requests

url = 'https://sai.co.tz/api-proxy.php/create-payment'
headers = {
    'Content-Type': 'application/json',
    'X-API-Key': 'your_api_key_here'
}
data = {
    'phone_number': '255712345678',
    'amount': 5000,
    'product_id': 1,
    'customer_name': 'John Doe',
    'customer_email': 'john@example.com'
}

response = requests.post(url, json=data, headers=headers)
result = response.json()

if result['success']:
    print(f"Transaction ID: {result['transaction_id']}")

# cURL example
curl -X POST https://sai.co.tz/api-proxy.php/create-payment \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{
    "phone_number": "255712345678",
    "amount": 5000,
    "product_id": 1,
    "customer_name": "John Doe",
    "customer_email": "john@example.com"
  }'

Maswali ya mara kwa mara

Ni njia zipi za malipo zinazotumika?

Malipo ya simu nchini Tanzania: M-Pesa, Airtel Money, Mixx by Yas, na Halotel.

How long does a payment take?

Payments are typically completed within 30 seconds to 2 minutes after customer authorizes the USSD push.

What happens if payment fails?

The transaction status will be marked as 'failed'. Customer can retry the payment.

Ninawezaje kujaribu muunganisho?

Tumia nambari yako ya simu kwa majaribio. Kiwango cha chini kwa TZS ni 500.

Is there a refund option?

Contact admin for refund requests. Refunds are processed manually.

How are webhooks delivered?

Webhooks are sent to the URL configured in your site settings. Retry logic is implemented for failed deliveries.