VibeFox Pesapal for OpenCart — Help

Requirements

OpenCart: 3.0.x (tested on 3.0.5.0) or 4.0.2 and later (tested on 4.1.0.3).

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 extension 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 extension registers its notification URL itself. Your store 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

The download is one zip file with the packages for both OpenCart versions. Unpack it on your computer. It contains README.txt, the OpenCart 3 package wcp_pesapal_pay-oc3-(version).ocmod.zip and the OpenCart 4 package wcp_pesapal_pay.ocmod.zip. Install only the package for your OpenCart version. The license key is the same for both versions.

OpenCart 3

1. In the admin go to Extensions > Installer, click Upload and choose the file wcp_pesapal_pay-oc3-(version).ocmod.zip. The extension has no OCMOD modifications, so Extensions > Modifications does not need a refresh. Instead of the installer you can copy the contents of the upload folder of this package into the root folder of your store.

2. Go to Extensions > Extensions and choose the type Payments. Find VibeFox Pesapal Pay Gateway and click Install (the green + button). Your admin user needs the right to modify the payment extensions list.

3. Click Edit (the pencil button) to open the settings page. Paste your VibeFox license key into License key in the license block at the top of the 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.

OpenCart 4

1. In the admin go to Extensions > Installer, click Upload and choose the file wcp_pesapal_pay.ocmod.zip. Do not rename the file: OpenCart 4 takes the extension code from the file name, and a renamed package does not work.

2. The package appears in the list of installed extensions on the same page. Click Install (the green + button) next to it.

3. Go to Extensions > Extensions and choose the type Payments. Find VibeFox Pesapal Pay Gateway, click Install (the green + button), then Edit (the pencil button).

4. Enter the license key and the Pesapal keys as in steps 3 to 5 for OpenCart 3. The settings page and its fields are the same in both versions. Only the IPN URL is different (see Payment notifications).

A new install starts with the payment method turned off and sandbox mode on.

Configuration

All settings are on the extension page: Extensions > Extensions > Payments > VibeFox Pesapal Pay Gateway > Edit. The sections are listed on the left; the Save button under the list saves the whole page. Above the settings 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 store. Without the right to modify the extension the page shows the settings but cannot save them.

When you save, an empty Title is not accepted: the previous title is kept with an error, and the other fields are saved. Sort Order must be a whole number (negative values are allowed), Total a number 0 or greater, and Geo Zone and the order statuses must exist; otherwise that field keeps its previous value with an error. Saving drops the cached Pesapal access tokens.

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, at most 128 characters.

Description: the text shown to the customer at the Confirm Order step, above the confirm button. Default: Pay securely with M-Pesa, Airtel Money, card or bank via Pesapal. You will be redirected to Pesapal to complete the payment.

Sort Order: the position of Pesapal among the payment methods at checkout. Leave it empty or enter a whole number.

Geo Zone: offer Pesapal only for payment addresses in the selected geo zone. Default: All zones. Geo zones are set up in System > Localisation > Geo Zones.

Total: the checkout total, in the default currency of the store, that an order must reach before Pesapal is offered. Leave it empty to offer Pesapal for any total.

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: shown when a key is saved. Tick it and click Save to remove all four saved keys and secrets.

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.

Order statuses

OpenCart creates the order at the Confirm Order step without a status (a missing order). The order gets a status only after Pesapal has reported the payment as Completed. Each field below lists your OpenCart order statuses.

Order Status After Payment: the status set when Pesapal confirms the payment. Default: Processing.

Pesapal Payment On Hold Status: payments whose amount or currency does not match the order, and payments received after a cancellation. A note explains why. Default: Pending, because OpenCart has no On hold status. You can create your own status in System > Localisation > Order Statuses and select it here.

Cancelled Order Status: a Pesapal payment that arrives for an order in this status (or in the refunded status) puts the order on hold instead of reopening it silently. Default: Canceled.

Refunded Status: set when Pesapal reports the payment of the order as reversed. Default: Refunded.

Payment notifications (IPN)

