TK Paybill and Till Checkout for M-Pesa

Description

TK MPesa Payment Gateway allows your WooCommerce customers to pay directly from their mobile phone via MPesa STK Push (Lipa Na MPesa Online).

This plugin is not affiliated with, endorsed by, or sponsored by Safaricom PLC. M-Pesa and Daraja are trademarks of Safaricom PLC, referenced here only to describe compatibility with their payment service.

How it works:

1. A customer checks out and selects MPesa Payments, entering the MPesa number the STK prompt should be sent to.
2. The plugin authenticates with the Safaricom Daraja API and sends an STK Push (stkpush/v1/processrequest) request for the order total.
3. The customer receives a “Lipa Na MPesa” prompt directly on their phone and enters their MPesa PIN to approve it.
4. Safaricom sends a payment-result callback to this site’s dedicated REST endpoint, protected by a per-install secret token so only genuine Safaricom callbacks are accepted.
5. On a successful callback, the order is marked paid automatically and the confirmation – including the MPesa number that was billed – is recorded on the order.

If a customer doesn’t complete the prompt in time or the order is otherwise left unpaid, they can return to it later through WooCommerce’s standard “Pay for order” screen to retry.

Payment types:

• Paybill (CustomerPayBillOnline) – pay into a Paybill number and account
• Buy Goods Till (CustomerBuyGoodsOnline) – pay into a Till number; the Till must be settling funds to a bank account
• Configurable Short Code (your Paybill/Till number) and Payment To number, independent of the payment type selected

Checkout compatibility:

• Classic shortcode checkout
• WooCommerce Checkout Block, via a full AbstractPaymentMethodType integration
• HPOS (High-Performance Order Storage) compatible

Payment tracking & admin tools:

• A dedicated MPesa Payments admin menu, separate from WooCommerce Orders, listing every STK Push request with its date, Request ID, linked Order ID, requesting MPesa number, amount, and payment status
• A Logs submenu that jumps straight to this plugin’s entries under WooCommerce → Status → Logs (source tk-mpesa), useful when a payment doesn’t go through
• Paid orders show the MPesa confirmation and billed phone number directly on the WooCommerce order screen, alongside the standard order details

Sandbox / test mode:

• A Test mode toggle switches the gateway to the Safaricom Daraja sandbox API for development, without touching your live credentials

Security:

• The MPesa callback endpoint requires a per-install secret token (generated on activation) before it will process any callback, preventing forged requests from marking an order as paid
• Callback payment amounts are compared using a tolerant float comparison rather than a loose ==
• All checkout input is sanitised and all admin/checkout output is escaped
• Checkout requests are protected by WordPress nonces

Requirements:

• A Safaricom MPesa Paybill or Buy Goods Till number
• A registered Safaricom Daraja application (Consumer Key, Consumer Secret, PassKey)
• An HTTPS-enabled WordPress site (required by the MPesa callback)

External services

This plugin connects to the Safaricom Daraja API to process M-Pesa payments. This is required for the plugin’s core function – initiating an M-Pesa STK Push payment request to the customer’s phone and receiving confirmation that it was paid.

Two Daraja endpoints are used:

• oauth/v1/generate – authenticates the site with Safaricom using the Consumer Key and Consumer Secret you enter in the gateway settings. No customer data is sent to this endpoint.
• mpesa/stkpush/v1/processrequest – initiates the STK Push. When a customer places an order and chooses this payment method at checkout, the following is sent: your configured Paybill/Till short code, the order amount, the customer’s phone number, a callback URL, and the WooCommerce order ID (as a reference). Safaricom then sends a payment-result callback to this site’s REST endpoint.

This plugin is not affiliated with, endorsed by, or sponsored by Safaricom PLC. Learn more: Daraja API Terms and Conditions, Safaricom Data Privacy Statement.