VibeFox Pesapal for PrestaShop — Help

Requirements

PrestaShop: 8.0 to 9.x.

PHP: 8.0 or later. The module refuses to install on older PHP versions.

Currency: the cart must be in KES, UGX, TZS, ZMW, RWF or USD. In other currencies the payment method is hidden at checkout. The cart is charged in its own currency; the module 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 module registers its notification URL itself. Your shop 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 the back office go to Modules > Module Manager and click Upload a module. Choose the module ZIP file.

2. When the upload finishes, click Configure, or find VibeFox Pesapal Pay Gateway in the module list later and click Configure.

3. Paste your VibeFox license key into License key in the license block at the top of the Configure page and click Activate (see License key).

4. Enter the sandbox consumer key and secret, turn on Enable/Disable, click Save and make a test order.

5. Enter the live consumer key and secret, turn off Sandbox mode and click Save to accept real payments.

On install the module creates the order status Pesapal payment on hold. PrestaShop offers a new payment module for all currencies, countries and customer groups. You can limit them in Payment > Preferences.

Configuration

All settings are on the module page: Modules > Module Manager > VibeFox Pesapal Pay Gateway > Configure. Each section has its own Save button, which saves the whole page. Above the fields a badge shows the mode: SANDBOX — Test payments on cybqa.pesapal.com — no real money is charged. or LIVE — 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 the default currency of your shop.

Pesapal

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

Title: the payment method name customers see at checkout. It is also the payment method name stored in the order. Default: Pesapal (M-Pesa, Airtel Money, cards). Required: an empty title is not saved, the previous one is kept.

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.

Sandbox mode: Use the Pesapal sandbox (no real money). When on, new payments use cybqa.pesapal.com with the sandbox keys. Turn it off 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.

Saved keys and secrets are never shown again. The field stays empty and shows Saved — leave empty to keep it. Type a new value only to change it.

Clear saved consumer keys and secrets: tick it and click Save to remove all four saved keys and secrets.

Saving the settings drops the cached Pesapal access tokens. 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.

Payment notifications (IPN)

IPN URL: shows the notification URL of your shop. With friendly URLs it looks like https://your-shop/module/wcp_pesapal_pay/webhook, possibly with a language code such as /en/. 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 section 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 firewall or password protection in front of it. It keeps working while the shop is in maintenance mode and is not blocked by the country restriction of your shop.

Advanced

Debug log: Log Pesapal requests and notifications. Writes details to logs/pesapal_p_debug.log.php in the module folder. The file cannot be opened from the web. Errors and warnings are always logged, even when the switch is off. Keys, tokens and customer data are never logged. Default: off.

Log: shows the size and the latest entries of the log. Click Clear log to empty it.

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

Checkout

At the payment step the customer chooses the payment method (by default Pesapal (M-Pesa, Airtel Money, cards)) and sees its description. After confirming, the module creates a Pesapal payment request for the cart total in the cart currency, with the billing details of the invoice address, and sends the customer to the Pesapal payment page. The payment description sent to Pesapal is Cart, the cart number and the shop name. There the customer pays with one of the methods Pesapal offers, such as M-Pesa, Airtel Money, MTN, card or bank. No order exists yet at this point.

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 module 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 cart and that the paid amount and currency match the cart. The order is then created and the customer sees the standard order confirmation page.

Mobile money payments can take a moment. If Pesapal has not confirmed the payment yet when the customer comes back, a Payment confirmation 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. with the buttons Check again and Back to checkout. The notification from Pesapal creates the order as soon as the payment is confirmed. If the order was put on hold, the confirmation 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 are back at checkout 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 cart is kept and the customer can pay again. Every payment attempt of the cart is remembered, so a payment made later on an older Pesapal page of the cart is still accepted.

If Pesapal cannot start the payment, the customer stays at checkout with 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. The technical reason is written to the log. The order total must be greater than zero.