IPN URL: shows the notification URL of your store. On OpenCart 3 it looks like https://your-store/index.php?route=extension/payment/wcp_pesapal_pay/ipn, on OpenCart 4 like https://your-store/index.php?route=extension/wcp_pesapal_pay/payment/wcp_pesapal_pay.ipn. It is built from the storefront address of your OpenCart installation. The URL is registered with Pesapal automatically at the first payment, separately for sandbox and live and for each consumer key, 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 store is in maintenance mode, because OpenCart lets payment extension requests through (on OpenCart 4 the extension adds its own startup action for this, which also lets the customer return from Pesapal).

Advanced

Debug log: logs Pesapal requests and notifications to pesapal_p_debug.log.php in the OpenCart logs folder (storage/logs). The file cannot be opened from the web, and at 5 MB it is moved to pesapal_p_debug.old.log.php. 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 extension settings and logs when the extension is uninstalled. Pesapal data saved on orders (tracking IDs, notes) is payment history and is always kept. Disabling the extension never deletes anything. Default: off.

Import / Export

Export: Download JSON saves the settings as a JSON file. The consumer keys and secrets are not exported.

Import: paste previously exported JSON and click Import to restore the settings. The saved consumer keys and secrets are kept.

Checkout

At the Payment Method step the customer chooses the payment method (by default Pesapal (M-Pesa, Airtel Money, cards)). At the Confirm Order step the customer sees your description. OpenCart creates the order at this step, still without a status. On OpenCart 4 the customer picks the payment method with the Choose button of the payment method block, in the window Payment method options, and clicks Confirm Order at the bottom of the checkout page. When the customer clicks Confirm Order, the extension creates a Pesapal payment request for the order total in the order currency, with the billing details of the payment address (on OpenCart 4, when the checkout asks for no payment address, of the shipping address), and sends the customer to the Pesapal payment page. The payment description sent to Pesapal is Order, the order number and the store name. There the customer pays with one of the methods Pesapal offers, such as M-Pesa, Airtel Money, MTN, card or bank. A note on the order records the payment request.

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 extension 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. The order then gets its status the standard OpenCart way, with the usual order e-mails and stock update, and the customer sees the OpenCart order success 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 sets the order status as soon as the payment is confirmed. If the order was put on hold, the success page shows Your payment was received and is being reviewed by the store. You will receive an e-mail once the order is confirmed. When a payment later moves the order from the on hold status to the paid status, the customer is notified by e-mail.

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. and a note on the order gives the reason. The cart is kept and the customer can pay again. On OpenCart 4 these messages are shown above the checkout page. OpenCart 3 creates a new order every time the Confirm Order step is shown, OpenCart 4 updates the order of the checkout, so before a new payment the extension checks the earlier attempts of the cart with Pesapal: if one of them has been paid meanwhile, that order gets its status and the customer goes to the success page without paying twice. A payment made later on an older Pesapal page of the cart is still accepted. A change of the cart, including a new quantity, counts as a new cart that needs its own payment.

OpenCart 4 keeps the order in the checkout until the success page is shown. If that order was closed meanwhile (for example you cancelled it), or it was paid for an earlier cart and the cart has changed since, the customer is sent back to the checkout with the message Your previous order is already closed. Please confirm the order again: the cart will be paid with a new order. The next Confirm Order pays a new order. A closed order is never shown as paid.

If Pesapal cannot start the payment, the customer stays at the Confirm Order step with a short message above the button, 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 and to the order notes. The order total must be greater than zero.

The extension 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 status (missing order): the customer was sent to Pesapal and has not paid, the payment failed, or Pesapal has not confirmed the payment yet. In Sales > Orders such orders are shown only with the filter Order Status set to Missing Orders.

Order Status After Payment (default Processing): Pesapal reports the payment as Completed and the amount and currency match. 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 Status (default Pending): the paid amount or currency differs from the order (note Pesapal amount/currency mismatch — held for review), or money arrived for an order in the cancelled or refunded status. Check the payment in the Pesapal dashboard, then complete the order or refund the payment.

