VibeFox PayU India 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. The PayU verify and refund requests use the PHP cURL extension.

Currency: Indian Rupee (INR). PayU India charges in rupees only. The currency the customer sees at checkout (the order currency) must be INR; for other currencies the payment method is hidden. The base currency of the store can be different.

Phone number: PayU requires a phone number for every payment. Keep the phone field of the address required in your checkout.

PayU India account: you need the Merchant Key and Merchant Salt (v1) from PayU Dashboard > Payment Gateway > Key Salt Details. Switch the dashboard to Test Mode to see the test pair. Use Salt v1, not Salt v2.

Internet access to your store: needed for the webhook. Without it, orders are confirmed only when the customer returns from PayU.

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

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

2. Run bin/magento module:enable Vibefox_PayuIndiaPayment 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 India Payment Gateway. 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 Test Merchant Key and Salt and the Live Merchant Key and Salt, add the Webhook URL shown on the page in PayU Dashboard > Webhooks for successful and failed payments, set Enable to Yes and click Save Config. Test a payment in Test mode, then switch Mode to Live.

The module adds the PayU India 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, processed results and refund requests.

Configuration

All settings are in Stores > Configuration > Sales > Payment Methods > VibeFox PayU India Payment Gateway, in the standard Magento configuration form. 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. The license block, Delete data on uninstall and Log are on 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 India: enter a title of 1 to 128 characters.), a Sort Order that is not a whole number (PayU India: Sort Order must be a whole number.), or a Minimum Order Total or Maximum Order Total that is empty, not a number or negative (PayU India: order limits must be non-negative numbers.). Use a dot as the decimal separator, for example 9.99.

While Enable is Yes, the PayU India information row and a warning after Save Config show PayU India: enter the Merchant Key and Salt for the selected mode. when the key or salt of the selected mode is missing, and the row shows TEST MODE: no real money is charged. in Test mode. These messages check the Default Config values.

PayU India information

The first row after the license block repeats that PayU India charges in INR only and that a phone number is required, and shows two addresses. Copy the URLs exactly as the page shows them.

Return URL: looks like https://your-store/wcppayuindiapayment/checkout/back/. Each payment sends the return URL of the store view where the order was placed, so nothing has to be configured in PayU.

Webhook URL: the address of the default store view, also when you use a custom Admin URL. It looks like https://your-store/wcppayuindiapayment/webhook/index/. Recommended: it confirms payments even if the customer closes the browser before returning. Add it in PayU Dashboard > Webhooks for successful and failed payments. It must be reachable from the internet (no basic auth or firewall block). One webhook URL serves all store views: the order is found by its PayU transaction ID, whichever store view the request comes to.

The webhook carries the same signed result as the customer's return. Webhooks without a valid PayU hash are rejected.

General

Enable: shows or hides PayU India at checkout. It is shown only when the key and salt of the selected Mode are set. Default: No.

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

Description: shown in the payment method list at checkout. Default: Pay securely via Credit/Debit Card, NetBanking, UPI, or Wallets through PayU.

Mode and credentials

Copy the Merchant Key and Merchant Salt (v1) from PayU Dashboard > Payment Gateway > Key Salt Details. Switch the dashboard to Test Mode for the test pair. When you save, spaces and line breaks are removed from keys and salts, because a salt with a pasted space would make every PayU response fail the check.

Mode: which PayU environment new payments use.

Payments already started keep the mode they were started in: their results are checked and their refunds are sent with the key and salt of that mode, even after you switch the mode.

Live Merchant Key: your live PayU Merchant Key.

Live Merchant Salt (v1): your live PayU Merchant Salt (v1). It signs requests and verifies PayU responses. Keep it secret.

Test Merchant Key: your PayU test Merchant Key, used in Test mode only.

Test Merchant Salt (v1): your PayU test Merchant Salt (v1), used in Test mode only.

Magento stores the salts encrypted and shows only a mask (******) after saving. Leave the mask unchanged to keep the saved value, type a new value to change it. To delete a saved salt, clear the field and click Save Config.

Verification and log

Verify Payment: double-checks every successful result with the PayU verify_payment API. If the check is unavailable, the order is put on hold and the check is repeated on the next delivery of the result. Default: Yes.

Enable Logging: adds the other gateway events, such as every payment form and PayU API call, to var/log/payu_p_debug.log.php in the Magento folder. Errors and warnings are always logged. The file cannot be opened from the web. Over 5 MB it is moved to payu_p_debug.old.log.php and a new file is started. Keys, salts and e-mail addresses are masked. Default: No.

Conditions

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

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

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

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

Sort Order: the position among the payment methods at checkout. A whole number, it can be negative. Default: 0.

Advanced

Delete data on uninstall: when Yes, uninstalling the module with its data deletes the module settings, cache and logs (see Uninstall). Orders and the payment and refund history are always preserved. Default: No.

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

