M-Pesa Integration

Accept automatic M-Pesa payments with STK push and instant subscriber activation.

Overview

Qserve integrates with Safaricom's Daraja API to handle M-Pesa payments. When a subscriber pays via M-Pesa (triggered by STK push or a self-service link), Qserve's callback receives the confirmation, matches it to the subscriber, and immediately activates or renews their package. No manual intervention needed.

Prerequisites

• A Safaricom M-Pesa business account (Pay Bill number or Till number)
• Access to Safaricom Daraja developer portal
• An approved Daraja API app (sandbox first, then production)

Step 1 — Create a Daraja App

1. Sign in to developer.safaricom.co.ke.
2. Click My Apps → Create New App.
3. Select all relevant APIs: Lipa Na M-Pesa Sandbox, M-Pesa Express.
4. Note your Consumer Key and Consumer Secret from the app details page.

Step 2 — Configure in Qserve

1. In Qserve, go to Settings → Payment Platforms.
2. Click Configure M-Pesa.
3. Enter:
   • Shortcode — Your Pay Bill or Till number (e.g., 174379 for sandbox)
   • Consumer Key — from your Daraja app
   • Consumer Secret — from your Daraja app
   • Passkey — The Lipa Na M-Pesa Online passkey (from Daraja → Go Live → API settings)
   • Environment — Sandbox for testing, Production for live payments
4. Save. Qserve will verify the credentials automatically.

Step 3 — Register Callback URLs in Daraja

In the Daraja portal, set the following callback URL for your app:

https://qserve-isp.net/api/mpesa/callback

For the STK push confirmation URL:

https://qserve-isp.net/api/mpesa/stk-push

Step 4 — Test with STK Push

1. Open any subscriber's profile in Qserve.
2. Click Request Payment.
3. Enter the subscriber's M-Pesa phone number and click Send STK Push.
4. The subscriber's phone will prompt them to enter their M-Pesa PIN.
5. After confirmation, Qserve receives the callback and renews the subscriber's package automatically.

Self-Service Payment Links

Each subscriber has a unique payment link they can bookmark. When they click it and pay, their account renews instantly. Share this link via SMS or WhatsApp when sending renewal reminders.

Troubleshooting

STK push not received

• Check that the phone number is in the correct format: 254XXXXXXXXX (no leading +).
• Verify that your Daraja credentials are correct and the environment matches (sandbox vs production).
• Ensure your M-Pesa shortcode is approved for STK push (check Daraja portal status).

Payment received but subscriber not activated

• Check Transactions to see if the payment was recorded with a matching subscriber.
• If the phone number on the M-Pesa payment differs from the subscriber's registered number, Qserve may not match it automatically. Manually link the transaction from the Transactions page.

"Invalid Access Token" error in logs

• Your Consumer Key or Secret is incorrect. Re-enter them in Settings.
• Confirm you are using Production credentials if in production (sandbox keys don't work in production mode).