VibeFox Pesapal for WooCommerce — Help

Requirements

WordPress: 6.2 or later.

WooCommerce: 8.0 or later, installed and active. The plugin refuses to activate without it.

PHP: 8.0 or later.

Currency: the order must be in KES, UGX, TZS, ZMW, RWF or USD. In other currencies the payment method is hidden at checkout. The order is charged in its own currency; the plugin does not convert currencies. Amounts are sent in major units, rounded to the precision of the currency (UGX and RWF without decimals).

Pesapal account: you need the consumer key and consumer secret of a Pesapal merchant account. Sandbox and live keys are different. Sandbox keys come from a demo merchant account at cybqa.pesapal.com (Pesapal also publishes demo keys on its developer portal). Live keys come from your Pesapal merchant dashboard. Nothing else has to be set up in the Pesapal dashboard: the plugin registers its notification URL itself. Your site must be reachable from the internet, because Pesapal sends payment notifications to it.

VibeFox license key: bought on vibefox.net. One key works on one domain.

Installation

1. In WordPress go to Plugins > Add New > Upload Plugin, choose the plugin ZIP file and click Install Now. You can also upload the wcp_pesapal_pay folder to /wp-content/plugins/ by FTP.

2. Click Activate.

3. Open the settings: WooCommerce > Settings > Payments > Pesapal > Manage, or click Settings under the plugin name on the Plugins page.

4. Enter your VibeFox license key in the license block at the top of the page and click Activate.

5. Enter the sandbox consumer key and secret, turn on Enable/Disable, save and make a test order.

6. Enter the live consumer key and secret, untick Sandbox mode and save to accept real payments.

Configuration

All settings are on one page: WooCommerce > Settings > Payments > Pesapal. Above the fields a badge shows the mode: SANDBOX with Test payments on cybqa.pesapal.com — no real money is charged. or LIVE with Real payments on pay.pesapal.com. A warning appears when the keys of the current mode are missing (Enter the sandbox consumer key and secret — until then Pesapal is not shown at checkout., or the same for live) and when Pesapal does not support your store currency. In the list of payment methods, Pesapal is marked as Test mode while the sandbox is on.

Payment notifications (IPN)

This block shows the notification URL of your store. It looks like https://your-site/wc-api/pesapal_pay/. The URL is registered with Pesapal automatically at the first payment, separately for sandbox and live and for each pair of keys, so there is nothing to configure. After the first payment the block shows Registered IPN ID: with the ID Pesapal returned; before that it says Not registered yet for the current mode and keys. The URL must be reachable from the internet: no maintenance mode, firewall or password protection in front of it.

Checkout

Enable/Disable: Enable Pesapal turns the payment method on or off. Default: off.

Title: the payment method name customers see at checkout. Default: Pesapal (M-Pesa, Airtel Money, cards).

Description: the text shown under the payment method at checkout. Default: Pay securely with M-Pesa, Airtel Money, card or bank via Pesapal. You will be redirected to Pesapal to complete the payment.

API credentials

The section explains where to get the keys and links to cybqa.pesapal.com and pesapal.com. Enter the sandbox and live keys each in its own field. All key fields are password fields.

Sandbox mode: Use the Pesapal sandbox (no real money). When on, new payments use cybqa.pesapal.com with the sandbox keys. Untick it to accept real payments on pay.pesapal.com with the live keys. Default: on.

Sandbox consumer key: the consumer key of your sandbox (demo) merchant account. Used only in sandbox mode.

Sandbox consumer secret: the consumer secret of your sandbox merchant account. Used only in sandbox mode.

Live consumer key: the consumer key from your Pesapal merchant dashboard. Used when sandbox mode is disabled.

Live consumer secret: the consumer secret from your Pesapal merchant dashboard. Used when sandbox mode is disabled.

Switching the mode or changing keys never reuses an access token or notification ID of the other mode or keys. A payment started in one mode is always checked in that mode, even after you switch.

Advanced

Debug log: Log Pesapal requests and notifications writes details to WooCommerce > Status > Logs, source wcp_pesapal_pay. Errors and warnings are always logged. Keys, tokens and customer data are never logged. Default: off.

Delete data: Delete the plugin settings and logs when the plugin is deleted. Pesapal data saved on orders (tracking IDs, notes) is payment history and is always kept. Deactivating the plugin never deletes anything. Default: off.

Checkout

The customer chooses the payment method (by default Pesapal (M-Pesa, Airtel Money, cards)) and places the order. In sandbox mode the Checkout block shows Sandbox mode: no real money will be charged. The plugin creates a Pesapal payment request for the order total in the order currency, with the billing details of the order, and adds an order note with the mode, amount and Pesapal tracking ID. The customer is sent to the Pesapal payment page and pays with one of the methods Pesapal offers, such as M-Pesa, Airtel Money, MTN, card or bank.

The order is marked paid only after Pesapal confirms it. Pesapal notifications and the customer return carry no payment data and no signature, so the plugin does not trust them: for each one it asks Pesapal for the transaction status with an authenticated server-to-server request, in the mode the payment was started in. It also checks that the transaction belongs to this order and that the paid amount and currency match the order.

After paying, the customer comes back to the order received page. Mobile money payments can take a moment. If the payment is not confirmed yet, the page shows Your payment is being confirmed by Pesapal. You will receive an e-mail as soon as it is confirmed — there is no need to pay again. The notification from Pesapal completes the order later. If the order was put on hold, the page shows Your payment was received and is being reviewed by the shop. You will receive an e-mail once the order is confirmed.

