GiftedPay for WooCommerce

Accept M-Pesa STK Push payments on your WooCommerce store — one API key, no complex setup.

What It Does

When a customer checks out, they enter their Safaricom number. An M-Pesa STK Push is sent to their phone instantly. They enter their PIN, and the order is marked as paid — automatically, in real time, with no page refresh.

Customer enters number → STK Push sent → Customer enters PIN → Order confirmed ✓

Features

• One credential — only your GiftedPay API key is needed
• Real-time status — thank-you page polls every 4 seconds and updates live
• Callback webhook — GiftedPay also notifies your store when payment settles
• Phone validation — accepts 07xx, 01xx, or 254xxx formats, validates live at checkout
• Receipt links — printable M-Pesa receipt linked on thank-you page and in order emails
• Connection test — admin settings page confirms your API key works after saving
• HPOS compatible — supports WooCommerce High Performance Order Storage
• Dual confirmation — both polling and webhook update the order, whichever arrives first

Requirements

Installation

Option A — Upload ZIP (recommended)

1. Download the latest release ZIP
2. In your WordPress admin go to Plugins → Add New → Upload Plugin
3. Choose the downloaded ZIP file → click Install Now
4. Click Activate Plugin

Option B — Manual (FTP / cPanel)

1. Download and unzip the release
2. Upload the giftedpay-woocommerce/ folder to /wp-content/plugins/
3. Go to WordPress Admin → Plugins and activate GiftedPay for WooCommerce

Option C — Clone with Git

cd /path/to/wordpress/wp-content/plugins/
git clone https://github.com/mauricegift/giftedpay-woocommerce-plugin.git giftedpay-woocommerce

Then activate via Plugins → Installed Plugins.

Configuration

After activation, go to WooCommerce → Settings → Payments → GiftedPay M-Pesa.

Step 1 — Get your API key

1. Log in to pay.gifted.co.ke
2. Go to Dashboard → Apps
3. Click your app (create one if you haven't yet)
4. Copy the API Key — it starts with gifted_mpesa_stk_

Step 2 — Paste it in WordPress

Paste the key into the GiftedPay API Key field and click Save changes.

A green "✓ API key is valid" message appears immediately below the field if the connection works.

Step 3 — That's it

No callback URL to configure. The plugin automatically sets the callback URL to:

https://yourstore.com/?wc-api=giftedpay_callback

This is sent with every payment request — GiftedPay will POST payment results back to this URL automatically.

Settings Reference

How Payments Work (Technical Flow)

1. Customer selects M-Pesa at checkout
2. Enters Safaricom number (07xx / 01xx / 254xxx — auto-normalised)
3. Clicks "Place Order"
4. Plugin calls  POST https://mpesa.gifted.co.ke/api/payments/process
                 Authorization: Bearer <api_key>
                 { phone_number, amount, account_reference, transaction_desc, callback_url }
5. GiftedPay triggers Safaricom STK Push → customer receives PIN prompt
6. Plugin redirects to thank-you page
7. Thank-you page polls  POST /payments/verify  every 4s via WordPress AJAX
   (API key stays server-side — never exposed to browser)
8. In parallel, Safaricom posts callback to GiftedPay
   → GiftedPay posts to  /?wc-api=giftedpay_callback
   → Plugin finds order by _giftedpay_checkout_id meta, marks paid
9. Whichever arrives first (poll or callback) calls $order->payment_complete()

Callback Payload

GiftedPay POSTs to your /?wc-api=giftedpay_callback endpoint:

{
  "checkout_request_id": "ws_CO_31032026031749...",
  "status": "completed",
  "mpesa_receipt_number": "UCV6EAV0NH",
  "amount": 1500,
  "phone_number": "254712345678",
  "result_desc": "The service request is processed successfully."
}

The plugin also handles the raw Safaricom STK callback format as a fallback.

Phone Number Normalisation

All of these are accepted and converted to 254XXXXXXXXX automatically:

Order Meta

The plugin stores the following metadata on each order:

Receipt Link

After a successful payment, customers see a View M-Pesa Receipt link that opens:

https://mpesa.gifted.co.ke/api/payments/receipt/<checkout_request_id>

This page shows a printable receipt and includes a Save as PDF button. The same link appears in WooCommerce order confirmation emails.

Sandbox vs Production

To go live, upgrade your GiftedPay account from the dashboard. No code changes needed.

Troubleshooting

"STK push not received"

• Confirm the phone number is a valid Safaricom number (Airtel/Faiba not supported for STK)
• Check your GiftedPay app is not disabled
• In sandbox mode, only the account owner's number works

"Payment confirmed but order still shows Pending"

• Check WordPress error logs for callback delivery failures
• Ensure /?wc-api=giftedpay_callback is publicly accessible (not behind a login or firewall)
• The polling fallback should catch this within ~8 seconds anyway

"API key is invalid" in settings

• Re-copy the key from GiftedPay Dashboard → Apps → [your app]
• Make sure there are no leading/trailing spaces

"Could not reach GiftedPay API"

• Your server must be able to make outbound HTTPS requests to mpesa.gifted.co.ke
• Check if your host blocks outbound connections (common on some shared hosts)

Store currency not KES

• Go to WooCommerce → Settings → General → Currency → Kenyan Shilling (KES)

File Structure

giftedpay-woocommerce/
├── giftedpay-woocommerce.php          ← Main plugin file (entry point)
├── includes/
│   └── class-wc-giftedpay-gateway.php ← Payment gateway class
├── assets/
│   ├── js/
│   │   ├── checkout.js                ← Phone validation at checkout
│   │   └── thankyou.js               ← Real-time polling on thank-you page
│   ├── css/
│   │   └── giftedpay.css             ← Styles for checkout + thank-you page
│   └── images/
│       └── mpesa-badge.svg           ← M-Pesa badge shown at checkout
├── readme.txt                         ← WordPress plugin readme
└── README.md                          ← This file

API Reference

This plugin integrates with the GiftedPay API. Key endpoints used:

Full API docs: https://pay.gifted.co.ke/api-guide

Support

• Documentation: https://pay.gifted.co.ke/api-guide
• Email: payments@gifted.co.ke
• Website: https://pay.gifted.co.ke
• Issues: GitHub Issues

License

GPL-2.0+ — see LICENSE for details.

Changelog

1.0.0

• Initial release
• STK Push initiation with POST /payments/process
• Real-time polling via WordPress AJAX (API key stays server-side)
• Webhook callback handler (?wc-api=giftedpay_callback)
• Live connection test in admin settings
• Receipt link on thank-you page and order emails
• HPOS compatibility declared
• Phone number auto-normalisation (07xx / 01xx / 254xxx)