Checkout

At the payment step the customer chooses the payment method (by default PayU India) and sees the description and the note You will pay on the PayU India hosted checkout page. After Place Order, Magento places the order in Pending Payment. No invoice is created and no order e-mail is sent yet. The next page shows You are being redirected to PayU India. and sends a signed payment request for the order total in INR to the PayU hosted checkout. If the browser does not continue by itself, the customer clicks Continue to PayU India. On the PayU page the customer pays by card, NetBanking, UPI or wallet.

Every payment attempt gets its own PayU transaction ID that starts with the internal number of the order, stored with its amount and mode. The request also carries the product SKUs of the order as the product information (up to 100 characters), the customer's name, e-mail and address, and the phone as digits: the billing address phone is used first, then the shipping address phone.

PayU sends the result back with the customer and, if configured, by webhook. A result is accepted only with a valid PayU hash made with the key and salt of the mode in which the payment was started, and only for a transaction ID issued by your store. With Verify Payment on, a successful result is also checked with the PayU verify_payment API. The paid amount must equal the amount of the attempt and the order total to the paisa, in INR. The order is marked paid only after PayU confirms it this way. The module handles these PayU results:

After a successful payment Magento creates the invoice with the PayU transaction ID (mihpayid) as the transaction ID and the order moves to Processing. The customer sees the standard order success page. The order e-mail is sent by the cron job of the module, which runs every 20 minutes, if order e-mails are enabled in your store.

For a pending payment the customer sees Your PayU India payment is pending. The order will be updated when PayU confirms the result. Please do not pay again. with a Check again button. For an order under review the message is Your PayU India payment is being reviewed. The order requires store review. Please do not pay again; contact the store if needed. A customer who comes back in another browser sees We could not confirm the payment result. If your account was charged, contact the store before paying again.

After an unsuccessful payment the cart is restored and the customer is back in the cart with Payment was not completed. Please try again or choose another payment method. or, after cancelling on the PayU page, Payment was cancelled. You may try again.

If the payment cannot be started, the order is cancelled, the cart is restored and the customer sees the reason in the cart: PayU India requires a phone number. Please enter your phone number and try again., PayU India is not configured. Please choose another payment method., PayU India accepts Indian Rupees (INR) only., PayU India is unavailable for this billing country., PayU India is unavailable for this order amount. or PayU India could not start the payment. Please try again. An order that already has a pending or held payment does not get a new payment form, so the browser Back button cannot start a second payment.

Magento cancels orders that stay in Pending Payment longer than the Pending Payment Order Lifetime (Stores > Configuration > Sales > Sales > Orders Cron Settings). If a successful payment is reported later for a cancelled order, the order is not reopened.

The module works with the standard Magento (Luma) checkout. The module charges in INR only and has no multi-currency processing (MCP). It has no saved cards or tokenization, no subscriptions, no on-site (seamless) card form, no EMI or offer management and no PayU one-click checkout. PayU India is not offered for orders created in the Admin or for multiple-address checkout.

Orders and refunds

Order statuses

Pending Payment: the order was placed and the customer was sent to PayU, but no final result has arrived yet, or PayU reported the payment as pending. There is no invoice.

Processing: PayU confirmed the payment. The invoice is created with the PayU transaction ID, and a note says PayU India payment successful. Transaction ID: …, Mode: …, Bank: … with the amount and the environment.

On Hold: the paid amount or currency differs from the order, or the verify_payment API could not be reached, did not confirm the payment yet or does not match the signed result. No invoice is created. The note tells the reason. When only the verification was unavailable or not confirmed yet, the order is paid automatically on the next delivery of the result. Otherwise check the transaction in the PayU Dashboard.

Canceled: the payment failed or was cancelled on the PayU page, the payment could not be started, or the order was cancelled in Magento. If a successful payment arrives later, the order stays Canceled and a note asks you to review or refund it: PayU India payment … arrived for a closed or cancelled order. The order was not reopened. Review fulfillment or refund these held funds.

Closed: everything paid was refunded with credit memos. A repeated PayU result does not reopen the order.

A paid order is never changed by a later result. If PayU reports another successful payment for an order or a cart that is already paid, nothing is invoiced again and a note asks you to refund the duplicate in the PayU Dashboard. The notes are order comments that the customer does not see.

PayU India payment information

On the admin order page (Sales > Orders > View) the payment information shows the payment method title and, when known, PayU shop transaction ID, PayU transaction ID, PayU environment, PayU payment mode and PayU bank. The customer sees only the payment method title.

Below it, the section PayU India payment history lists each payment attempt: shop transaction ID, PayU transaction ID, environment, status, expected and reported amount, payment mode and bank. Under Refund requests it lists the amount, PayU request ID, status, credit memo and reason of each refund. The section is shown also when the module is disabled.