If the customer cancels on the Pesapal page, they come back to the Pay for order page with The Pesapal payment was cancelled. You can try again or choose another payment method. If the payment failed, the message is The Pesapal payment was not successful. Please try again or choose another payment method. The customer can pay the same order again. Every payment attempt of the order is remembered, so a payment made later on an older Pesapal page of the order is still accepted.

If Pesapal cannot start the payment, the customer sees a short message, for example Pesapal is temporarily unavailable. Please try again in a few minutes or choose another payment method., Pesapal is not available at the moment. Please choose another payment method. (wrong keys) or Pesapal could not start the payment: followed by the reason from Pesapal. Technical details go to the order notes and the log. The order total must be greater than zero.

The payment method works on the classic checkout, on the Checkout block and on the Pay for order page. It is compatible with WooCommerce High-Performance Order Storage (HPOS).

The plugin has no payment form on the checkout page itself (the customer always pays on the Pesapal page), no saved cards, no subscriptions or recurring payments and no currency conversion.

Orders and refunds

Order statuses

Pending payment: the customer was sent to Pesapal and has not paid yet, or Pesapal has not confirmed the payment yet.

Processing: Pesapal reports the payment as Completed and the amount and currency match. The order note shows the amount, the payment method, the Pesapal confirmation code and the tracking ID. The transaction ID of the order is the Pesapal tracking ID. Each payment is applied once.

On hold: the paid amount or currency differs from the order (note Pesapal amount/currency mismatch — held for review), or money arrived for an order that had been cancelled before it was paid. Check the payment in the Pesapal dashboard, then complete the order or refund the payment.

Failed: Pesapal reports the latest payment attempt as failed. The note gives the reason from Pesapal. If the customer tries again from the Pay for order page and that attempt fails too, another note with the reason is added. A failure of an older attempt does not change the order. The customer can pay again.

Refunded: Pesapal reports the payment that paid the order as reversed. A reversal of another attempt is only noted on the order.

If a second payment attempt of an order that is already paid is completed as well, the order is not changed. A note asks you to refund the second payment in the Pesapal dashboard. Cancelled and refunded orders are never reopened automatically.

Refunds

The plugin does not send refunds to Pesapal. Refund the payment in the Pesapal dashboard, then record the refund in WooCommerce manually.

License key

The plugin works with a VibeFox license key from vibefox.net. The license block is at the top of WooCommerce > Settings > Payments > Pesapal. Paste the key into License key and click Activate. The block shows the status, for example the date the license is active until and your domain. Use Check now to check the status again, Change key to enter another key and Remove key to remove it from this site. The link Manage licenses and domains in your account opens your vibefox.net account.

One key works on one domain. Removing the key from a site does not free its domain slot. Free the slot in your vibefox.net account.

Without an active key, Pesapal is not shown to customers at checkout. If a payment is started anyway, the customer sees This payment method is not available. Please choose another one. Logged-in store managers still see the payment method, marked (unlicensed — visible to admins only), so you can set up and test the plugin before you buy a key. A reminder appears on the Plugins page and on WooCommerce pages. Existing orders are not affected: payments already started are still confirmed by the Pesapal notification and the customer return.

When a license expires, the plugin keeps working, but updates and support need a renewal. The status is checked again automatically in the background.

Troubleshooting

Pesapal does not appear at checkout: check that the license is active, Enable/Disable is on, the consumer key and secret of the current mode are entered (Sandbox consumer key and Sandbox consumer secret in sandbox mode, Live consumer key and Live consumer secret in live mode) and the order currency is KES, UGX, TZS, ZMW, RWF or USD. The warnings at the top of the settings name the problem. Developers can change the list of currencies with the filter pesapal_p_supported_currencies.

The payment went through, but the order stays Pending payment: the notification from Pesapal did not reach your store and the customer did not come back. Check that the URL shown in Payment notifications (IPN) is reachable from the internet (no maintenance mode, firewall or password protection in front of /wc-api/pesapal_pay/). Look at WooCommerce > Status > Logs, source wcp_pesapal_pay.

How the store answers notifications: a processed notification is answered with HTTP 200. When the plugin cannot process it, it answers with an error, and Pesapal sends the notification again later: 400 (missing or malformed tracking ID), 404 (no order of this store has this tracking ID), 409 (the transaction belongs to another merchant reference; the order is not changed), 502 (the Pesapal API could not be reached at that moment) and 503 (the order was being updated by the customer return at the same moment).

The customer sees Pesapal is not available at the moment: Pesapal rejected the consumer key or secret of the current mode. Check that the keys belong to the mode: sandbox keys work only with the sandbox, live keys only in live mode. The order note shows the Pesapal error.

The customer sees Pesapal is temporarily unavailable: Pesapal could not be reached, or the notification URL could not be registered. Read the order note and the log, and try again.

The order is On hold after payment: read the order note. The paid amount or currency differed from the order, or the payment arrived after the order had been cancelled. Check the payment in the Pesapal dashboard, then process the order or refund the payment.

The license block shows an error: follow the message in the block. For example, if the key is already used on another domain, free a slot in your vibefox.net account and click Check now. If the site address changed, click Check now to activate the key for the new domain. If the license server cannot be reached, the plugin keeps working on the last known status.

Uninstall

Deactivating the plugin keeps all data. To remove it, deactivate and delete it on the Plugins page. The license key and license status of this plugin, the cached Pesapal access tokens and the registered notification IDs are always removed. The plugin settings and its logs (log files, including rotated ones, and database log entries of the source wcp_pesapal_pay) are removed only if Delete data was on. Otherwise they stay for a later re-install. Existing orders keep their payment notes, transaction IDs and Pesapal tracking IDs.

Pesapal is a trademark of its respective owner. This plugin is not affiliated with or endorsed by Pesapal.