VibeFox PayU for Adobe Commerce — Ayuda

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, with the cURL and JSON extensions.

Currency: the order currency must be one of PLN, EUR, CZK, HUF, RON, BGN, GBP, USD, CHF, DKK, NOK, SEK, UAH. It 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.

Magento cron: the order e-mail of a paid order is sent by the Magento cron.

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 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-payu-payment. Without Composer: unpack the ZIP file into app/code/Vibefox/PayuPayment/, so that registration.php is directly in that folder.

2. Run bin/magento module:enable Vibefox_PayuPayment 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 VibeFox PayU Payment. 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 four Sandbox keys and the four Live keys (see Configuration). No notification URL has to be configured in PayU. Set Enable to Yes and click Save Config. Leave Test Mode on Yes until you have made a test payment, then set it to No to accept real payments with the Live keys.

The module adds the PayU payment method to the Magento checkout. It is off after installation (Enable = No). The module uses the standard Magento order states and creates no order statuses of its own. It creates three tables for the PayU payment attempts, refunds and processed events.

Configuration

All settings are in Stores > Configuration > Sales > Payment Methods > VibeFox PayU Payment, in the standard Magento configuration form. The fields form one list on the page; below they are grouped by purpose. Like other Magento settings, they can be changed for a website with the Scope switcher at the top of the page; Title and Description also for a store view. Delete data on uninstall is set and read in the Default Config only. Save Config saves the whole page.

If a value is wrong, Magento shows an error and nothing on the page is saved: an empty Title or a title longer than 128 characters (PayU: enter a title of 1 to 128 characters.); a Sort Order that is not a whole number (PayU: Sort Order must be a whole number.); a Minimum Order Total or Maximum Order Total that is empty, negative or not a number (PayU: order limits must be non-negative numbers.). Write amounts with a dot, for example 9.99.

The PayU information row at the top of the group shows a short note and the notification URL. While Enable is Yes in the Default Config, it also warns about the Default Config values: Sandbox mode: no real money is charged. while Test Mode is on, and Enter all four credentials of the selected environment. when one of the four keys of the current mode is missing. In that case PayU is not shown at checkout.

General

Enable: shows or hides PayU at checkout. It is shown only when all four keys of the current mode are set. Default: No.

Title: the payment method name customers see at checkout. It is also stored in the order. Default: PayU. Required, at most 128 characters.

Description: shown in the payment method list at checkout, when the customer selects the method. Default: Pay securely via PayU.

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

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. All whitespace is removed from the keys when you save, because copying from the PayU panel often adds it.

Test Mode: uses the PayU sandbox and the Sandbox keys below. No real money is charged. While it is on, customers see TEST MODE: no real money is charged. under the payment method. Set it to No to accept real payments with the Live keys. Default: Yes.

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.

Magento stores the Second Keys and client secrets encrypted and shows only a mask (******) after saving. Leave the mask as it is to keep the saved value, type a new value to change it. To delete a saved key, clear the field and click Save Config. The POS IDs and client IDs are shown as saved. Saving the settings also clears the cached PayU access tokens.

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

The PayU information row shows the storefront notification URL. It looks like https://your-store/wcppayupayment/checkout/webhook/. The module sends the notification URL of the order's store view to PayU with every payment, so nothing has to be configured in the PayU panel and no secret other than the Second Key is needed. Make sure the URL is reachable from the internet (not blocked by a firewall or HTTP authentication). A notification is accepted for an order of any store view, and the Second Key is read for the store view of that order. Enter the keys for the website of that store or in the Default Config.

Orders

Receive payments automatically: receive authorized payments automatically; the order is paid only after PayU confirms COMPLETED. 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 Yes, the module receives such payments at once. When it is No, or receiving fails, the payment waits for you: you receive or cancel it with the buttons on the order page, a note tells you so. In both cases the authorized order moves to Processing without an invoice. Default: Yes.

Conditions

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

Payment from Specific Countries: offer PayU only for billing addresses in these countries.

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

Maximum Order Total: offer PayU only up to this order total, in the base currency. Enter 0 for no maximum. Default: 0.

Advanced

Debug log: writes technical events (order numbers, PayU attempts, statuses) to var/log/wc_pu_debug.log.php in the Magento folder. The file cannot be opened from the web. Keys, tokens and e-mail addresses are masked. Warnings and errors are always logged; the other events only while this is Yes. Default: No.

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

Delete data on uninstall: when Yes, uninstalling the module with its data deletes the module settings and the log (see Uninstall). Payment, refund and event history is always preserved. Default: No.

Checkout

