VibeFox Pesapal for Adobe Commerce — Hilfe

Requirements

Magento: Magento Open Source or Adobe Commerce 2.4.6 to 2.4.9, on your own server or hosting, on premises or on Adobe Commerce on cloud infrastructure. The module does not work with Adobe Commerce as a Cloud Service (the SaaS edition), which does not accept PHP modules.

PHP: 8.1 to 8.4.

Currency: the order currency must be 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 currency the customer sees; 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 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 module is one ZIP file. It is a Composer package and can also be copied into app/code. Run the commands in the Magento root folder as the user that owns the Magento files.

1. With Composer: put the ZIP file into a folder that your project uses as a Composer "artifact" repository and run composer require vibefox/module-pesapal-payment. Without Composer: unpack the ZIP file into app/code/Vibefox/PesapalPayment/, so that registration.php is directly in that folder.

2. Run bin/magento module:enable Vibefox_PesapalPayment and bin/magento setup:upgrade. In production mode also run bin/magento setup:di:compile and bin/magento setup:static-content:deploy, then bin/magento cache:flush.

3. In the Admin go to Stores > Configuration > Sales > Payment Methods and open Pesapal. When the Magento PayPal module is enabled, the group is listed under Other Payment Methods. Paste your VibeFox license key into License key in the license block, the first row of the group, and click Activate (see License key).

4. Enter the sandbox consumer key and secret, set Enable to Yes, click Save Config and place a test order. When you are ready, enter the live consumer key and secret, set Sandbox mode to No and click Save Config to accept real payments.

The module adds the Pesapal (M-Pesa, Airtel Money, cards) payment method to the Magento checkout. It is off after installation (Enable = No) and in sandbox mode. The module uses the standard Magento order states and creates no order statuses of its own. It creates its own tables for the payment attempts, their events and the registered notification IDs.

Configuration

All settings are in Stores > Configuration > Sales > Payment Methods > Pesapal, in the standard Magento configuration form. The settings can be changed for a website or a store view with the Scope switcher at the top of the page. The license block and Remove data on uninstall exist in the Default Config only. A payment uses the settings of the store view where the order was placed. Save Config saves the whole page and drops the cached Pesapal access tokens.

Wrong values do not stop the save. Magento saves the other fields, keeps the previous value of the wrong field and shows a warning: Pesapal: enter a payment title of 1 to 128 characters. Invalid title was kept unchanged; other fields were saved., Pesapal: sort order must be a whole number. Previous value was kept. or Pesapal: minimum and maximum amounts must be non-negative. Previous value was kept.

After Save Config, while Enable is Yes, Magento also shows Pesapal: enter the consumer key and secret of the active environment. The payment method is hidden until then. when a key of the current mode is missing, Pesapal does not support the default store currency with the currency code when the base currency is not one of the supported currencies, and Pesapal SANDBOX — no real payments will be processed. in sandbox mode. The payment method itself depends on the currency of the order, not on the base currency.

General

Enable: shows or hides Pesapal at checkout. It is shown only when the consumer key and secret of the current mode are set. Default: No.

Title: shown at checkout and stored in the order. Default: Pesapal (M-Pesa, Airtel Money, cards). Required, at most 128 characters.

Description: shown in the payment method list 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

Sandbox mode: when Yes, new payments use cybqa.pesapal.com with the sandbox keys and no real money is charged. Set it to No to accept real payments on pay.pesapal.com with the live keys. Default: Yes. While it is on, customers see SANDBOX — no real payments will be processed. under the payment method.

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 No.

Live consumer secret: the consumer secret from your Pesapal merchant dashboard. Used when Sandbox mode is No.

Magento stores the keys and secrets encrypted and shows only a mask (******) after saving. Leave the mask unchanged to keep the saved value, type a new value to change it. The value is saved exactly as entered, including quotes and backslashes; only spaces at the start and end are removed. To delete a saved value, clear the field and click Save Config.

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)

Notification registration: shows SANDBOX or LIVE and, for reference, the notification URL of the default store view. It looks like https://your-store/wcppesapalpay/checkout/notify/. The URL is registered with Pesapal automatically at the first payment, for each store view, mode, consumer key and URL, so there is nothing to configure. After the first payment the row shows Registered IPN ID with the ID Pesapal returned; before that it says Not registered yet. The URL must be reachable from the internet: no firewall or password protection in front of it. Notifications contain no signature or payment data. They only trigger an authenticated server-side status check.

Payment restrictions

Sort order: the position among the payment methods at checkout. A whole number. Default: 0.

Minimum order total: offer Pesapal only from this order total, in the base currency of your store. Enter 0 for no minimum. Default: 0.

Maximum order total: offer Pesapal only up to this order total, in the base currency. Enter 0 for no maximum. Default: 0. Use a dot as the decimal separator in both fields, for example 9.99. Any form of zero, such as 0.00, is saved as 0. An empty field or "9,99" is not accepted: the previous value is kept with a warning.

