VibeFox PayU 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, with the cURL extension.

Currency: the checkout currency of the customer must be 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 store: PayU sends payment notifications to your store, 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

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_payu_payment-oc3-(version).ocmod.zip and the OpenCart 4 package wcp_payu_payment.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_payu_payment-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 PayU Payment 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 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.

OpenCart 4

1. In the admin go to Extensions > Installer, click Upload and choose the file wcp_payu_payment.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 PayU Payment, click Install (the green + button), then Edit (the pencil button).

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

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

Configuration

All settings are on the extension page: Extensions > Extensions > Payments > VibeFox PayU Payment > Edit. The sections are listed on the left; the Save button under the list saves the whole page. Above the settings 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 (PayU is then not shown at checkout) and when PayU does not accept the default currency of the store (PayU is then hidden for orders in that currency). Without the right to modify the extension the page shows the settings but cannot save them.

When you save, spaces and line breaks are removed from all keys, because copying from the PayU panel often adds them. Title must not be empty or longer than 128 characters (the page shows Enter a title for the payment method (at most 128 characters).), Sort Order must be a whole number (negative numbers are allowed), Total must be a number, 0 or greater, and the geo zone and order statuses must exist. Otherwise nothing is saved. Saving the settings also clears the cached PayU access tokens.

PayU

Enable/Disable: Enable PayU payment gateway 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: PayU. Required, at most 128 characters.

Description: the text shown to the customer at the Confirm Order step, above the confirm button. Default: Pay securely via PayU.

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

Geo Zone: offer PayU 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 PayU is offered. Leave it empty to offer PayU for any total.

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. The section links to the PayU developer documentation.

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. at the Confirm Order step. 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, receiving or cancelling 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.

Order statuses

OpenCart creates the order at the Confirm Order step without a status (a missing order). The order gets a status only after PayU has confirmed the payment, by a signed notification or by the status check when the customer returns. OpenCart has no On hold status: the waiting statuses default to Pending, and the PayU tab of the order and its notes explain why. Each field below lists your OpenCart order statuses; you can create your own statuses in System > Localisation > Order Statuses.

Order Status After Payment: set when PayU confirms the payment (COMPLETED) and the amount and currency match. Default: Processing.

Awaiting PayU Payment Confirmation: the payment is authorized and waits to be received (automatic receiving off or failed). Use Receive PayU payment or Cancel PayU payment in the PayU tab of the order. Default: Pending.

PayU Payment On Hold: the paid amount or currency does not match the order, or a payment was completed for a cancelled order. The order is not marked as paid; the note says why. Default: Pending.

Payment Error Status: the payment of an order waiting for confirmation was cancelled or rejected. Default: Failed.

Cancelled Order Status: a PayU payment completed for an order in this status puts the order on hold instead of reopening it silently. The extension never sets this status. Default: Canceled.

Refunded Status: set after the payment is fully refunded from the PayU tab of the order. Default: Refunded.

Payment notifications

Notification URL: shows the address PayU sends notifications to. On OpenCart 3 it looks like https://your-store/index.php?route=extension/payment/wcp_payu_payment/notify, on OpenCart 4 like https://your-store/index.php?route=extension/wcp_payu_payment/payment/wcp_payu_payment.notify. It is built from the storefront address of your OpenCart installation. The extension 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 store is in maintenance mode (on OpenCart 4 through the startup action of the extension, which also lets the customer return from PayU). Notifications without a valid signature are rejected.

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 extension receives such payments at once and the order gets its paid status when PayU reports the payment as completed. When it is off, or receiving fails, the order gets Awaiting PayU Payment Confirmation and you receive or cancel the payment with the buttons in the PayU tab of the order. Default: on.

Logging: writes technical events (order numbers, PayU order IDs, statuses, errors, no keys or personal data) to wc_pu_debug.log.php in the OpenCart logs folder (storage/logs). 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: when on, uninstalling the extension removes the gateway settings and the log. Orders and their payment data (PayU transactions, refunds) are never deleted. Cached PayU access tokens are always removed. Default: off.

Import / Export

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

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

Checkout

At the Payment Method step the customer chooses the payment method (by default PayU). At the Confirm Order step the customer sees your description and the note You will be redirected to PayU to complete the payment (BLIK, bank transfer, card and other methods). 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 PayU order for the order total in the order currency, with the description Order #, the order number and your store name, and with the products, the shipping method and the other order total lines for display on the PayU page. The customer's e-mail, name and phone are passed to PayU, and the PayU page language follows the storefront language. The customer is sent to the PayU page, chooses a method there and pays.

Each attempt gets its own PayU order. When the customer tries again (OpenCart 3 creates a new order every time the Confirm Order step is shown, OpenCart 4 updates the order of the checkout), the unfinished PayU payments of the previous attempts of the same order and cart are cancelled at PayU, so an old payment link cannot be paid twice. If a previous payment turns out to be paid already, it is applied instead, and an order or cart that is already paid, on hold or waiting for confirmation goes straight to the success page without a second payment. A change of the cart, including a new quantity, counts as a new cart that needs its own payment.

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 (at most once every 10 seconds per payment). The amount and currency must match. The order then gets its status the standard OpenCart way, with the usual order e-mails and stock update. The extension handles these PayU statuses:

After a confirmed payment the customer sees the OpenCart order success 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. When such an order is later paid or its payment fails, OpenCart notifies the customer of the new status. If the payment of the order failed, 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 (back to checkout) and Check again. The notification sets the order status 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. On OpenCart 4 this message is shown above the checkout page.

OpenCart 4 keeps the order in the checkout until the success page is shown. If that order was closed meanwhile (for example its payment waiting for confirmation was cancelled, or you cancelled or refunded it), the customer is sent back to the checkout with Your previous order was closed (not paid, cancelled or refunded). Please confirm the order again to pay with a new order. When the customer returns from PayU to an order closed without a payment, the message is The payment was not completed. You can try again or choose another payment method. If that order was already paid for an earlier cart and the cart has changed since, the customer is taken back to the checkout. In each case the next Confirm Order pays a new order of the current cart. A closed order is never shown as paid.

If PayU cannot start the payment, the customer stays at the Confirm Order step 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.

The customer chooses the payment method on the PayU page, not in your checkout. The extension has no card form on your site, 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 status (missing order): the customer was sent to PayU and has not paid, the payment was cancelled, or PayU 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): the payment was confirmed. A note shows the PayU order ID, the amount and the environment (sandbox or live).

Awaiting PayU Payment Confirmation (default Pending): the payment is authorized and waits for you (automatic receiving off, or receiving failed).

PayU Payment On Hold (default Pending): the paid amount or currency did not match the order, a payment waiting for confirmation had another amount, or a payment was completed for an order that had been cancelled. The note says which one. Check the order and fulfil it or refund the payment.

Payment Error Status (default Failed): the payment of an order waiting for confirmation was cancelled or rejected.

Refunded Status (default Refunded): the payment was fully refunded through the extension.

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, or for another order of a cart that is already paid, a note on the paid order 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.

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

VibeFox PayU Payment tab

In Sales > Orders open an order paid with PayU. At the bottom of the order page, next to History and Additional, the VibeFox PayU Payment tab shows the PayU order ID with a Sandbox label for sandbox payments, the extOrderId, the PayU status, the Payment amount, the amounts Paid / refunded, the refund form, the Refunds history, the PayU payment attempts of the order and the PayU notes. The tab is shown to users who have access to the extension; its actions need the right to modify the extension (set in System > Users > User Groups).

Payments waiting for confirmation

For an order with a payment waiting for confirmation, the tab shows Receive PayU payment and Cancel PayU payment. 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 user name, and the new PayU status is applied right away: a received payment sets Order Status After Payment, a cancelled one Payment Error Status.

Refunds

In the tab enter the Amount (the amount not refunded yet is filled in), optionally a Reason (optional), and click Refund via PayU. Confirm the question Refund this amount through PayU? This cannot be undone. Full and partial refunds are supported. Refunds are available once PayU has completed the payment. 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 tab shows PayU's error and no refund is recorded. A full refund sets the order to Refunded Status, without notifying the customer and without returning products to stock. A partial refund does not change the status.

Refunds are asynchronous at PayU. The extension 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.

Product returns in Sales > Returns do not send money back through PayU.

License key

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

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

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 customer's currency is one of the supported currencies, that the payment address is in the selected Geo Zone and that the order reaches the Total set in the settings. The settings page shows a warning when keys are missing or the store currency is not supported.

The payment went through, but the order stays without a status: 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 store, for example another store on the same POS. PayU stops retrying.

Notification answers Busy, retry later: the cart was being confirmed by another request at the same moment. 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 after Confirm Order: turn on Logging and look at the Log field on the extension 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. This payment method is not available. means the checkout session no longer matches the order or the payment method was turned off meanwhile: the customer reloads the checkout.

The order is in PayU Payment On Hold: read the notes in the VibeFox PayU Payment tab (see Order statuses), then fulfil the order or refund the payment.

The order is in 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 tab.

Refund fails or there is no refund form: the tab says why. Refunds are available once PayU has completed the payment. 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. Without the right to modify the extension the tab shows You do not have permission to refund (modify this extension).

Uninstall

Go to Extensions > Extensions, choose the type Payments and click Uninstall (the red − button) next to VibeFox PayU Payment. 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 and the cached PayU access tokens are 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 on uninstall is on, the other gateway settings (title, description, test mode, keys, automatic receiving, logging) and the log are removed. If it is off, they are kept for a later re-install. The PayU transactions and refunds are always kept, so orders paid before can still be refunded after a re-install. Existing orders keep their payment notes.

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 PayU Payment in the list of installed extensions, then Delete (the red bin button) to remove the uploaded package.

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