At the payment step the customer chooses the payment method (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 Place Order, Magento places the order in Pending Payment. No invoice is created and no order e-mail is sent yet. The module then creates a PayU order for the order total in the order currency, with the description Order #, the order number and the store name, and with the products and shipping for display on the PayU page. The customer's e-mail, name and phone are passed to PayU. The PayU page language follows the store locale when PayU supports it, otherwise English. The customer is sent to the PayU page, chooses a method there and pays.

Each payment attempt gets its own PayU order. When a new attempt starts for the same cart, the previous unfinished PayU payment of that cart is cancelled at PayU, so an old payment link cannot be paid twice. If the previous payment turns out to be paid already, that payment is confirmed instead of a new one. If a previous payment can be neither closed nor checked, the customer sees PayU could not close a previous payment. Please check its status before paying again.

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 cart). The PayU order must be one created for this order, and the amount and currency must match. The module handles these PayU statuses:

After confirmation Magento creates the invoice with the PayU order ID as the transaction ID, the order goes to Processing, and the Magento cron sends the order e-mail (the job runs every 10 minutes, if order e-mails are enabled in Magento). The customer who comes back sees the standard order success page.

If PayU has not confirmed the payment yet when the customer comes back, a PayU payment page shows Your PayU payment is being verified. Please do not pay again. We will send confirmation when PayU completes it. with the button Check again. The notification confirms the order as soon as it arrives. A payment that needs your attention shows Your PayU payment requires store review. Please do not pay again; contact the store. A customer who comes back in another browser sees We could not confirm this payment. Contact the store if your account was charged. The notification still confirms the order.

If PayU reports the latest attempt as cancelled or rejected, the order is cancelled (the stock goes back). When the customer comes back, the cart is restored and shows PayU payment was not completed. Please try again.

If the payment cannot be started, the order is cancelled, the cart is restored and the customer sees a short message in the cart: PayU could not start the payment. Please try again., or, when the conditions have changed since the order was placed, PayU is not configured. Please choose another payment method., PayU does not support this currency., PayU is unavailable for this order amount. or PayU is unavailable for this billing country. The technical reason is written to the log. An order with money already recorded at PayU is not cancelled this way.

When an order in Pending Payment is cancelled in Magento, by you or by the Magento cron after the Pending Payment Order Lifetime (Stores > Configuration > Sales > Sales > Orders Cron Settings), its open PayU payments are cancelled at PayU. A paid order is not cancelled. An order with an authorized payment is in Processing, so the cron does not cancel it. If PayU cannot cancel a payment, a warning is written to the log; check it in the PayU panel.

The customer chooses the payment method on the PayU page, not in your checkout. The module works with the standard Magento checkout. It has no card form in your store, no saved cards or one-click payments, no subscriptions, no PayU installment or credit widgets and no multiple-address checkout. It uses one point of sale per environment. PayU 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 PayU, but PayU has not confirmed the payment yet. There is no paid invoice.

Processing without an invoice: the payment is authorized (WAITING_FOR_CONFIRMATION) and waits to be received, by the module or by you. You can receive it with Receive PayU payment or with an invoice and Capture Online, or cancel it with Cancel PayU payment or the order Cancel button. When PayU reports COMPLETED, the paid invoice is created.

Processing: the payment was confirmed. The invoice is created 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).

On Hold after a mismatch: PayU reported a different amount or currency than the order total. No invoice is created. The note shows the amount received and the amount expected. A payment waiting for confirmation with another amount also puts the order on hold; it is not received automatically, so use Receive PayU payment or Cancel PayU payment after your review. After Unhold such an order is in Processing without an invoice, so the cron does not cancel it.

Payment Review: you started Capture Online from an invoice for a payment waiting for confirmation. The invoice stays open until PayU reports COMPLETED and is then paid. If PayU cancels the payment, the invoice and the order are cancelled.

Canceled: PayU cancelled or rejected the payment, the payment could not be started, or the order was cancelled in Magento. A payment that arrives after that does not reopen the order. A note asks you to review fulfilment or refund the money.

Closed: the payment was fully refunded with a credit memo.

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 the duplicate 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. A late cancellation does not change a payment that is already completed. The notes are order comments that the customer does not see.

PayU payment information

On the admin order page (Sales > Orders > View) the payment information shows the payment method title and, for a confirmed payment, PayU order ID, External order ID and Environment. The customer sees only the payment method title.

Below it the PayU payment history section lists all attempts of the cart with PayU order ID, External order ID, Environment, Status, Expected / charged and Native order, links to the invoices, Provider funds remaining and the refund table with Refund ID, Amount, Status and Native credit memo. The section also appears while the module is off (Enable = No) or has no active license. Its buttons follow the rights of the Admin role for invoices, order cancellation and credit memos.

Payments waiting for confirmation

