📚 API Documentation

🚀 Getting Started

Welcome to the Payment Gateway API. This documentation will help you integrate mobile money payments into your website or application.

Prerequisites

• Valid API Key from admin panel
• Customer phone number (Tanzania format: 255XXXXXXXXX)
• Product ID (created in admin panel)

🔑 Authentication

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

📍 API Endpoints

💳 Create Payment

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

Request Parameters

Example Request

fetch('https://dukuzii.com/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."
}

📊 Check Transaction Status

Check the status of a payment transaction.

Example Request

fetch('https://dukuzii.com/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

We'll send real-time updates to your webhook URL when payment status changes.

Webhook Payload

{
    "transaction_id": 123,
    "status": "completed",
    "amount": 5000,
    "customer_phone": "255712345678",
    "completed_at": "2026-04-07 10:32:00"
}

⚠️ Error Codes

Example Error Response

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

💻 Code Examples

// Complete JavaScript example
async function initiatePayment() {
    const response = await fetch('https://dukuzii.com/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://dukuzii.com/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://dukuzii.com/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://dukuzii.com/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://dukuzii.com/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"
  }'

❓ Frequently Asked Questions

What payment methods are supported?

We support all major mobile money networks in Tanzania: M-Pesa, Airtel Money, Tigo Pesa, and 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.

How do I test the integration?

Use your own phone number for testing. Minimum amount is TZS 100.

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.