The module has no payment form on your own site (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

No order yet: the customer was sent to Pesapal and has not paid, the payment failed, or Pesapal has not confirmed the payment yet. Only the cart exists.

Payment accepted: Pesapal reports the payment as Completed and the amount and currency match. The payment is recorded with the Pesapal tracking ID as the transaction ID, and a note shows the amount, the payment method, the Pesapal confirmation code and the tracking ID. Each payment is applied once.

Pesapal payment on hold: the paid amount or currency differs from the cart (note Pesapal amount/currency mismatch — held for review), or money arrived for an order that had been cancelled. The amount actually paid is recorded on the order when it is in the order currency. Check the payment in the Pesapal dashboard, then complete the order or refund the payment.

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 a cart 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.

Pesapal payment block

The order page shows a Pesapal payment block with a Sandbox or Live badge, the tracking ID, the merchant reference, the Pesapal status, the payment method, the confirmation code, the requested and the paid amount, the reason for a review, all Payment attempts of the cart and the Payment notes of the order. The block is read only.

Refunds

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

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox Pesapal Pay Gateway is the first block on Modules > Module Manager > VibeFox Pesapal Pay Gateway > Configure, above the settings. Paste the key into License key and click Activate. After that the block shows the key masked, the status (for example the date the license is active until and your domain) and the buttons Check now to check the status again, Change key to enter another key and Remove key to remove the key from this shop. Below them are the line Product: presta-payment-pesapal and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only employees with the Configure permission for the module can change the key. The texts of the block follow the back office language (English and Russian are included).

If the key is not accepted, the block says why, for example Key not found, This key belongs to another product, Domain limit reached or License expired on a date. After the shop address changes, or after you free a domain slot in your account, click Check now. If the license server cannot be reached, the module keeps working on the last known status.

One key works on one domain: the domain of the main shop, also in a multistore setup. Removing the key from the shop 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. The PrestaShop storefront does not know that you are logged in to the back office, so the payment method is hidden for you too: you can set up the module before you buy a key, but not test it at checkout. A reminder appears in Modules > Module Manager on the Alerts tab. Existing orders are not affected: payments already started are still confirmed, and Pesapal notifications about existing payments, including reversals, are still applied.

When a license expires, the module keeps working, but updates and support need a renewal. The status is checked again automatically while you work in the back office: once a day for the first 14 days after the key is entered, then once a week. No cron job is needed. Uninstalling or resetting the module always removes the license key and license status.

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 cart currency is KES, UGX, TZS, ZMW, RWF or USD. The warnings at the top of the settings name the problem. In Payment > Preferences check that the module is allowed for the cart currency, the customer's country and the customer's group. Developers can change the list of currencies with the hook actionPesapalSupportedCurrencies.

The payment went through, but no order was created: the notification from Pesapal did not reach your shop and the customer did not come back. Check that the URL shown in IPN URL is reachable from the internet (no firewall or password protection in front of it). Turn on Debug log and look at the Log field on the module page.

How the shop answers notifications: a processed notification is answered with HTTP 200. When the module cannot process it, it answers with an error, and Pesapal sends the notification again later: 400 (missing or malformed tracking ID), 404 (no cart of this shop has this tracking ID), 409 (the transaction belongs to another merchant reference; nothing is changed), 502 (the Pesapal API could not be reached at that moment, or the keys of the mode the payment was started in are missing) and 503 (the cart was being updated by the customer return at the same moment, or the order could not be created, for example because the module is disabled).

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 log 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 log and try again.

Payments of an older mode are not confirmed after switching: a payment is checked with the keys of the mode it was started in. Keep the keys of that mode entered until its payments are confirmed.

Order is Pesapal payment on hold after payment: read the notes in the Pesapal payment block. The paid amount or currency differed from the cart, 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.

Uninstall

Go to Modules > Module Manager, open the menu next to VibeFox Pesapal Pay Gateway and choose Uninstall. The license key and license status of this module are always removed. The cached Pesapal access tokens and the registered notification IDs are always removed. If Delete data is on, the module settings and the log are removed too. If it is off, all settings are kept for a later re-install. The Pesapal payment attempts and the order status Pesapal payment on hold are always kept. Existing orders keep their payment notes, transaction IDs and Pesapal tracking IDs.

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