Refunds

Open the Invoices tab of the order, open the invoice, click Credit Memo, set the items or amounts and click Refund. Full and partial refunds are supported, up to the rest of what PayU charged. The refund is sent through the PayU refund API in INR with the key and salt of the mode the payment was made in, so those credentials must be set. A credit memo opened from the order page offers only Refund Offline, which sends no money. A full refund closes the order.

PayU queues refunds and completes them asynchronously: the credit memo records the accepted request, not the money reaching the customer. The module does not check the refund status later. Refunds made in the PayU Dashboard are not reported to Magento; record them with Refund Offline. Refunds work also when Enable is No.

If PayU rejects the refund, Magento shows PayU refund failed: with PayU's message and the credit memo is not created. If PayU's answer is lost, Magento shows The PayU refund result is uncertain. Check the PayU Dashboard before trying again. and further online refunds of this payment stay blocked with The previous PayU India refund result is uncertain. Check the PayU Dashboard before another request., so that money cannot be sent twice. If PayU accepted a refund but Magento could not save the credit memo, repeat the credit memo with the same amount: it is completed without a second request to PayU.

Refund of a payment without an invoice

A payment that went on hold, for example after a mismatch or for a cancelled order, has no invoice, so there is no credit memo for it. While such an order has no paid invoice, the PayU India payment history section shows This payment requires review. Confirm the funds in the PayU Dashboard before refunding. This action creates no native invoice or credit memo. with Amount in INR, Reason and the button Refund held funds via PayU. Admin users need the credit memo permission of the Sales section. A successful request adds a note with the PayU request ID.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox PayU India Payment Gateway is the first row of the VibeFox PayU India Payment Gateway 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-india 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 India 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 India does not appear at checkout: check that the license is active and Enable is Yes for the website of the store, and that the key and salt of the selected Mode are filled in. Check that the currency the customer sees is INR. Check Payment from Applicable Countries and Payment from Specific Countries against the customer's billing address, and Minimum Order Total and Maximum Order Total. To switch a limit off, enter 0. PayU India is not offered for an order total of zero.

The payment went through, but the order stays Pending Payment: no result reached your store: the customer did not come back, and no webhook arrived. Add the webhook URL from the settings page in PayU Dashboard > Webhooks for successful and failed payments, and make sure it is reachable from the internet. Magento maintenance mode closes the whole site, the webhook and return URLs too; PayU's result does not arrive while it is on.

Webhook answers invalid_signature: the PayU hash did not match. Check that the key and salt of the payment's mode are correct and that Salt v1 is used, not Salt v2. A result of a live payment signed with the test salt, or the other way round, is rejected too. Nothing is changed.

Webhook answers not_configured: the key or salt of the mode in which the payment was started is missing. Enter them; a later delivery is then processed.

Webhook answers verify_unavailable: the verify_payment API could not confirm the payment yet. The order is on hold, and the next delivery verifies again. If no further delivery comes, check the payment in the PayU Dashboard.

Webhook answers busy or retry: the customer's return of the same order was being processed at the same moment, or the result could not be applied. The answer is HTTP 503, so the result can be delivered again. The reason of a retry is written to the log.

Webhook answers ignored_unknown_txnid: the transaction was not started by this store, for example another store using the same PayU account. Nothing is changed.

The customer is back in the cart with PayU India requires a phone number: keep the phone field of the address required in the checkout. The billing address is used first, then the shipping address.

A payment was made but the order is On Hold or Canceled: read the order notes. The reason is an amount or currency mismatch, a failed or pending verification, or a payment for an order that had been cancelled, for example by the Pending Payment Order Lifetime cron. Check the transaction in the PayU Dashboard.

The order e-mail arrives late or not at all: the e-mail of a paid order is sent by the Magento cron, every 20 minutes. Check that cron is running and that order e-mails are enabled.

The Refund button is missing on the credit memo: open the credit memo from the invoice, not from the order page. An order without an invoice has no online refund; see Refund of a payment without an invoice.

Refund fails: The Merchant Key and Salt for the original payment mode are required. means you must enter the credentials of that mode first. Refund amount exceeds the remaining … INR. means the amount is more than the rest of the payment. PayU India payment is busy. Please try again. means a result of the same order is being processed.

Too little in the log: errors and warnings are always written; set Enable Logging to Yes to see every payment form and API call as well.

For developers: the Magento event payu_p_request_fields changes the payment request fields before they are signed. The key, transaction ID, amount and return URLs cannot be changed by it.

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

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

The license key and license status are always removed. If Delete data on uninstall is Yes, the module settings, cache and log are removed too. If it is No, the settings and the log are kept for a re-install. The PayU transaction records and refund requests 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.