Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developers.kulmipay.com/llms.txt

Use this file to discover all available pages before exploring further.

Use the KulmiPay WooCommerce plugin to add KulmiPay as a payment method at checkout. The plugin creates a KulmiPay checkout session for each WooCommerce order, redirects or opens the payment popup depending on your settings, and confirms payment status before marking the order paid. The plugin currently supports KulmiPay checkout for M-Pesa and PesaLink payments.

​
Requirements

  • WordPress 6.0 or later
  • WooCommerce 8.0 or later
  • PHP 7.4 or later
  • A KulmiPay account with a public API key
  • HTTPS enabled before you go live

​
Install the plugin

1

Download the plugin ZIP

Download the KulmiPay WooCommerce plugin ZIP from your release package. In this repository, the packaged artifact is wordpress/dist/kulmipay.zip.
2

Upload it in WordPress

In WP Admin, go to Plugins → Add New → Upload Plugin, select kulmipay.zip, and click Install Now.
3

Activate KulmiPay

After installation completes, click Activate Plugin. The payment gateway will appear in WooCommerce payment settings as Kulmipay.

​
Configure WooCommerce

Open WooCommerce → Settings → Payments, then enable Kulmipay. Configure the following fields:
FieldDescription
Enable KulmipayTurns the payment method on at checkout.
TitleThe payment method name shown to customers. Defaults to Kulmipay.
DescriptionCheckout text shown below the payment method.
Test modeUses the sandbox host and test public key when enabled.
Trust BadgesShows the KulmiPay checkout badge at checkout.
Test Public KeyYour sandbox public key. It must start with ISPubKey_test.
Live Public KeyYour live public key. It must start with ISPubKey_live.
Payment OptionChoose Redirect to send customers to KulmiPay, or Popup to keep checkout in-page.
Use a public key in WooCommerce. Do not paste a secret key into the plugin settings. Secret keys start with ISSecretKey_ and are only for backend API calls.

​
Get your API key

Use the environment that matches your store mode:
ModeDashboardKey format
Sandboxsandbox.kulmipay.com/account/api-keys/ISPubKey_test_...
Liveapp.kulmipay.com/account/api-keys/ISPubKey_live_...
When you are ready to process real payments, turn off Test mode, add your live public key, and make sure your WordPress site uses HTTPS.

​
Test checkout

  1. Add a product to your cart.
  2. Go to checkout.
  3. Select Kulmipay as the payment method.
  4. Place the order.
  5. Complete the payment in the KulmiPay checkout flow.
After KulmiPay confirms the payment, the plugin validates the invoice through POST /api/v1/payment/status/ and marks the WooCommerce order as paid.

​
Redirects and webhooks

The plugin sends both redirect_url and callback_url when creating the checkout session. Both point to your WooCommerce callback URL: 
https://your-store.example/wc-api/kulmipay?ref_id=<order_id>
KulmiPay also posts webhook-style callbacks to: 
https://your-store.example/wc-api/kulmipay_webhook
Keep these URLs publicly reachable so WooCommerce can reconcile successful payments.

​
Troubleshooting

IssueWhat to check
KulmiPay does not appear at checkoutConfirm the plugin is active and Enable Kulmipay is checked under WooCommerce payment settings.
”Public key is required”Add either a test public key or live public key, depending on Test mode.
”Invalid public key”Test keys must start with ISPubKey_test; live keys must start with ISPubKey_live.
Live checkout fails on HTTPEnable HTTPS or switch back to Test mode while developing locally.
Order remains pendingConfirm the customer completed payment and that /wc-api/kulmipay and /wc-api/kulmipay_webhook are reachable from the internet.
The WooCommerce plugin uses the same KulmiPay checkout infrastructure as the browser SDK, but WordPress merchants only need to install the plugin and configure a public key.