VibeFox PayU for WooCommerce — Help

Requirements

WordPress: 5.8 or later.

WooCommerce: 7.0 or later, installed and active. The plugin refuses to activate without it; if WooCommerce is turned off later, the plugin does nothing and shows a notice in the admin area.

PHP: 8.0 or later.

Store 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 method is hidden at checkout.

Internet access to your site: PayU sends payment notifications to your store, so the site must be reachable from the internet (not behind HTTP authentication or a maintenance page). Without notifications, orders 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 WordPress go to Plugins > Add New > Upload Plugin, choose the plugin ZIP file and click Install Now. You can also upload the wcp_payu_payment folder to /wp-content/plugins/ by FTP.

2. Click Activate.

3. Open the settings: WooCommerce > Settings > Payments > PayU > 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 four Sandbox keys and the four Live keys (see Configuration). No notification URL has to be configured in PayU.

6. Turn on Enable/Disable. Leave Test Mode on until you have made a test payment, then untick it to accept real payments with the Live keys.

Configuration

All settings are on one page: WooCommerce > Settings > Payments > PayU. Above the fields the page warns you while sandbox mode is on, when one of the four keys of the current mode is missing and when PayU does not accept the store 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.

General

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

Title: the payment method title displayed to the customer. Default: PayU.

Description: the payment method description displayed to the customer. 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: Enable sandbox (test) mode. Uses the PayU sandbox and the Sandbox keys below. No real money is charged. On the classic checkout and the Checkout block the customer sees Sandbox mode — no real money is charged. 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.

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. A notification signed with the sandbox key is never accepted for a live payment.

Payment notifications

This section shows the notification URL, which looks like https://your-site/wc-api/wc_pu_payment/. The plugin 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, maintenance mode or HTTP authentication).

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 plugin receives such payments at once. When it is off, such orders are put on hold and you receive or cancel the payment with the order actions Receive PayU payment and Cancel PayU payment. Default: on.

Logging: Enable logging writes technical events (order numbers, PayU order IDs, statuses, errors, no keys or personal data) to WooCommerce > Status > Logs, source wcp_payu_payment. Default: off.

Delete data on uninstall: Delete the plugin settings and logs when the plugin is deleted. Orders and their payment data are never deleted. Deactivating the plugin keeps everything. Default: off.

Checkout

The customer chooses the payment method (by default PayU) and places the order. The plugin creates a PayU order for the order total in the order currency, with the description Order #, the order number and your store name, and with the order items, shipping and fees for display on the PayU page. The PayU page language follows the store language when PayU supports it, otherwise English. The customer is sent to the PayU payment page, chooses a method there and pays.

Each payment attempt gets its own PayU order. When the customer pays again (after a failed or cancelled payment, or from the Pay for order page), the previous unfinished PayU payment of the order is cancelled at PayU, so an old payment link cannot be paid twice.

The return to your store 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 (useful if a notification is delayed). The PayU order must be one created for this order, and the amount and currency must match. The plugin handles these PayU statuses:

On the order received page, while the order is still Pending payment, the customer sees We have not received the payment confirmation from PayU yet. If the payment was interrupted, you can try again: or, after a failed payment, The payment was not completed. You can try again:, each with a Pay again button. For an order on hold the message is Your payment is being verified. We will send you an e-mail as soon as it is confirmed.

If PayU cannot start the payment, the customer sees Payment error. Please try again or choose another payment method. The technical reason (HTTP code and PayU status) is written to the log and to an order note PayU payment could not be started:. If the keys of the current mode are missing, the message is Payment gateway is not configured properly. Please contact the administrator.

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 customer chooses the payment method on the PayU page, not in your checkout. The plugin has no card form in your store, no saved cards or one-click payments, no subscriptions and no PayU installment or credit widgets. It uses one point of sale per environment (no point of sale per currency).

Orders and refunds

Order statuses

Pending payment: the customer was sent to PayU and has not paid yet. The order note shows the PayU order ID and the environment (sandbox or live).

Processing: the payment was confirmed. The order note shows the PayU order ID, the amount and the environment. The transaction ID is the PayU order ID that was paid. Orders with only virtual downloadable products become Completed, as WooCommerce does by default.

On hold: the paid amount or currency did not match the order, a payment was completed for an order that had been cancelled, or a payment waits for your confirmation (automatic receiving off, or receiving failed). The order note says which one and what to do.

Failed: the latest PayU payment was cancelled or rejected. The customer can pay again.

Every notification is processed once, under a per-order lock: repeated notifications do not add notes, reduce stock or send e-mails twice. 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.

Payments waiting for confirmation

For an unpaid order with a payment waiting for confirmation, the order screen offers two order actions: Receive PayU payment (waiting for confirmation) and Cancel PayU payment (release the funds). Choose one and click the update button. The action is added to the order notes with your user name, and the new PayU status is applied right away.

Refunds

Open the order, click Refund, enter the amount and click Refund via PayU (the button shows your Title). 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. The refund reason is sent as the refund description. If PayU rejects the refund, WooCommerce shows PayU's error and no refund is recorded.

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

Orders put on hold because of an amount or currency mismatch keep the PayU order ID as their transaction ID, so the payment can be refunded from WooCommerce as well as in the PayU panel.

License key

The plugin works with a VibeFox license key from vibefox.net. The license block is at the top of WooCommerce > Settings > Payments > PayU. 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, 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. 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, and refunds work.

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

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 store currency (or the order currency on the Pay for order page) is one of the supported currencies. The settings page shows a warning for each of these problems.

The payment went through, but the order stays Pending payment: 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.

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: the PayU order does not belong to an order of this store paid with PayU, for example another shop on the same POS. PayU stops retrying.

The payment is not created: turn on Logging and look at WooCommerce > Status > Logs, source wcp_payu_payment. 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 On hold: read the order note. The reason is an amount or currency mismatch, a payment after cancellation or a payment waiting for confirmation. For the last case use the order actions Receive PayU payment or Cancel PayU payment.

Refund fails: This order has no completed PayU payment. Cannot process refund. means the order has no paid PayU order. 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.

Other currencies: developers can change the currency list with the wc_pu_supported_currencies filter and the checkout icon with the wc_pu_icon filter.

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 settings; only cached PayU access tokens are dropped. To remove it, deactivate and delete it on the Plugins page. The license key and license status of this plugin are always removed, together with cached tokens. The gateway settings and the log of this plugin are removed only if Delete data on uninstall was on. Otherwise they stay for a later re-install. Existing orders keep their payment notes, PayU order IDs and transaction IDs.

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