Payment from applicable countries: All Allowed Countries offers Pesapal for every country your store allows, Specific Countries only for the countries below.

Payment from specific countries: offer Pesapal only for billing addresses in these countries.

Advanced

Debug log: writes details to var/log/pesapal_p_debug.log.php in the Magento folder. The file cannot be opened from the web. Errors and warnings are always logged, even when this field is No. Keys, tokens and customer contact data are never logged. Default: No.

Remove data on uninstall: when Yes, uninstalling the module with its data also removes the settings and the log (see Uninstall). The payment attempt and event history is always preserved. Uninstalling with data always clears the access tokens and the notification IDs. Default: No.

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

Checkout

At the payment step the customer chooses the payment method (by default Pesapal (M-Pesa, Airtel Money, cards)) and sees the description and the note You will be redirected to Pesapal to complete your payment. After Place Order, Magento places the order in Pending Payment. No invoice is created and no order e-mail is sent yet. The module creates a Pesapal payment request for the order total in the order currency, with the billing details of the order, and sends the customer to the Pesapal payment page. The payment description sent to Pesapal contains 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.

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 order and that the paid amount and currency match the order. A notification is handled for any store view of the installation. Notifications and returns are handled even when Enable is No or the license is not active.

After a confirmed payment Magento creates the invoice with the Pesapal tracking ID as the transaction ID, the order moves to Processing and the order e-mail is sent. The customer sees the standard order success page. A customer who comes back in another browser lands on the home page with Your Pesapal payment has been confirmed.

Mobile money payments can take a moment. If Pesapal has not confirmed the payment yet when the customer comes back, a Pesapal payment confirmation page shows Your payment is being confirmed by Pesapal. There is no need to pay again. with the link Check again. The notification from Pesapal completes the order as soon as the payment is confirmed. If the payment needs a review, the page shows Your Pesapal payment was received and needs manual review. Contact the store; do not pay again. If it was reversed, the page shows Pesapal has reversed this payment. Contact the store if you need help.

If the customer cancels on the Pesapal page or the payment failed, the order is cancelled (the stock goes back), the cart is restored and the customer is back in the cart with Your Pesapal payment was not completed. You can try again or choose another method. A customer who comes back in another browser lands on the home page.

If Pesapal rejects the payment request or the payment cannot be started, for example because of wrong keys, the order is cancelled, the cart is restored and the customer sees Pesapal could not start the payment. Try again or choose another method. The order total must be greater than zero.

A new payment for the same cart is created only after the earlier attempts of the cart have been checked with Pesapal. While the same order waits for payment, the customer gets the same Pesapal page again. If an earlier payment is paid or needs a review, if Pesapal cannot be asked about it, or if the answer to a payment request was lost, no new payment is created, because Pesapal has no way to look up such a request. The customer sees Pesapal could not start or an earlier payment is uncertain. Contact the store before paying again. and the order stays in Pending Payment. A note on the order tells you to check the original Pesapal account.

Magento cancels orders that stay in Pending Payment longer than the Pending Payment Order Lifetime (Stores > Configuration > Sales > Sales > Orders Cron Settings). The module does not stop such a cancellation. Pesapal has no cancellation API, so the customer can still pay on the open Pesapal page. Such a payment does not reopen the order: it stays Canceled and a note asks you to check the stock and reconcile or refund the payment in Pesapal.

The module works with the standard Magento checkout. It has no payment form on your own site (the customer always pays on the Pesapal page), no saved cards, no subscriptions or recurring payments, no online refunds and no currency conversion. Pesapal is not offered for orders created in the Admin.

Orders and refunds

Order statuses

Pending Payment: the order was placed and the customer was sent to Pesapal, but Pesapal has not confirmed a payment yet. There is no invoice.

Processing: Pesapal reports the payment as Completed and the amount and currency match. The invoice is created 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.

On Hold: the paid amount or currency differs from the order, or the order total has changed. No invoice is created. The note says that the funds require a manual review and shows the amount received. Check the payment in the Pesapal dashboard, then process the order or refund the payment there.

Canceled: Pesapal reports the latest attempt of the order as Failed, the customer cancelled, the payment could not be started, or the order was cancelled in Magento. A cancelled order is never reopened automatically.

Closed: Pesapal reports the payment that paid the order as reversed, and the credit memo covers the rest of the invoice.

If a second payment attempt of a cart that is already paid is completed as well, the order is not changed and nothing is invoiced again. A note asks you to refund the second payment in the Pesapal dashboard. The notes are order comments that the customer does not see.

Pesapal payment information

On the admin order page (Sales > Orders > View) the payment information shows the payment method title and, when known, Pesapal tracking ID, Environment, Payment status and Funding tracking ID. The customer sees only the payment method title.

