VibeFox PayU 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: one of PLN, EUR, CZK, HUF, RON, BGN, GBP, USD, CHF, DKK, NOK, SEK, UAH. The currency must also be enabled for your point of sale at PayU. For other currencies the payment option is hidden at checkout.

Internet access to your shop: PayU sends payment notifications to your shop, so it must be reachable from the internet (not behind HTTP authentication or a firewall). Without notifications, payments are still checked when the customer returns from PayU.

PayU account: you need four keys of your point of sale (POS): POS ID, Second key (MD5), OAuth client_id and OAuth client_secret. They are in the PayU merchant panel under Online payments > My shops > your shop > Points of sale (POS) > your POS > Configuration keys. Sandbox keys come from a separate PayU sandbox account.

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 PayU Payment 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 four Sandbox keys and the four Live keys (see Configuration). No notification URL has to be configured in PayU.

5. Turn on Enable/Disable and click Save. Leave Test Mode on until you have made a test payment, then turn it off to accept real payments with the Live keys.

On install the module creates two order statuses, Awaiting PayU payment confirmation and PayU 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 PayU Payment > Configure. Each section has its own Save button, which saves the whole page. Above the fields the page warns you while sandbox mode is on (Sandbox (test) mode is on: payments go to the PayU sandbox and no real money is charged. Do not ship orders paid in test mode.), when one of the four keys of the current mode is missing and when PayU does not accept the default shop currency. In the last two cases PayU is not shown at checkout.

When you save, spaces and line breaks are removed from all keys, because copying from the PayU panel often adds them. An empty Title is not saved: the page shows Enter a title for the payment method.

PayU

Enable/Disable: Enable PayU payment gateway turns the payment option on or off. Default: off.

Title: the payment method title displayed to the customer. It is also the payment method name stored in the order. Default: PayU. Required.

Description: the payment method description displayed to the customer at checkout. Default: Pay securely via PayU.

API credentials

Find the keys in the PayU merchant panel: Online payments > My shops > your shop > Points of sale (POS) > your POS > Configuration keys. Sandbox keys come from a separate PayU sandbox account. All four keys of a mode must be filled in.

Test Mode: uses the PayU sandbox and the Sandbox keys below. No real money is charged. While it is on, customers see Sandbox mode: no real payment is taken. under the payment option. Turn it off to accept real payments with the Live keys. Default: on.

Live POS ID: the POS ID (merchantPosId) of your production point of sale.

Live Second Key (MD5): used to verify the signature of PayU notifications.

Live OAuth Client ID: the OAuth client_id of the point of sale.

Live OAuth Client Secret: the OAuth client_secret of the point of sale.

Sandbox POS ID: the POS ID of your PayU sandbox point of sale.

Sandbox Second Key (MD5): used to verify the signature of PayU sandbox notifications.

Sandbox OAuth Client ID: the OAuth client_id of the sandbox point of sale.

Sandbox OAuth Client Secret: the OAuth client_secret of the sandbox point of sale.

Saved Second Keys and client 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. The POS IDs and client IDs are shown as saved.

Clear saved secrets: tick a secret and click Save to remove it. An empty field keeps the saved value.

Every payment remembers its environment. Notifications, status checks and refunds of a payment always use the keys of that environment, so older payments keep working after you switch modes. A notification signed with the sandbox key is never accepted for a live payment, and the other way round.

Payment notifications

Notification URL: shows the address PayU sends notifications to. With friendly URLs it looks like https://your-shop/module/wcp_payu_payment/webhook, possibly with a language code. The module sends it to PayU with every payment, so nothing has to be configured in the PayU panel. Make sure it is reachable from the internet (not blocked by a firewall or HTTP authentication). Notifications also work while the shop is in maintenance mode and are not blocked by the country restriction of your shop.

Advanced

Receive payments automatically: automatically receive payments waiting for confirmation. This only matters if automatic receiving is switched off for your POS in the PayU panel: payments then wait for confirmation (WAITING_FOR_CONFIRMATION). When this option is on, the module receives such payments at once and the order is created when PayU reports the payment as completed. When it is off, or receiving fails, the order is created in Awaiting PayU payment confirmation and you receive or cancel the payment with the buttons in the PayU block of the order. Default: on.

