Payments
M-PESA
In a nutshell
M-PESA payment integration for businesses in Kenya, with STK push, offline Paybill, and M-PESA Till.
Paystack supports three M-PESA flows to accommodate different customer experiences. All M-PESA transactions use the mobile_money parameter with KES as the currency. We recommend that you include the country code in the phone number. For example, 0722000000 should be sent as +254722000000 to the Charge endpoint
Copy linkSTK Push
The most common flow where Paystack sends an STK (SIM Toolkit) push notification to the customer's phone. The customer enters their M-PESA PIN to approve the payment.
The response returns data.status as pay_offline. The display_text field describes the next step for the customer.
This is a commonly used in the following scenarios:
- E-commerce checkout - customer is ready to pay and can respond immediately
- In-app payments - real-time context, the app can show a "check your phone" prompt
- Event ticketing: time-sensitive purchases where instant confirmation matters
- Donations and fundraising pages: simple single-action flows
POSTapi.paystack.co/charge
curl https://api.paystack.co/charge \
-H "Authorization: Bearer YOUR_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"amount": 300,
"email": "[email protected]",
"currency": "KES",
"mobile_money": {
"phone": "254710000000",
"provider": "mpesa"
}
}'const response = await fetch('https://api.paystack.co/charge', {
method: 'POST',
headers: {
Authorization: 'Bearer YOUR_SECRET_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
amount: 300,
email: '[email protected]',
currency: 'KES',
mobile_money: {
phone: '254710000000',
provider: 'mpesa'
}
})
})
const data = await response.json()
console.log(data)Time limit
The customer must respond to the STK push within 180 seconds. After this window, verify the transaction using the Verify Transaction endpoint to determine the final outcome.
Copy linkOffline Payment
The offline option allows businesses to create a transaction that will be completed later. This is useful for businesses that offer payment after service delivery. The customer will pay to Paystack's Paybill and the generated account_reference will identify the transaction.
The biggest benefit to businesses is the transaction canβt be completed with the wrong amount. Itβll fail and the customer will have to start again.
This feature is commonly used in:
- Invoice generation
- Payment on delivery
- Customer-initiated payments at their own convenience
- Fallback when STK push is unavailable
POSTapi.paystack.co/charge
curl https://api.paystack.co/charge \
-H "Authorization: Bearer YOUR_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"amount": 10000,
"email": "[email protected]",
"currency": "KES",
"mobile_money": {
"provider": "mpesa_offline"
}
}'const response = await fetch('https://api.paystack.co/charge', {
method: 'POST',
headers: {
Authorization: 'Bearer YOUR_SECRET_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
amount: 10000,
email: '[email protected]',
currency: 'KES',
mobile_money: {
provider: 'mpesa_offline'
}
})
})
const data = await response.json()
console.log(data){
"status": true,
"message": "Charge attempted",
"data": {
"reference": "e6i9ak3rbq982wh",
"status": "pay_offline",
"display_text": "Please complete authorization process on your mobile phone",
"account_number": "4084333",
"account_reference": 1234567
}
}Transaction Verification
If the customer sends an incorrect amount, the transaction will fail automatically. A new charge must be created.
Copy linkM-PESA Till
You can also get paid by other businesses from their M-PESA Till numbers. The mobile_money object should have provider set to mptill and the account which is the other business's M-PESA Till number. They will receive a prompt on the phone assigned the till for authorization. This channel is best suited for large M-PESA based transactions.
POSTapi.paystack.co/charge
curl https://api.paystack.co/charge \
-H "Authorization: Bearer YOUR_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"amount": 1000,
"email": "[email protected]",
"currency": "KES",
"mobile_money": {
"provider": "mptill",
"account": 1234059
}
}'const response = await fetch('https://api.paystack.co/charge', {
method: 'POST',
headers: {
Authorization: 'Bearer YOUR_SECRET_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
amount: 1000,
email: '[email protected]',
currency: 'KES',
mobile_money: {
provider: 'mptill',
account: 1234059
}
})
})
const data = await response.json()
console.log(data)Copy linkWebhook confirmation
Paystack sends a charge.success webhook on successful authorization. Always wait for the charge.success webhook before fulfilling orders.
{
"event": "charge.success",
"data": {
"status": "success",
"reference": "your_reference",
"amount": 10000,
"currency": "KES",
"channel": "mobile_money"
}
}