Back-to-Business Sale Up to 30% off
Claim Now Close discount banner
Sign In Try For Free
View Categories

M-Pesa Payment Gateway

Directorist – M-Pesa Payment Gateway adds M-Pesa as a payment method for Directorist checkout and for Directorist Pricing Plans. Buyers pay by receiving an STK Push prompt on their phone and entering their M-Pesa PIN; recurring plan payments use Safaricom’s Ratiba standing order collections. This guide walks through getting Daraja credentials, configuring the gateway, and confirming it works before you take live payments.

Requirements #

  • Directorist core plugin, active.
  • WordPress 6.5 or later, PHP 7.4 or later.
  • A Safaricom Daraja developer account with an app (sandbox and/or production/live).
  • Directorist Pricing Plans addon, active — only required if you want to accept recurring plan payments through M-Pesa’s Ratiba standing orders. One-time listing payments work without it.

Prerequisites: Create a Daraja app #

Before configuring the plugin, create an app in the Safaricom Daraja developer portal and collect these values. You’ll need a separate set for Sandbox (testing) and Live (production):

  • Consumer Key
  • Consumer Secret
  • Shortcode (your PayBill business number, or your Till number)
  • Passkey (issued for M-Pesa Online / Lipa Na M-Pesa Online integration)

Step 1 – Turn on M-Pesa as a payment method #

Path: WP Admin → Settings → Monetization → Payment gateways

  1. Go to Settings, open Monetization, and stay on the Payment gateways tab.
  2. Under Payment Methods, find M-Pesa in the list and toggle it on. This step is required — M-Pesa won’t appear at checkout until this toggle is enabled, even if the gateway is fully configured.
  3. Optionally, open the Default gateway dropdown and select M-Pesa if you want it pre-selected for buyers at checkout instead of another active gateway.
  4. Click Save changes.

Step 2 – Open the M-Pesa Gateway settings #

Path: WP Admin → Directorist → Settings → Monetization → M-Pesa Gateway

(Verify this exact menu wording against your Directorist install — the plugin registers this page into Directorist’s Monetization settings under the label M-Pesa Gateway*, but the top-level menu labels can vary slightly by the Directorist version.)*

Step 3 – Choose Sandbox or Live mode #

  1. Find the Enable Sandbox Mode toggle at the top of the settings section.
  2. Leave it on to test with Safaricom’s sandbox environment (this is the default state).
  3. Turn it off once you’re ready to accept real payments — this switches the gateway to your Live credentials and the live Safaricom API.

Only one set of credentials is active at a time, based on this toggle: sandbox fields are used while it’s on, live fields are used while it’s off.

Step 4 – Set the checkout text #

  1. In Gateway Title, enter the name buyers see on the Directorist checkout page. Defaults to M-Pesa.
  2. In Gateway Description, enter the explanation shown under the gateway option. Defaults to “Pay with M-Pesa. We will send an STK Push prompt to your phone to authorize this payment.”

Step 5 – Choose your Shortcode Type #

  1. Open the Shortcode Type dropdown.
  2. Select PayBill if you collect payments through a PayBill business number (CustomerPayBillOnline).
  3. Select Till if you collect payments through a Buy Goods till number (CustomerBuyGoodsOnline).

This determines which M-Pesa transaction type the plugin sends with every STK Push request, so it must match how your shortcode is actually registered with Safaricom.

Step 6 – Enter your Sandbox credentials #

Fill these in using the values from your Daraja sandbox app:

  1. Sandbox Consumer Key
  2. Sandbox Consumer Secret
  3. Sandbox Shortcode / Till
  4. Sandbox Passkey

Step 7 – Enter your Live credentials #

Fill these in using the values from your Daraja live/production app (needed once you’re ready to go live, not required while testing in sandbox mode):

  1. Live Consumer Key
  2. Live Consumer Secret
  3. Live Shortcode / Till
  4. Live Passkey

If any of the required fields for the currently active mode (sandbox or live) are left empty, Directorist shows a warning banner in the admin area: “Directorist – M-Pesa is active but Daraja credentials are incomplete for the current mode,” with a link back to this settings page.

Step 8 – Set the Callback URL in Daraja #

  1. Copy the value shown in the read-only Callback URL field on this settings page. It’s generated automatically in the form https://yourdomain.com/wp-json/directorist-mpesa/callback.
  2. Paste this URL into the corresponding callback/result URL field in your Daraja app (sandbox and live apps each need it set).
  3. Confirm the URL is publicly reachable over HTTPS — Safaricom must be able to reach your site directly. A staging site behind a login wall, IP allowlist, or localhost won’t receive callbacks.

Step 9 – Test the connection #

  1. Click Test Connection next to Test on the settings page.
  2. Wait for the page to reload with a result banner at the top.
  3. A success banner confirms the plugin obtained an access token from Safaricom using your current mode’s credentials (sandbox or live, whichever is active).
  4. An error banner shows the reason the connection failed — most commonly incomplete credentials, an invalid Consumer Key/Secret pair, or Safaricom temporarily rejecting the request. Re-check the credentials for the active mode and try again.

How checkout works for buyers #

Once configured, M-Pesa appears as a payment option alongside Directorist’s other gateways.

  1. The buyer selects M-Pesa at checkout, which reveals an M-Pesa phone number field.
  2. The buyer enters their Safaricom number (any format is accepted — for example 0708374149 or 254708374149 — the plugin normalizes it to the 2547XXXXXXXX format Safaricom requires).
  3. On submitting the order, the plugin sends an STK Push request and takes the buyer to the payment receipt page, which displays a message that a prompt was sent to their (partially masked) phone number.
  4. The buyer authorizes the payment on their phone by entering their M-Pesa PIN.
  5. Safaricom sends the result to your Callback URL, and the plugin marks the order Paid or Failed accordingly. As a fallback, a background task also checks any still-pending M-Pesa orders every 15 minutes in case a callback is delayed or missed.

Recurring plan payments (Ratiba) #

If Directorist Pricing Plans is active and a plan is marked recurring, M-Pesa uses Safaricom’s Ratiba standing order API instead of a one-time STK Push. The buyer authorizes the standing order once at checkout the same way as a normal STK Push; Safaricom then collects renewal payments automatically on the plan’s billing frequency (daily, weekly, monthly, or yearly, based on the plan’s interval). Each successful recurring collection creates a renewal order in Directorist and advances the subscriber’s billing period automatically — no separate action is needed after the initial setup.

Going live checklist #

  • M-Pesa is toggled on under Settings → Monetization → Payment gateways → Payment Methods — this is required for the gateway to appear at checkout, separate from having credentials configured.
  • Enable Sandbox Mode is turned off.
  • Live Consumer Key, Live Consumer Secret, Live Shortcode / Till, and Live Passkey are all filled in.
  • Shortcode Type matches how your live shortcode is registered with Safaricom (PayBill vs. Till).
  • The Callback URL is set in your live Daraja app and is publicly reachable.
  • Test Connection returns a success banner in live mode.
What are your Feelings