Collection API
Send a payment request and receive money from mobile money.
Authentication
Every request requires your API key in the headers.
Required Headers
Authorization
Bearer sk_live_XXXXXXXXXXXX
Content-Type
application/json
Overview
Collect payments from M-Pesa, Mixx By Yas, Airtel Money and Halopesa. Send POST /collections/ussd-push with phone + amount; the response returns orderid, phone, amount, status (pending) and created. Then track the status via /transactions/{orderid} or a webhook.
- Step 1 — USSD Push (Payment Request) — Send POST /collections/ussd-push with phone + amount; the customer receives a USSD push to enter their PIN and the status is pending.
- Step 2 — Status — Check the status with GET /transactions/{orderid} until it becomes success or failed.
- Step 3 — Webhook — Or wait for SpeedPesa Pro to send the event to your webhook URL.
Step 1 — Send Payment Request (USSD PUSH)
This endpoint immediately sends a payment request to the customer. The customer receives a USSD-PUSH on their phone and enters their wallet PIN. The response returns a stable SpeedPesa Pro orderid for status checks, the provider_order_id, phone, amount, status (pending) and created.
Use www.speedpesapro.com specifically (without www the request is redirected and some HTTP clients drop the POST body — which causes a server error).
Request Body (JSON)
| Parameter | Type | Required | Description |
|---|---|---|---|
| phone | string | Yes | Customer's phone number (M-Pesa, Mixx By Yas, Airtel Money, Halopesa).example: 0712345678 |
| amount | integer | Yes | Amount to collect in TZS.example: 1000 |
| reference | string | No | A unique reference for the order in your system.example: ORD-1001 |
curl -X POST 'https://www.speedpesapro.com/api/public/v1/collections/ussd-push' \
-H 'Authorization: Bearer sk_live_XXXXXXXXXXXX' \
-H 'Content-Type: application/json' \
-d '{
"phone": "0712345678",
"amount": 1000
}'Note: Save orderid (the same value as transaction_id). Always use it at /transactions/{orderid}; do not use provider_order_id for your integration. The initial status is pending until payment is confirmed.
Step 3 — Check Payment Status
Check the payment status using the transaction_id or your order reference. If the transaction is still pending, the system confirms directly with the provider before returning a response.
Use www.speedpesapro.com specifically (without www the request is redirected and some HTTP clients drop the POST body — which causes a server error).
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| transaction_id | string | Yes | The identifier you received in step 2 (or your reference).example: STB-8FA21-3D91C |
curl -X GET 'https://www.speedpesapro.com/api/public/v1/transactions/STB-8FA21-3D91C' \
-H 'Authorization: Bearer sk_live_XXXXXXXXXXXX'Note: Possible statuses are pending, success and failed.
Transaction Statuses
pending
The push has reached the customer; the PIN has not been entered yet.
Action: Wait for the webhook or poll /transactions/{id} every 5–10 seconds (up to 3 minutes).
success
Payment is complete and the balance has been credited.
Action: Fulfil your order immediately; this event cannot be reversed.
failed
The customer cancelled, entered the wrong PIN, or had insufficient balance.
Action: Ask the customer to try again with a new reference.