ClickPesaMobile Money IntegrationTanzania PaymentsPHP APIFintechPayment GatewayUSSD PushWebhooksAPI SecurityHMAC SHA256
Complete Guide to ClickPesa Mobile Money Integration in PHP - USSD PUSH (Step-by-Step for Beginners)
Learn how to integrate ClickPesa mobile money payments into your website using PHP. This step-by-step guide covers authentication, checksum security, USSD push requests, and webhook handling for real-time payment updates.
Integrating mobile payment systems into your website is essential for modern businesses, especially in Tanzania where mobile money dominates digital transactions. In this complete guide, you’ll learn how to integrate ClickPesa into your PHP application step-by-step—from account setup to handling real-time payment confirmations.
🚀 Step 1: Account Setup & Credentials
Start by registering for a ClickPesa account and understanding the difference between Sandbox (testing) and Live (production) environments.
To activate payment features like Mix by Yas, you must complete the KYC (Know Your Customer) process by uploading your business documents.
Once verified, navigate to the Developer section to obtain:
Client ID
API Key
Checksum Key (very important for security)
🔐 Step 2: Authentication (Bearer Tokens)
ClickPesa uses short-lived Bearer Tokens to secure API communication.
You’ll need to send your Client ID and API Key to the /generate-token endpoint using PHP and cURL.
⚠️ Best Practice: Always generate a new token for each transaction to maintain security.
🛡️ Step 3: Security & Checksums (Fixing “Invalid Checksum”)
To ensure data integrity, ClickPesa requires a Checksum to prevent tampering.
Here’s how it works:
Arrange your request data (Amount, Phone, Reference) alphabetically
Convert the data into a clean JSON string
Sign it using HMAC-SHA256 with your Checksum Key
This step is critical—most integration errors happen here.
📲 Step 4: Initiating the USSD Push
Prepare your payment request payload with:
Amount (in TZS)
Phone number (format: 255XXXXXXXXX)
Unique Order Reference
Send this data along with the checksum to the /initiate-ussd-push-request endpoint.
Once successful, prompt the user:
👉 “Please check your phone and enter your PIN to complete payment.”
🔄 Step 5: Webhooks (Automatic Payment Updates)
To automate payment confirmation:
Create a callback.php file on your server
Configure it as your webhook URL in ClickPesa dashboard
Listen for payment status updates
When a payment is successful, automatically update your database (e.g., change booking status from Pending → Paid).
🎨 Step 6: User Interface (UI) Design
A good user experience is key:
Create a simple mobile-friendly form for phone number and amount
Use JavaScript to show a “Processing…” loader while waiting for user confirmation
Keep the interface clean and intuitive
💡 Pro Tip
ClickPesa allows you to configure the Fee Bearer setting in your dashboard.
You can choose whether:
The Customer pays transaction fees, or
The Merchant covers the fees
Choose wisely based on your business model.
✅ Final Thoughts
By following this guide, you’ll be able to build a secure and efficient mobile payment system using ClickPesa. This integration is perfect for e-commerce platforms, booking systems, and service-based applications in Tanzania.
🚀 Step 1: Account Setup & Credentials
Start by registering for a ClickPesa account and understanding the difference between Sandbox (testing) and Live (production) environments.
To activate payment features like Mix by Yas, you must complete the KYC (Know Your Customer) process by uploading your business documents.
Once verified, navigate to the Developer section to obtain:
Client ID
API Key
Checksum Key (very important for security)
🔐 Step 2: Authentication (Bearer Tokens)
ClickPesa uses short-lived Bearer Tokens to secure API communication.
You’ll need to send your Client ID and API Key to the /generate-token endpoint using PHP and cURL.
⚠️ Best Practice: Always generate a new token for each transaction to maintain security.
🛡️ Step 3: Security & Checksums (Fixing “Invalid Checksum”)
To ensure data integrity, ClickPesa requires a Checksum to prevent tampering.
Here’s how it works:
Arrange your request data (Amount, Phone, Reference) alphabetically
Convert the data into a clean JSON string
Sign it using HMAC-SHA256 with your Checksum Key
This step is critical—most integration errors happen here.
📲 Step 4: Initiating the USSD Push
Prepare your payment request payload with:
Amount (in TZS)
Phone number (format: 255XXXXXXXXX)
Unique Order Reference
Send this data along with the checksum to the /initiate-ussd-push-request endpoint.
Once successful, prompt the user:
👉 “Please check your phone and enter your PIN to complete payment.”
🔄 Step 5: Webhooks (Automatic Payment Updates)
To automate payment confirmation:
Create a callback.php file on your server
Configure it as your webhook URL in ClickPesa dashboard
Listen for payment status updates
When a payment is successful, automatically update your database (e.g., change booking status from Pending → Paid).
🎨 Step 6: User Interface (UI) Design
A good user experience is key:
Create a simple mobile-friendly form for phone number and amount
Use JavaScript to show a “Processing…” loader while waiting for user confirmation
Keep the interface clean and intuitive
💡 Pro Tip
ClickPesa allows you to configure the Fee Bearer setting in your dashboard.
You can choose whether:
The Customer pays transaction fees, or
The Merchant covers the fees
Choose wisely based on your business model.
✅ Final Thoughts
By following this guide, you’ll be able to build a secure and efficient mobile payment system using ClickPesa. This integration is perfect for e-commerce platforms, booking systems, and service-based applications in Tanzania.