The Information tab of the order also has the section Pesapal payment history, with all attempts of the cart: Tracking ID / merchant reference, Environment, Pesapal status, Native handling, Requested / received, Payment method / confirmation and Review, followed by Pesapal order notes. It is read only and is shown also when Enable is No.

Refunds

The module does not send refunds to Pesapal, and there is no Refund button for online refunds on the credit memo. Refund the payment in the Pesapal dashboard. When Pesapal then reports the payment that paid the order as reversed and the amount still matches, the module creates a credit memo with Refund Offline for the amount not refunded yet. This only records money that has already been returned. Repeated notifications do not create a second credit memo. If you recorded the refund yourself before, with a credit memo and Refund Offline, only the rest is recorded.

A reversal of another attempt is only noted on the order. If the reported amount or currency of a reversed payment does not match, no credit memo is created and the attempt is marked for review. A partial refund that Pesapal does not report as reversed has to be recorded by you with Refund Offline.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — Pesapal is the first row of the Pesapal group in Stores > Configuration > Sales > Payment Methods, 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: magento-payment-pesapal and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only Admin users whose role allows the Payment Methods configuration section can change the key. The texts of the block follow the Admin interface locale (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 module keeps working on the last known status.

One key works on one domain: the domain of the default store view, also when the installation has several websites or stores. 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 order is cancelled, the cart is restored and the customer sees Pesapal could not start the payment. Try again or choose another method. The Magento storefront does not know that you are logged in to the Admin, 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 the System Messages of the Admin, with the links Enter the license key and Dismiss, which hides 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 module keeps working, but updates and support need a renewal. The status is checked again automatically: once a day for the first 14 days after the key is entered, then once a week, by the Magento cron and while you work in the Admin. Uninstalling the module with its data always removes the license key and license status.

Troubleshooting

Pesapal does not appear at checkout: check that the license is active and Enable is Yes for the website or store view, that 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 that the currency of the cart is KES, UGX, TZS, ZMW, RWF or USD. Check Payment from applicable countries and Payment from specific countries against the customer's billing address, and Minimum order total and Maximum order total. The order total must be greater than zero.

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 Notification registration is reachable from the internet (no firewall or password protection in front of it). Check that the keys of the mode the payment was started in are still entered. Turn on Debug log and look at the Log field. The Check again link on the page of the customer and every new notification check the status again.

How the store 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 (this store has no attempt with 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, the keys of the mode the payment was started in are missing, or the answer has no merchant reference) and 503 (the cart was being updated by another request at the same moment, or an error occurred while the order was being updated).

Notifications fail while the store is in maintenance mode: Magento maintenance mode closes the whole site, the notification and return URLs too. The order is confirmed by the next notification or return that reaches the store.

The customer is back in the cart with Pesapal could not start the payment: Pesapal rejected the consumer key or secret of the current mode, or the payment request, or the notification URL could not be registered. Sandbox keys work only with the sandbox, live keys only in live mode. Other causes: the module was disabled, the license is not active, or the country or order total is no longer allowed. The order of that attempt is cancelled. The log shows the Pesapal error.

The customer sees Pesapal could not start or an earlier payment is uncertain: an earlier attempt of the cart is paid or needs a review, Pesapal could not be asked about it, or the answer to a payment request was lost. Read the notes and Pesapal payment history of the order and check the payment in the original Pesapal account before the customer pays again. Retrying does not create a second payment.

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.

A payment was made but the order is On Hold or Canceled: the paid amount or currency did not match the order, or the payment arrived after the order had been cancelled, for example by the Pending Payment Order Lifetime cron. Read the notes and check the payment in the Pesapal dashboard.

There is no Refund button on the credit memo: this is normal. The module has no online refunds. Refund the payment in the Pesapal dashboard, then use Refund Offline if the module has not recorded the reversal itself.

For developers: the list of currencies can be changed with the Magento event pesapal_p_supported_currencies, and the payment request with pesapal_p_submit_order_payload. The currency, amount, reference and URLs of the request stay bound to the order.

The settings page or the checkout looks unchanged after installing or updating: run bin/magento setup:upgrade and bin/magento cache:flush; in production mode also setup:di:compile and setup:static-content:deploy.

Uninstall

Deleting the module code alone removes nothing from the database: the license key and the settings stay. To remove the data, uninstall the module with the Magento command:

Installed with Composer: run bin/magento module:uninstall --remove-data Vibefox_PesapalPayment. It removes the data and the code.

Installed in app/code: run bin/magento module:uninstall --non-composer Vibefox_PesapalPayment to remove the data, then bin/magento module:disable Vibefox_PesapalPayment, delete the folder app/code/Vibefox/PesapalPayment and run bin/magento setup:upgrade.

The license key and license status are always removed, and so are the cached Pesapal access tokens and the registered notification IDs. If Remove data on uninstall is Yes, the module settings and the log are removed too. If it is No, they are kept for a re-install. The Pesapal payment attempts and their events are always kept. Existing orders keep their invoices, payment notes and transaction IDs.

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