VibeFox PayU LATAM 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.

Currency: the order must be in ARS, BRL, CLP, COP, MXN, PEN or USD, the currencies processed by PayU Latam in Argentina, Brazil, Chile, Colombia, Mexico, Panama and Peru. In other currencies the payment method is hidden at checkout.

PayU Latam account: you need three values of your PayU commerce: the merchant ID, the account ID of the country you sell in and the API key. They are in the PayU module (the PayU merchant panel) under Settings > Technical configuration (merchant ID, API key) and Accounts (account ID). For testing, PayU publishes public sandbox credentials and test cards on the "Test your solution" page of its developer documentation. The API Login and other API credentials are not needed, because the payment is made on the PayU hosted page.

Internet access to your site: PayU sends the payment result to your store from its servers, so the site must be reachable from the internet (not a local site, not behind password protection or a maintenance page).

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_latam_payment folder to /wp-content/plugins/ by FTP.

2. Click Activate.

3. Open the settings: WooCommerce > Settings > Payments > PayU LATAM > 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 sandbox credentials and your live credentials (see Configuration). No confirmation URL has to be configured in PayU.

6. Turn on Enable/Disable and save. Keep Sandbox on until you have made a test payment, then untick it to accept real payments with the live credentials.

Configuration

All settings are on one page: WooCommerce > Settings > Payments > PayU LATAM. Above the fields the page warns you while sandbox mode is on (Sandbox mode. Payments go to the PayU sandbox and no real money is charged.), when the merchant ID, account ID or API key of the current environment is missing, and when PayU LATAM does not process the store currency. In the last two cases PayU LATAM is not shown at checkout. In the list of payment methods, PayU LATAM is marked as needing setup until the three credentials of the current environment are filled in. Spaces at the start or end of a credential are ignored.

General

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

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

Description: the payment method description displayed to the customer during checkout. Default: Pay with a card, cash or bank transfer on the secure PayU page. You will be redirected to PayU to complete your payment.

Environment

Sandbox: Enable the PayU sandbox (test mode). Payments go to the PayU sandbox with the sandbox credentials below, and no real money is charged. When disabled, the live credentials and the live PayU checkout are used. Default: on.

Live credentials

Find them in the PayU module: Settings > Technical configuration (merchant ID, API key) and Accounts (account ID of the country you sell in). The section links to the PayU merchant panel.

Merchant ID: the numeric identifier of your PayU commerce.

Account ID: the identifier of the PayU account. There is one account per country.

API Key: the secret key used to sign payments and to verify PayU notifications.

Sandbox credentials

PayU publishes public test credentials and test cards for its sandbox. The section links to the "Test your solution" page of the PayU documentation.

Sandbox merchant ID: the merchant ID for the PayU sandbox.

Sandbox account ID: the account ID for the PayU sandbox.

Sandbox API key: the API key for the PayU sandbox.

Every payment attempt remembers its environment. The confirmation of a sandbox payment is verified with the sandbox API key and merchant ID, and the confirmation of a live payment with the live ones, so pending payments keep working after you switch. When you update from version 1.0, which had one set of credentials, the old values are copied to the sandbox fields if the sandbox was on. Check the settings after updating.

Confirmation URL

This section shows the URL to which PayU reports every payment result. It looks like https://your-site/wc-api/payu_lp/. The plugin sends it to PayU with each payment, so there is nothing to configure in PayU. The page must be reachable from the internet. The confirmation is signed by PayU with your API key. Confirmations without a valid signature, with another merchant ID or with a payment reference that this store did not issue for the order are rejected. The plugin handles these PayU transaction states:

4 (approved): the payment was made. The order is marked paid when the amount and currency match.

6 (declined), 5 (expired), 104 (error): the payment failed. An unpaid order of the latest attempt is marked Failed.

7 and other pending states: the payment is waiting, for example a cash or bank payment the customer has not completed yet. The order is put on hold.

Other states are only added as an order note. Without the confirmation, an order is never marked paid: it stays Pending payment.

Advanced

Debug log: Log payment requests and PayU notifications writes details to WooCommerce > Status > Logs, source wcp_payu_latam_payment, without keys or personal data. Errors and rejected notifications are always logged. Default: off.

Delete data: Delete the settings and logs when the plugin is deleted. Deactivating the plugin never deletes anything. PayU data saved on orders is kept. Default: off.

Checkout

The customer chooses the payment method (by default PayU LATAM) and places the order. On the Checkout block in sandbox mode the customer sees Sandbox mode: no real payment is made. The order stays Pending payment, and the customer goes to a payment page of your store with the text Thank you for your order. You are being redirected to PayU LATAM to complete the payment… The page sends a signed form to the PayU WebCheckout page automatically. If that does not happen, the customer clicks Pay with PayU LATAM, or Cancel order to cancel the order.

The form contains the order total and currency, the tax and the tax base of the order (both 0 for orders without tax, so that PayU does not add a default VAT), the description Order # with the order number and your store name, the customer's e-mail, name, phone and billing address. The PayU page opens in Spanish, Portuguese or English, following the store language. On the PayU page the customer pays with any method enabled in your PayU account.

