Speedpesa API v1
Webhook API
Pokea taarifa za matukio moja kwa moja kwenye server yako.
WEBHOOK · POST kwakoSpeedpesa inatuma POST kwenye server yako kila hali ya muamala inabadilika.
Authentication
Kila ombi linahitaji API key yako kwenye headers.
Required Headers
Authorization
Bearer sk_live_XXXXXXXXXXXX
Content-Type
application/json
Muhtasari
Badala ya kuuliza API kila mara, Speedpesa inatuma HTTP POST kwenye URL yako kila hali ya muamala inapobadilika. Sajili URL kwenye Dashboard → Settings → Developer.
PAYIN Webhook Event
Tukio hili linatumwa mteja anapokamilisha malipo (collection / USSD-PUSH).
json
{
"event": "payment.completed",
"sent_at": "2026-07-31T12:00:00+03:00",
"data": {
"transaction_id": "STB-8FA21-3D91C",
"reference": "ORD-1001",
"direction": "credit",
"amount": "5000.00",
"currency": "TZS",
"status": "success",
"channel": "Tigo Pesa",
"phone": "255712345678",
"completed_at": "2026-07-31T12:00:00+03:00"
}
}PAYOUT Webhook Event
Tukio hili linatumwa payout inapofanikiwa kwenda mobile money ya mpokeaji.
json
{
"event": "payout.completed",
"sent_at": "2026-07-31T14:30:00+03:00",
"data": {
"transaction_id": "WDR-7C31A9",
"reference": "PAY-2001",
"direction": "debit",
"amount": "10000.00",
"fee": "660.00",
"currency": "TZS",
"status": "success",
"channel": "Vodacom Tanzania",
"phone": "255712345678",
"completed_at": "2026-07-31T14:30:00+03:00"
}
}FAILED Webhook Event
Muamala ukishindikana (PIN si sahihi, mteja alighairi au salio halitoshi).
json
{
"event": "payment.failed",
"sent_at": "2026-07-31T12:02:10+03:00",
"data": {
"transaction_id": "STB-8FA21-3D91C",
"reference": "ORD-1001",
"status": "failed",
"message": "Mteja alighairi muamala."
}
}Kuthibitisha Saini
Kila ombi hubeba header X-Speedpesa-Signature yenye HMAC SHA-256 ya mwili wa ombi ukitumia webhook secret yako. Linganisha kabla ya kuchakata.
php
$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_SPEEDPESA_SIGNATURE'] ?? '';
$expected = hash_hmac('sha256', $payload, getenv('SPEEDPESA_WEBHOOK_SECRET'));
if (!hash_equals($expected, $signature)) {
http_response_code(401);
exit('Invalid signature');
}
http_response_code(200);
echo 'ok';