STK Push (C2B)
Initiate M-Pesa STK Push requests to collect payments from customers. The customer receives a prompt on their phone to enter their M-Pesa PIN.
/v3/stk-initiate/
POST
/v3/stk-initiate/
Auth Required
Service: stk_push
Initiate STK Push
Send an STK Push request to a customer's phone. Payment is routed to your configured payment channel.
Headers
| Header | Value |
|---|---|
Authorization |
Bearer YOUR_API_KEY |
Content-Type |
application/json |
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
amount |
integer | Yes | Amount in KES (minimum 1) |
phone_number |
string | Yes | Customer phone (254XXXXXXXXX or 07XXXXXXXX) |
external_reference |
string | No | Your unique reference (auto-generated if omitted) |
customer_name |
string | No | Customer name for records |
channel_id |
integer | No | Specific payment channel ID (uses default if omitted) |
account_number |
string | No | Paybill only: override the channel default account (max 20 chars, letters/numbers/hyphen/period). Omit to use the saved default. Rejected for bank, till, and wallet channels. |
callback_url |
string | No | URL to receive payment status callback |
Example Response
JSON
{
"success": true,
"status": "INITIATED",
"message": "STK Push sent successfully. Please check your phone.",
"reference": "INV-12345",
"transaction_id": 789,
"checkout_request_id": "ws_CO_12345...",
"merchant_request_id": "12345-67890",
"channel_type": "paybill",
"routing_info": {
"party_b": "174379",
"transaction_type": "CustomerPayBillOnline",
"description": "Paybill 174379, Account: ACC001"
}
}cURL Example
bash
curl -X POST 'https://swiftwallet.co.ke/v3/stk-initiate/' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"amount": 100,
"phone_number": "254712345678",
"external_reference": "INV-12345",
"account_number": "INV-991",
"customer_name": "John Doe",
"callback_url": "https://yoursite.com/callback"
}'Callback Payload
After the customer completes (or cancels) the payment, SwiftWallet sends a POST request to your callback_url with an enhanced payload.
POST to your callback_url
{
"success": true,
"transaction_id": 789,
"external_reference": "INV-12345",
"checkout_request_id": "ws_CO_12345...",
"merchant_request_id": "12345-67890",
"status": "completed",
"timestamp": "2024-12-31T12:30:05+03:00",
"service_fee": 5,
"result": {
"ResultCode": 0,
"ResultDesc": "Success",
"Amount": 100,
"MpesaReceiptNumber": "ABC123XYZ",
"Phone": "254712345678",
"TransactionDate": "20241231123000"
},
"channel_info": {
"channel_type": "paybill",
"channel_name": "Main Paybill",
"routing_description": "Paybill 174379, Account: ACC001"
}
}Verify callbacks by checking the transaction_id against your records via the Transactions API.