40% of churn in Kenya is involuntary — failed M-Pesa payments that customers never report. This integration helps you catch them automatically.
What You'll Need
- M-Pesa business account (Paybill or Till)
- API credentials from Safaricom Developer Portal
- Cuoral Pro or Enterprise plan
- ~10 minutes
Setup Steps
Get API Credentials
Go to Safaricom Developer Portal and create an app.
Copy your Consumer Key and Consumer Secret.
Connect in Cuoral
In Cuoral: Settings → Integrations → Payment Gateways → Connect M-Pesa
Configure Webhook
Copy your Cuoral webhook URL and paste it in Safaricom's Callback URL settings.
Important: Without the callback URL, M-Pesa won't notify Cuoral about payment events.
Map Customer Phone Numbers
Cuoral automatically matches payments if customer phone numbers are stored in your database. Format: 254XXXXXXXXX
Set Up Payment Alerts
Create an alert for failed payments:
"Hi [Name] ⚠️ Your M-Pesa payment for [Product] failed. Retry here: [link]"
What Cuoral Tracks
- Payment success/failure status
- Failure reasons (insufficient balance, timeout, etc.)
- Payment timing and patterns
- All data feeds into customer health scores
Troubleshooting
Payments not showing in Cuoral?
Check that callback URL is set correctly in Safaricom portal
Wrong customers matched?
Verify phone numbers match M-Pesa format (254XXXXXXXXX)