Each visit of the payment page starts a new payment attempt with its own reference (the order number and a timestamp). The last 30 attempts of the order are remembered: if the customer pays in an older PayU tab, the payment is still accepted.

The order is marked paid only after PayU confirms it with the signed confirmation. The customer coming back from PayU never marks an order as paid. When the customer comes back:

After a signed decline, expiry or error: the order is marked Failed at once, and WooCommerce shows its standard page for a failed payment with the option to pay again.

Without a PayU transaction (the customer left the PayU page): the customer goes to the Pay for order page with the message Your PayU LATAM payment was not completed. You can try again or choose another payment method.

Otherwise: the customer sees the order received page. While the order is Pending payment, it says We are waiting for PayU LATAM to confirm your payment. You will receive an e-mail as soon as it is confirmed. For an order on hold it says Your PayU LATAM payment is pending (for example, a cash or bank payment that has not been completed yet). We will process the order as soon as PayU confirms the payment.

If the credentials of the current environment are missing, the customer sees PayU LATAM is not available right now. Please choose another payment method. For an unsupported order currency the message is PayU LATAM does not accept payments in followed by the currency. An order that is already paid is not paid again: the payment page shows This order has already been paid.

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 plugin has no payment form in your store, no refunds from WooCommerce, no saved cards, no subscriptions and no installments settings (PayU shows installments on its page). It does not query the PayU API for the payment status: only the signed confirmation updates the order.

Orders

Order statuses

Pending payment: the customer was sent to PayU and has not paid yet, or PayU has not sent the confirmation yet.

Processing: PayU confirmed the payment and the amount and currency match. The order note shows the PayU transaction, the amount, the payment method and [sandbox] for sandbox payments. The transaction ID of the order is the PayU transaction ID. Orders with only virtual downloadable products become Completed, as WooCommerce does by default.

On hold: PayU reports the payment as pending (cash or bank payment), the paid amount or currency does not match the order total, or a payment was approved for an order that had been cancelled. The order note says which one: check the payment in the PayU module, then process the order, restore it or refund the payment.

Failed: the latest payment attempt was declined, expired or ended with an error. The note shows the PayU message. The customer can pay again. A decline of an older attempt, or of an order that already has an approved payment, is only added as a note.

Every notification is processed once, under a per-order lock: repeated PayU notifications do not add notes, reduce stock or send e-mails twice. If the order is being updated by another request for too long, the confirmation is answered with an error and PayU sends it again later. A paid, completed or refunded order is never reopened. If another approved payment arrives for an order that is already paid, a note says so: if the customer paid twice, refund the duplicate in the PayU module.

Refunds

Refunds are not made from WooCommerce. Refund the transaction in the PayU module and, if needed, record the refund manually in WooCommerce.

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 LATAM. 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 LATAM 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.

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 LATAM does not appear at checkout: check that the license is active, Enable/Disable is on and the merchant ID, account ID and API key of the current environment are filled in: the sandbox credentials when Sandbox is on, the live credentials when it is off. Check that the store currency (or the order currency on the Pay for order page) is ARS, BRL, CLP, COP, MXN, PEN or USD. The settings page shows a warning for each of these problems.

The payment went through, but the order stays Pending payment: the PayU confirmation did not reach your store or was rejected. Check that the confirmation URL shown in the settings is reachable from the internet (no local site, maintenance mode, firewall or password protection). Look at WooCommerce > Status > Logs, source wcp_payu_latam_payment, for rejected confirmations. PayU sends the confirmation again after any error answer.

Confirmation answers Invalid signature: the confirmation was not signed with the API key of the environment of the payment. Check API Key for live payments and Sandbox API key for sandbox payments.

Confirmation answers Merchant mismatch: the merchant ID of the confirmation differs from Merchant ID or Sandbox merchant ID of the payment's environment. Enter the merchant ID of the PayU account that processes the payments.

Confirmation answers Gateway not configured: the API key or merchant ID of the payment's environment is missing, for example the sandbox credentials were removed while a sandbox payment was pending. Enter them again; PayU retries the confirmation.

Confirmation answers Busy, retry later: the order was being updated by another request at the same time. Nothing was changed, and PayU sends the confirmation again.

Confirmation answers Unknown reference: the payment reference does not belong to a PayU LATAM order of this store, for example the order was switched to another payment method or deleted.

The order is On hold: read the order note. The payment is still pending at PayU (cash or bank payment), the paid amount or currency differed from the order, or the payment arrived after the order had been cancelled. Check the transaction in the PayU module.

Other currencies or form fields: developers can change the currency list with the payu_lp_supported_currencies filter, the checkout icon with the payu_lp_icon filter and the WebCheckout form fields with the payu_lp_payment_fields 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 data. To remove it, deactivate and delete it on the Plugins page. The license key and license status of this plugin are always removed. The gateway settings and the logs of this plugin are removed only if Delete data was on. Otherwise they stay for a later re-install. Existing orders keep their payment notes, PayU references and transaction IDs.

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