Logging: writes technical events (cart and order numbers, PayU order IDs, statuses, errors, no keys or personal data) to logs/wc_pu_debug.log.php in the module folder. The file cannot be opened from the web. Errors are always logged; the other events only while this is on. Default: off.

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

Delete data on uninstall: deletes the module settings and logs when the module is uninstalled. Orders and their payment data (PayU transactions, refunds, order statuses) are never deleted. Default: off.

Checkout

At the payment step the customer chooses the payment option (by default PayU) and sees the description and the note You will be redirected to PayU to complete the payment (BLIK, bank transfer, card and other methods). After confirming, the module creates a PayU order for the cart total in the cart currency, with the description Cart #, the cart number and your shop name, and with the products, shipping and gift wrapping for display on the PayU page. The customer's e-mail, name and phone are passed to PayU. The PayU page language follows the shop language when PayU supports it, otherwise English. The customer is sent to the PayU page, chooses a method there and pays. No order exists yet at this point.

Each payment attempt gets its own PayU order. When the customer tries again, the previous unfinished PayU payment of the cart is cancelled at PayU, so an old payment link cannot be paid twice. If the previous payment turns out to be paid already, the order is created instead of a new payment.

The return to your shop alone never pays an order. The order is marked paid only after PayU confirms it: by a notification signed with the Second Key of the payment's environment, or by a status check of the PayU order on the server when the customer comes back (at most once every 10 seconds per cart). The PayU order must be one created for this cart, and the amount and currency must match. The module handles these PayU statuses:

After a confirmed payment the customer sees the standard order confirmation page. For an order waiting for confirmation or on hold the page adds Your payment is being verified. We will send you an e-mail as soon as it is confirmed. If the payment of such an order is later cancelled, the page shows Your PayU payment was not completed. Please contact us about this order.

If PayU has not confirmed the payment yet when the customer comes back, a Payment confirmation page shows We have not received the payment confirmation from PayU yet. If the payment was interrupted, you can try again: (or, when PayU reported an error, The payment was not completed. You can try again:) with the buttons Pay again and Check again. The notification creates the order as soon as it arrives. If the payment was cancelled, the customer is back at checkout with The payment was not completed. You can try again or choose another payment method. The cart is kept.

If PayU cannot start the payment, the customer stays at checkout with Payment error. Please try again or choose another payment method. The technical reason is written to the log. If the keys of the current mode are missing, the message is Payment gateway is not configured properly. Please contact the administrator.

If a voucher in the cart stops being valid between the payment and its confirmation, it is removed from the order. The order then goes to PayU payment on hold with a note naming the voucher, because the customer paid the price with the discount.

The customer chooses the payment method on the PayU page, not in your checkout. The module has no card form in your shop, no saved cards or one-click payments, no subscriptions and no PayU installment or credit widgets. It uses one point of sale per environment.

Orders and refunds

Order statuses

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

Payment accepted: the payment was confirmed. The payment is recorded with the PayU order ID as the transaction ID, and a note shows the PayU order ID, the amount and the environment (sandbox or live).

Awaiting PayU payment confirmation: the payment is authorized and waits for you (automatic receiving off, or receiving failed). No payment is recorded yet.

PayU payment on hold: the paid amount or currency did not match the cart (the order is not marked paid), a voucher was removed, a payment waiting for confirmation had another amount, or a payment was completed for an order that had been cancelled (the payment is recorded). The note says which one. Check the order and fulfil it or refund the payment.

Payment error: the payment of an order waiting for confirmation was cancelled or rejected.

Refunded: the payment was fully refunded through the module.

Every notification is processed once: repeated notifications do not add notes or change the order again. If another payment is completed for an order that is already paid or refunded, a note asks you to refund it in the PayU panel. A payment waiting for confirmation on an order that is already paid or closed is cancelled automatically, so the money is not taken twice.

PayU payment block

The order page shows a PayU payment block with the PayU order ID, the extOrderId, the PayU status, the amount paid and refunded, a Sandbox badge for sandbox payments, the refund history and the PayU notes of the order. The actions of the block need the right to edit orders; access to the Modules pages is not needed.