Refunded Status (default 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 of an order or cart that is already paid is completed as well, the order is not changed. A note on the paid order asks you to refund the second payment in the Pesapal dashboard. Cancelled and refunded orders are never reopened automatically.

Notes are entries in the order History that the customer does not see.

VibeFox Pesapal Pay Gateway tab

In Sales > Orders open an order paid with Pesapal. At the bottom of the order page, next to History and Additional, the VibeFox Pesapal Pay Gateway tab shows the tracking ID with a Sandbox or Live label, 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 order (when there is more than one) and the Payment notes. The tab is read only and is shown to users who have access to the extension.

Refunds

The extension does not send refunds to Pesapal. Refund the payment in the Pesapal dashboard, then record the refund in OpenCart manually. Product returns in Sales > Returns do not send money back through Pesapal.

License key

The extension works with a VibeFox license key from vibefox.net. The license block License — VibeFox Pesapal Pay Gateway is the first block on Extensions > Extensions > Payments > VibeFox Pesapal Pay Gateway > Edit, 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 store. Below them are the line Product: opencart-payment-pesapal and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only admin users with the Modify permission for the extension can change the key. The texts of the block follow the admin 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 store address changes, or after you free a domain slot in your account, click Check now. If the license server cannot be reached, the extension keeps working on the last known status.

One key works on one domain: the store address from the OpenCart configuration. Removing the key from the store 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. An admin user who is logged in to the admin in the same browser still sees the payment method in the store, marked (unlicensed — visible to admins only), so you can set up and test the extension before you buy a key. On OpenCart 4 this preview is not available: the store does not see the admin login, so without an active key the payment method is hidden for everybody. After you have opened the Edit page once, a reminder appears on the admin Dashboard. Close it with × to hide it for 7 days. 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 extension keeps working, but updates and support need a renewal. The status is checked again automatically when you open the admin Dashboard or the Edit page: once a day for the first 14 days after the key is entered, then once a week. No cron job is needed. Uninstalling the extension 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 order currency is KES, UGX, TZS, ZMW, RWF or USD. The warnings at the top of the settings name the problem. Also check that the payment address is in the selected Geo Zone and that the order reaches the Total set in the settings.

The payment went through, but the order stays without a status: the notification from Pesapal did not reach your store 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 extension page.

How the store answers notifications: a processed notification is answered with HTTP 200. When the extension 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; 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 order was being processed by the customer return at the same moment, or the order status could not be set).

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.

The customer sees This payment method is not available. Please reload the checkout page.: the checkout session no longer matches the order, or the payment method was turned off meanwhile. The customer reloads the checkout.

The customer sees We could not verify the Pesapal payment: the return link from Pesapal did not match an order of the store. If money was charged, find the payment in the Pesapal dashboard and check the order before the customer pays 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 in the on hold status after payment: read the notes in the VibeFox Pesapal Pay Gateway tab. 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.

For developers: the extension triggers the OpenCart events pesapal_p_supported_currencies (the list of currencies) and pesapal_p_submit_order_payload (the payment request before it is sent to Pesapal).

Uninstall

Go to Extensions > Extensions, choose the type Payments and click Uninstall (the red − button) next to VibeFox Pesapal Pay Gateway. The license key and license status of this extension are always removed. OpenCart always removes its own settings of the extension: Enable/Disable, Sort Order, Geo Zone, Total and the order statuses of the Order statuses section, which return to their defaults on a re-install. The OpenCart event of the extension, the cached Pesapal access tokens and the registered notification IDs are always removed too (on OpenCart 4 also its events and its startup action, which lets the notifications and the customer's return through in maintenance mode). If Delete data is on, the other settings (title, description, sandbox mode, keys, debug log switch) and the log are removed. If it is off, they are kept for a later re-install. The Pesapal payment attempts are always kept. Existing orders keep their payment notes and Pesapal tracking IDs.

On OpenCart 4, to remove the files of the extension as well, go to Extensions > Installer after the uninstall and click Uninstall (the orange − button) next to VibeFox Pesapal Pay Gateway in the list of installed extensions, then Delete (the red bin button) to remove the uploaded package.

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