Troubleshooting

This page covers common problems encountered when using Frappe Mpesa Payments and the steps to resolve them.

Authentication Issues

Symptom: API calls fail with an authentication error. The system may display a message like "Invalid Access Token" or "Access Token expired."

Cause: The Consumer Key or Consumer Secret in Mpesa Settings is incorrect, or the stored token has become invalid.

Resolution:

Open the relevant Mpesa Settings record.
Verify the Consumer Key and Consumer Secret match what is shown in your Daraja application.
Save the record. The app will generate a new token on the next API call.
If the problem persists, check that your Daraja application is active and the API type matches the credentials entered.

Symptom: B2C disbursements or Transaction Status queries fail with an "Initiator Information Invalid" error.

Cause: The Initiator Name or Initiator Password does not match the API Operator configured in the M-Pesa Org Portal.

Resolution:

Log in to the M-Pesa Org Portal.
Verify the API Operator's username and confirm the password is correct.
Update the Initiator Name and Initiator Password in Mpesa Settings.
Ensure the Mpesa Public Key Certificate for the correct environment (sandbox or production) is saved in the Mpesa Public Key Certificate DocType.

Symptom: Customers are paying via M-Pesa but no records appear in the Mpesa C2B Payment Register.

Causes and Resolutions:

Cause	Resolution
URLs are not registered	Open Mpesa C2B Payment Register URL and check the Register Status. If it is not Success, re-register.
Site is not publicly accessible	Ensure your Frappe site is accessible from the public internet over HTTPS.
Site is using HTTP instead of HTTPS	Safaricom requires HTTPS. Configure a valid TLS certificate on your domain.
Previously registered URLs are stale	Log in to the Daraja Portal, go to Self Services, delete the old URLs, and re-register.

Symptom: The Mpesa C2B Payment Register URL document shows a failed registration status.

Resolution:

Confirm the Business Shortcode in Mpesa Settings matches the Paybill or Till number on your Daraja application.
Confirm the Consumer Key and Consumer Secret are correct.
Ensure your domain is live, HTTPS-enabled, and accessible from outside your network.
Delete the existing registration record and create a new one.

Symptom: The Payment Request was saved but the customer did not receive an STK Push on their phone.

Causes and Resolutions:

Cause	Resolution
Incorrect phone number format	Ensure the number is in the format `2547XXXXXXXX` (no leading zero, no plus sign).
Customer's phone is off or out of network	Ask the customer to turn on their phone and retry.
Mpesa Express Settings not linked to Mode of Payment	Confirm the Mode of Payment on the Payment Request is linked to an Mpesa Express Settings record.
Daraja application not live	Confirm your Daraja application has been approved for production and is using the correct environment credentials.

Symptom: After submitting a B2C Payment Disbursement, all references show a failed status.

Causes and Resolutions:

Cause	Resolution
Initiator credentials are wrong	Check Initiator Name and Password in Mpesa Settings.
Security Credential is outdated	Ensure the correct public key certificate (sandbox or production) is saved in Mpesa Public Key Certificate.
Insufficient M-Pesa float	Confirm your business M-Pesa wallet has enough balance to cover the disbursements.
Phone numbers are in the wrong format	All numbers must be in the format `254XXXXXXXXX`.

Use the Retry Failed Payments button to reattempt disbursement for failed references without reprocessing successful ones.

Always test in the sandbox environment before switching to production credentials.
Keep sandbox and production Mpesa Settings as separate records to avoid confusion.
Monitor the Frappe error log (Settings > Error Log) for detailed stack traces when an API call fails silently.
Ensure your server's clock is accurate. Token generation and callback validation can fail if the server time is significantly out of sync.