For an order with a payment waiting for confirmation, the section shows Receive PayU payment and Cancel PayU payment. The action is sent to PayU with the keys of the payment's environment and added to the order notes, and the status is checked at once. A received payment is paid only when PayU reports COMPLETED. A cancelled payment cancels the order.

Refunds

Open the order, go to the Invoices tab, open the invoice and click Credit Memo. Choose the items and amounts to refund and click Refund. The money is sent back through PayU. Full and partial refunds are supported. A credit memo started from the order page instead of the invoice offers only Refund Offline, which does not send money back through PayU.

The refund is made in the order currency, up to the amount PayU charged minus the amounts already refunded, for the PayU order that was actually paid and with the keys of its environment, so those keys must be set. If PayU does not accept the refund or the answer is lost, Magento shows the error and the credit memo is not created. Repeating the same credit memo sends the same refund reference, so PayU does not refund twice. A full refund closes the order.

Refunds are asynchronous at PayU. The credit memo records the request PayU accepted, and a note shows the PayU refund ID and status. The final status arrives later as a PayU notification and is added to the notes and the refund table. If PayU cancels a refund, the note says that the money was not returned, the amount becomes available again, and the button Retry or resolve PayU refund repeats the refund without a second credit memo. Refunds made in the PayU panel are added to the notes when PayU notifies your store. The order and credit memos are not changed automatically; create a credit memo with Refund Offline if needed.

Money without an invoice: after a mismatch, or a payment on an order that had been cancelled or closed, there is no invoice to refund from. If the order has no invoices, the PayU payment history section shows a form with the amount (the remaining amount is filled in) and Reason, and the button Refund PayU review funds. The refund is made in the amount and currency PayU charged and is recorded only in the section and the notes, marked Review ledger only, without an invoice or credit memo. A duplicate payment is refunded in the PayU panel.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox PayU Payment is the first row of the VibeFox PayU Payment 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-payu 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, PayU 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 This payment method is not available. Please choose another one. 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 refunds work.

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

PayU does not appear at checkout: check that the license is active and Enable is Yes for the website of the store, and that 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 order currency is one of the supported currencies. Check Payment from Applicable Countries and Payment from Specific Countries against the customer's billing address, and Minimum Order Total and Maximum Order Total. An order with a total of 0 cannot be paid with PayU.

The payment went through, but the order stays Pending Payment: PayU has not delivered the notification yet, and the status check on return did not see a completed payment. Check that the notification URL is reachable from the internet and that the Second Key of the payment's environment is set for the website of the order's store or in the Default Config. Turn on Debug log to see more. The customer can also click Check again.

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

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 order was being confirmed by another request at the same moment, or an error occurred while the order was being updated. PayU repeats the notification. Errors are written to the log.

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

Notifications fail while the store is in maintenance mode: Magento maintenance mode closes the whole site, the notification URL too. PayU repeats the notification later, and the order is also confirmed when the customer returns.

The order e-mail does not arrive after payment: check that the Magento cron is running. The module sends the e-mail of a paid order from the cron job, not at the moment of the notification.

The customer is back in the cart with PayU could not start the payment: look at the Log field. 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. Also check that the currency is enabled for your POS. The order of that attempt is cancelled.

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

The order is Processing without an invoice, with the note PayU payment is authorized: automatic receiving is off for your POS, and the payment waits for you. Use Receive PayU payment or Cancel PayU payment in the PayU payment history section.

PayU: only a full waiting authorization can be received: there is no payment waiting for confirmation, or a partial invoice was attempted. The module receives only the full order total, and only while PayU reports WAITING_FOR_CONFIRMATION.

Refund fails: PayU charged another currency. Use the review refund form in the PayU history. means no PayU payment in the order currency is recorded for this order. PayU refund exceeds the remaining provider funds. means the amount is more than what is left of the PayU payment. PayU: original payment environment credentials are missing. means the payment was made in the other environment and its keys are not set; enter them and try again. PayU did not accept the refund. Check the PayU panel. and PayU refund could not be confirmed. Retry the same operation or check PayU before creating another refund. mean that PayU refused the refund or the answer was lost. Repeat the same operation or check the PayU panel first.

The Refund button is missing on the credit memo: start the credit memo from the invoice (Invoices tab), not from the order page. An order without an invoice is refunded with Refund PayU review funds (see Refunds).

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.

For developers: the event wc_pu_order_request can add optional fields to the PayU order. The notification and return URLs, the amount, the currency and the extOrderId cannot be changed by it.

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_PayuPayment. It removes the data and the code.

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

The license key and license status are always removed, and so are the cached PayU access tokens. If Delete 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 PayU transactions, refunds and events are always kept, so orders paid before can still be refunded after a re-install. Existing orders keep their invoices, payment notes and transaction IDs.

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