MPESA Donation Plugin Docs

---

Introduction

The MPESA Donation Plugin integrates MPESA’s payment gateway with WordPress, allowing users to make donations directly through your website. This documentation provides details on installation, configuration, usage, and customization.

Features

• MPESA Payment Integration: Accept donations via MPESA.
• Donation Status Tracking: View donation statuses in the WordPress admin.
• Shortcodes: Display donation status and thank you messages on your website.

Installation

1. Download and Install

1. Download the MPESA Donation Plugin ZIP file from the source.
2. Log in to your WordPress admin panel.
3. Navigate to Plugins > Add New.
4. Click Upload Plugin and choose the downloaded ZIP file.
5. Click Install Now and then Activate the plugin.

2. Configure the Plugin

1. Go to Settings > MPESA Donation to configure the plugin settings.
2. Enter your MPESA API credentials (API Key, API Secret, etc.).
3. Set up your donation amounts and other preferences.

Configuration

1. API Credentials

• API Key: Enter your MPESA API key.
• API Secret: Enter your MPESA API secret.
• Shortcode: Use the No transactions found. shortcode to display donation statuses.

2. Donation Settings

• Minimum Donation Amount: Define the minimum amount a user can donate.
• Currency: Set the currency used for donations (default is KES).

Shortcodes

1. mpesa_transaction_status

Displays the donation status or a thank you message.

Usage:

[mpesa_transaction_status]

Parameters:

• mpesa_donate_success: Set to true to display a thank you message. (Optional)
• amount: The donation amount to display. (Optional)

Example:

[mpesa_transaction_status mpesa_donate_success=true amount=1000]

2. Customization

• CSS Customization: Modify the CSS in the shortcode to fit your website’s design. You can add custom styles directly in the plugin or through your theme’s custom CSS section.

Donation Status Page

The donation status page shows the transaction details. To view this page, add the No transactions found. shortcode to a page or post. This page will display:

• Order Number
• Amount
• Phone Number
• Transaction Status

Example Code

Add the following to a WordPress page or post to display the donation status:

[mpesa_transaction_status]

Handling MPESA Callback

The plugin handles MPESA callbacks to update donation statuses. Ensure your MPESA API settings are correctly configured to receive callbacks.

Callback Function

Here’s an example callback function that processes donation statuses:

function handle_mpesa_callback() {
    // Your callback handling code here
}

Troubleshooting

1. Plugin Not Redirecting

Ensure that your wp_redirect URLs are correct and that query parameters are properly set.

2. Amount Showing as 0.00

Verify that the amount parameter is correctly passed and retrieved in your shortcode. Debug by logging the amount to check if it is correctly set.

Changelog

1.0.0

• Initial release with MPESA payment integration and donation status tracking.

License

This plugin is licensed under the GNU General Public License.

---

Additional Resources

• WordPress Plugin Developer Handbook: WordPress Plugin Handbook
• MPESA API Documentation: MPESA API Documentation

Feel free to modify and expand upon this documentation based on specific features and user feedback.