K-Pay for WooCommerce

Integrate K-Pay as a Mobile Money payment method in your WooCommerce store. Support MTN MoMo, Orange Money and other operators across 12 African countries.

Download plugin v2.1.0

Version 2.1.0 — Compatible with WordPress 6.x and WooCommerce 8.x+

Prerequisites

WordPress 6.0 or higher
WooCommerce 8.0 or higher (active)
PHP 7.4 or higher
SSL certificate (HTTPS) recommended for production
A K-Pay account with API keys (sandbox or production)

Installation

Method 1: Via WordPress dashboard

The simplest method to install the plugin.

Download the plugin ZIP file using the button above
In WordPress, go to Plugins → Add New → Upload Plugin
Select the wc-kpay-gateway-2.1.0.zip file and click Install
Activate the plugin once installation is complete

Method 2: Via FTP / command line

For advanced users or automated deployments.

Manual installation

# Extraire le zip et copier le dossier dans WordPress
unzip wc-kpay-gateway-2.1.0.zip -d /tmp/kpay
cp -r /tmp/kpay/wc-kpay-gateway /var/www/html/wp-content/plugins/

# Structure attendue :
# wp-content/plugins/wc-kpay-gateway/wc-kpay-gateway.php

Expected structure

The wc-kpay-gateway folder must be placed directly inside wp-content/plugins/. The main file wc-kpay-gateway.php must be at the root of that folder.

Configuration

After activation, configure the plugin from WooCommerce settings.

Navigation path

WooCommerce → Settings → Payments → K-Pay

General settings

General fields

enabledcheckbox

Enable or disable K-Pay as a payment method at checkout.

titletext

Name displayed to the customer during payment (default: Mobile Money).

descriptiontextarea

Descriptive text displayed below the title at checkout.

languageselect

Payment interface language: site language, French, or English.

Environment and API keys

Connection keys

environmentselect

Sandbox (test) or Live (production). Always start with Sandbox.

sandbox_api_keytext

Test API key (kpay_test_ prefix). Available in your K-Pay dashboard.

sandbox_secret_keypassword

Test secret key. Never share or expose it on the client side.

live_api_keytext

Production API key (kpay_live_ prefix). Activated after KYC validation.

live_secret_keypassword

Production secret key. Keep it confidential.

Payment and security

Payment options

payment_modeselect

USSD: customer enters their number on your site. Gateway: redirect to K-Pay payment page.

providersmultiselect

Mobile Money operators offered at checkout. Automatically filtered by your store's currency.

webhook_secretpassword

Secret to verify HMAC signatures of K-Pay webhook notifications.

gateway_secretpassword

Secret to verify return redirects in Gateway mode. Required if using Gateway mode.

debugcheckbox

Enable API exchange logging in WooCommerce → Status → Logs.

Currency configuration

K-Pay does not perform currency conversion. Your WooCommerce store must use a supported currency.

Navigation path

WooCommerce → Settings → General → Currency

Supported currencies

XAF, XOF, KES, CDF, UGX, RWF, ZMW, or SLE. If your currency is not in this list, the K-Pay payment method will not be visible at checkout.

Payment modes

USSD Mode

The customer enters their operator and phone number directly on your checkout page.

Customer selects "Mobile Money" at checkout
They select their operator (MTN, Orange, etc.) and enter their number
They receive a confirmation prompt on their phone
After validation, the order is automatically confirmed via webhook

Gateway Mode (redirect)

The customer is redirected to K-Pay's hosted payment page to complete payment.

Customer selects "Mobile Money" at checkout
They are redirected to K-Pay's secure payment page
They choose their operator and enter their number on the K-Pay page
After payment, they are redirected back to your site with automatic confirmation

Which mode to choose?

USSD mode provides a smoother experience as the customer stays on your site. Gateway mode is simpler to integrate and automatically handles operator selection. The chosen mode must match your K-Pay application configuration.

Webhook configuration

Webhooks allow K-Pay to notify your store in real-time about payment status.

Webhook URL

https://votre-site.com/?wc-api=kpay

Copy the webhook URL displayed in the plugin settings
Add this URL in your K-Pay dashboard (Webhooks section of your application)
Copy the webhook secret generated by K-Pay and paste it in the corresponding plugin field

Important

Without a configured webhook, orders will remain in "on hold" status indefinitely. The webhook is essential for automatic payment confirmation.

Testing the plugin

Before going to production, perform a complete test payment.

Verify the environment is set to Sandbox
Enter your test API keys (kpay_test_...)
Add a product to cart and proceed to checkout
Select Mobile Money and use the test number
Verify the order changes to "Processing" or "Completed" status

Test number (sandbox)

See the complete list of test numbers by country and operator in the virtual numbers documentation.

Tip

Enable debug mode to see detailed API exchanges in WooCommerce → Status → Logs. This makes troubleshooting easier.

Going to production

Once your tests are successful, go live by following these steps.

Complete your KYC verification on the K-Pay dashboard
Switch the environment from Sandbox to Live in the plugin settings
Enter your production API keys (kpay_live_...)
Make a real small-amount transaction to validate the complete flow

Troubleshooting

K-Pay doesn't appear at checkout

Verify that WooCommerce is active, the currency is supported (XAF, XOF, etc.), the plugin is activated, and valid API keys are configured.

Currency error

K-Pay does not convert currencies. Make sure your store's currency matches your target country (e.g., XAF for Cameroon).

Orders remain on hold

Verify the webhook URL is properly configured in your K-Pay dashboard and the webhook secret is correctly entered in the plugin. Enable debug to inspect logs.

Gateway mode error

The gateway secret is required in Gateway mode. Verify it is properly configured and that your K-Pay application's payment mode matches.

Source code

The plugin source code is available on GitHub.

Related resources

Payments APIComplete documentation of the K-Pay payment API.

WebhooksConfigure and secure payment notifications.

ProvidersList of supported Mobile Money operators by country.

Test numbersSandbox phone numbers for each country.

Was this page helpful?