Payments waiting for confirmation

For an order with a payment waiting for confirmation, the block shows Receive PayU payment (waiting for confirmation) and Cancel PayU payment (release the funds). After you confirm the question, the action is sent to PayU with the keys of the payment's environment, added to the notes with your name, and the new PayU status is applied right away: a received payment sets the order to Payment accepted, a cancelled one to Payment error.

Refunds

In the PayU payment block enter the amount (the amount not refunded yet is filled in), optionally a reason, and click Refund via PayU. Confirm the question Refund this amount through PayU? This cannot be undone. Full and partial refunds are supported. The refund is sent for the PayU order that was actually paid, with the keys of the environment of the payment, so those keys must be set. Refunds are made in the amount and currency PayU charged, so after an amount or currency mismatch you can refund up to what the customer actually paid, not the order total. The reason is sent as the refund description. If PayU rejects the refund, the block shows PayU's error and no refund is recorded. A full refund sets the order to Refunded. A partial refund does not change the status.

Refunds are asynchronous at PayU. The module adds a note with the PayU refund ID and status at once; the final status arrives later as a PayU notification and is added to the notes and the refund history. If PayU cancels a refund, the note says that the money was not returned to the customer, and the amount can be refunded again.

The module does not create credit slips. The standard PrestaShop refund buttons of the order page do not send money back through PayU.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox PayU Payment is the first block on Modules > Module Manager > VibeFox PayU Payment > 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-payu 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, PayU 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 by the notifications, and refunds work.

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

PayU does not appear at checkout: check that the license is active, Enable/Disable is on and all four keys of the current mode are filled in: the Sandbox keys in sandbox mode, the Live keys in live mode. Check that the cart currency is one of the supported currencies. In Payment > Preferences check that the module is allowed for the cart currency, the customer's country and the customer's group. The settings page shows a warning when keys are missing or the shop currency is not supported.

The payment went through, but no order was created: PayU has not delivered the notification yet, and the status check on the return page did not see a completed payment. Check that the notification URL shown in the settings is reachable from the internet. Turn on Logging to see what arrives. The customer can also click Check again on the Payment confirmation page.

Notification answers Invalid signature: the notification was not signed with the Second Key of either environment. Check Live Second Key (MD5) and Sandbox Second Key (MD5). The answer Invalid signature for this payment means the notification was signed with the key of the other environment than the payment.

Notification answers Ignored: unknown PayU order: the PayU order was not created by this shop, for example another shop on the same POS. PayU stops retrying.

Notification answers Busy, retry later: the cart was being confirmed by another request at the same moment, or the order could not be created (for example, the module is disabled). PayU repeats the notification. Turn on Logging to see the reason.

The notification URL shows POST expected in the browser: this is normal. The URL accepts only notifications from PayU.

The customer sees Payment error when choosing PayU: turn on Logging and look at the Log field on the module page. The log shows the HTTP code and the PayU status. Could not authenticate with PayU (check the OAuth client ID / secret). means wrong OAuth keys of the current mode.

The order is PayU payment on hold: read the notes in the PayU payment block (see Order statuses), then fulfil the order or refund the payment.

The order is Awaiting PayU payment confirmation: automatic receiving is off for your POS and the payment waits for you. Use Receive PayU payment or Cancel PayU payment in the PayU block.

Refund fails: This order has no completed PayU payment. Cannot process refund. means PayU has not completed a payment for the order yet. A message that the Sandbox keys or Live keys are missing means the payment was made in that environment and its keys are not set. Enter them and try again.

Uninstall

Go to Modules > Module Manager, open the menu next to VibeFox PayU Payment and choose Uninstall. The license key and license status of this module are always removed. Cached PayU access tokens are always removed. If Delete data on uninstall is on, the module settings and the log are removed. If it is off, all settings are kept for a later re-install. The PayU transactions and refunds and the order statuses Awaiting PayU payment confirmation and PayU payment on hold are always kept, so orders paid before can still be refunded after a re-install. Existing orders keep their payment notes and transaction IDs.

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