Common M-PESA API Errors: Simplifying WooCommerce Payments

Integrating M-PESA STK Push payments into your WooCommerce store can elevate the payment experience for your customers. However, like any payment gateway, errors can occasionally disrupt transactions, affecting customer satisfaction and business flow. Understanding these errors, their causes, and solutions will help streamline your payment system.

Our WooCommerce M-PESA plugin simplifies this process by integrating directly with M-PESA’s STK Push, providing a seamless solution for handling transactions. Here we cover common M-PESA STK Push errors, explain the causes, and offer solutions so you can ensure your checkout runs smoothly.

1. Error Code: 1037

Description: DS timeout – user cannot be reached
Cause: This error is seen in Lipa Na M-PESA transactions when the STK Push prompt doesn’t reach the user. This may happen due to:

• Old or outdated SIM card: Older SIM cards (over 3 years) may not support updated STK functionality.
• Network Issues: If the user’s phone is offline or in an area with poor reception, the prompt may not reach them.

Solution:

• Update SIM: Customers can update their SIM by dialing *234*1*6# or visiting a Safaricom agent for a replacement.
• Ensure Network Connectivity: Make sure the customer’s phone is online and in an area with good network reception.

Note: With recent updates, STK Push is now a network-initiated prompt, reducing errors tied to SIM compatibility.

2. Error Code: 1025

Description: An error occurred while sending a push request
Cause: This system error often occurs due to a temporary issue within the transaction request.

Solution: Retry the request, ensuring that your system and the customer’s network connection are functioning correctly.

3. Error Code: 9999

Description: An error occurred while sending a push request
Cause: Often linked to long USSD messages (more than 182 characters), which may be rejected by the system.

Solution: Adjust your message to remain within 182 characters. Ensure the prompt is concise and clear, minimizing the character count.

4. Error Code: 1037

Description: No response from the user
Cause: This error means the prompt was received by the customer, but the response was not sent back in time. It can occur due to backend delays rather than user actions.

Solution: Retry the transaction after the initial callback. It’s also helpful to notify the user that their request didn’t complete successfully.

5. Error Code: 1032

Description: The request was canceled by the user
Cause: This error occurs when:

• The STK Push prompt timed out while waiting for user input.
• The user actively canceled the transaction.

Solution: Inform the user that they either canceled the request or didn’t respond within the required time frame. Consider reinitiating the transaction if the user is still interested in completing the payment.

6. Error Code: 1

Description: Insufficient balance for the transaction
Cause: This occurs when:

• The user has insufficient funds on their M-PESA account.
• The user declined to use the Overdraft feature (Fuliza).

Solution: Advise the user to either top up their M-PESA balance or opt to use Fuliza if prompted during the transaction.

7. Error Code: 2001

Description: The initiator information is invalid
Cause: This error arises when:

• The initiator (customer) enters incorrect credentials.
• The customer incorrectly inputs their M-PESA PIN during STK Push validation.

Solution: Ensure that the user has the correct credentials and enters the proper PIN to authorize the transaction.

8. Error Code: 1019

Description: Transaction has expired
Cause: The transaction took too long to process and exceeded the allowable time for completion.

Solution: Encourage users to respond quickly after the STK prompt appears to avoid transaction expiration.

9. Error Code: 1001

Description: Unable to lock subscriber; a transaction is already in process
Cause: This occurs due to:

• A duplicated MSISDN (phone number) already involved in an ongoing session.
• An ongoing USSD session conflicting with the STK Push.
• Supplementary services being restricted for the user.

Solution:

• Ensure only one push request is active at a time.
• Ask the customer to close any ongoing USSD session.
• Wait 2-3 minutes before retrying the transaction.

How Our WooCommerce M-PESA Plugin Helps Manage These Errors

Our WooCommerce M-PESA plugin is designed to handle M-PESA STK Push payments with precision, offering features that allow you to manage and troubleshoot common issues. By directly integrating M-PESA into your WooCommerce store, the plugin automates transactions and handles real-time notifications, so errors like these become easier to address.

Benefits of Using Our M-PESA Plugin for WooCommerce

1. Error Logging: Our plugin logs transaction errors in your WooCommerce dashboard, helping you quickly identify issues like DS timeouts or insufficient balances.
2. Seamless User Experience: The plugin is designed to send concise, pre-formatted messages that avoid errors like 9999 by keeping character count below 182.
3. Retry and Notification: If a transaction times out, our plugin allows you to retry and inform the customer, preventing confusion and improving transaction success rates.
4. Integration with M-PESA: By integrating with M-PESA’s Daraja API, our plugin ensures that transactions are handled in real-time, reducing the chances of errors related to outdated sessions or conflicting MSISDN requests.
5. Increased Sales Potential: With STK Push handling payments smoothly, customers are less likely to abandon their carts due to payment errors, boosting your conversion rates.

Businesses using our mpesa plugin, such as cuppie.co.ke (selling menstrual cups), bubblewrap.co.ke (offering packing materials), and aromabox.co.ke, have already experienced the benefits of seamless STK Push integration. The improved checkout experience has helped these businesses retain customers and reduce transaction errors.

Understanding common M-PESA API errors and how to resolve them can significantly enhance your customers’ checkout experience. Our WooCommerce M-PESA plugin is built with robust features designed to tackle these challenges, ensuring transactions proceed smoothly and errors are quickly managed.

By adopting our mpesa plugin, your WooCommerce store can handle M-PESA transactions with ease, just like cuppie.co.ke, bubblewrap.co.ke, and aromabox.co.ke. This level of integration not only saves time but also boosts customer satisfaction and sales. Choose our WooCommerce M-PESA plugin today, and bring seamless payments to your customers!