VibeFox PayU LATAM for PrestaShop — Help

Requirements

PrestaShop: 8.0 to 9.x.

PHP: 8.0 or later. The module refuses to install on older PHP versions.

Currency: the cart 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 and the module never calls the PayU API.

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

VibeFox license key: bought on vibefox.net. One key works on one domain.

Installation

1. In the back office go to Modules > Module Manager and click Upload a module. Choose the module ZIP file.

2. When the upload finishes, click Configure, or find VibeFox PayU LATAM Payment in the module list later and click Configure.

3. Paste your VibeFox license key into License key in the license block at the top of the Configure page and click Activate (see License key).

4. Enter the sandbox credentials and your live credentials (see Configuration). No confirmation URL has to be configured in PayU.

5. Turn on Enable/Disable and click Save. Keep Sandbox on until you have made a test payment, then turn it off to accept real payments with the live credentials.

On install the module creates two order statuses, Awaiting PayU LATAM payment and PayU LATAM payment on hold. PrestaShop offers a new payment module for all currencies, countries and customer groups. You can limit them in Payment > Preferences. A country enabled later must be ticked there for the module as well.

Configuration

All settings are on the module page: Modules > Module Manager > VibeFox PayU LATAM Payment > Configure. Each section has its own Save button, which saves the whole page. Above the fields the page shows Sandbox mode. Payments go to the PayU sandbox and no real money is charged. while the sandbox is on, an error when the merchant ID, account ID or API key of the current environment is missing, and a warning when PayU LATAM does not process the default shop currency. While credentials are missing, PayU LATAM is not shown at checkout. Spaces at the start or end of a credential are ignored. The page does not save an empty Title and shows Enter a title for the payment method.

PayU LATAM

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. It is also the payment method name stored in the order. Default: PayU LATAM. Required.

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: 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. While it is on, customers see Sandbox mode: no real money is charged. under the payment method.

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.

Saved API keys are never shown again. The field stays empty and shows Saved — leave empty to keep it. Type a new value only to change it.

Clear saved secrets: tick API Key or Sandbox API key and click Save to remove the saved key. An empty field keeps the saved value.

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. A sandbox payment confirmed after the switch is marked [sandbox] in the order notes.

Confirmation URL

This section shows the URL to which PayU reports every payment result. With friendly URLs it looks like https://your-shop/module/wcp_payu_latam_payment/confirmation, possibly with a language code such as /en/. The module sends it to PayU with each payment, so there is nothing to configure in PayU. The URL must be reachable from the internet. It also works while the shop is in maintenance mode and is not blocked by the country restriction of your shop. 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 shop did not issue are rejected. The module handles these PayU transaction states:

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

6 (declined), 5 (expired), 104 (error): the payment failed. No order is created and the cart is kept.

7, 10, 12, 14, 15, 18 (pending): the payment is waiting, for example a cash or bank payment the customer has not completed yet. The order is created in Awaiting PayU LATAM payment.

Other states are only added as a note. Without the confirmation, no order is created.

Advanced

Debug log: logs payment requests and PayU notifications to logs/payu_lp_debug.log.php in the module folder. The file cannot be opened from the web. Keys and personal data are not logged. Errors and rejected notifications are always logged, even when this switch is off. Default: off.

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

Delete data: deletes the settings and logs when the module is uninstalled. PayU data of orders (payment attempts) and the order statuses are kept. Default: off.

Checkout

At the payment step the customer chooses the payment method (by default PayU LATAM) and confirms. A page of your shop shows You are being redirected to PayU LATAM to complete the payment... and sends a signed form to the PayU WebCheckout page automatically. If that does not happen, the customer clicks Pay with PayU LATAM, or Back to checkout to return. No order exists yet at this point.

The form contains the cart total and currency, the tax and the tax base of the cart (both 0 for carts without tax, so that PayU does not add a default VAT), the description Cart # with the cart number and your shop name, the customer's e-mail, name, phone and billing address. The PayU page opens in Spanish, Portuguese or English, following the cart 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 (PS, the cart number and a timestamp). Older attempts 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 customer is back at checkout with Your PayU LATAM payment was not approved, the PayU reason if there is one, and You can try again or choose another payment method. The cart is kept.

Without a PayU transaction (the customer left the PayU page): the customer is back at checkout with Your PayU LATAM payment was not completed. You can try again or choose another payment method.

The order already exists: the customer sees the standard order confirmation page. For an order in Awaiting PayU LATAM payment 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. For an order on hold it says We have received your PayU LATAM payment and are reviewing it. We will contact you if anything is needed. For an order in Payment error it says Your PayU LATAM payment was not approved. Please contact us.

PayU has not confirmed yet: a page says We are waiting for PayU LATAM to confirm your payment. You will receive an e-mail as soon as it is confirmed. (or the pending text above for a cash or bank payment) with a Check again button. The confirmation creates the order as soon as it arrives.

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 cart currency the message is PayU LATAM does not accept payments in followed by the currency. A cart that already has an order is not paid again: the customer goes to its order confirmation page.

The module has no payment form in your shop, no refunds from PrestaShop, 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

No order yet: the customer was sent to PayU and has not paid, the payment was declined, or PayU has not sent the confirmation yet. Only the cart exists.

Payment accepted: PayU confirmed the payment and the amount and currency match. The payment is recorded with the PayU transaction ID, and a note shows the transaction, the amount, the payment method and [sandbox] for sandbox payments.

Awaiting PayU LATAM payment: PayU reports the payment as pending (cash or bank payment). The order moves to Payment accepted when PayU confirms the payment.

PayU LATAM payment on hold: the paid amount or currency does not match the cart total, or a payment was approved for an order that had been cancelled. The payment is recorded if it is in the order currency. The note says which one: check the payment in the PayU module, then process the order, restore it or refund the payment.

Payment error: a pending payment of the latest attempt was later declined, expired or ended with an error. The note shows the PayU message. This cart cannot be paid again: the customer places a new order. 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-cart lock: repeated PayU notifications do not create a second order or add notes twice. A paid order is never reopened or downgraded. 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.

PayU LATAM payment block

The order page shows a PayU LATAM payment block with the reference, the transaction ID, the PayU reference, the status and the PayU state, the requested amount, the amount reported by PayU, the payment method, the PayU message, a SANDBOX badge for sandbox payments, the list of all payment attempts of the cart and the PayU LATAM notes of the order.

Refunds

Refunds are not made from PrestaShop. Refund the transaction in the PayU module, then record the refund in PrestaShop manually.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox PayU LATAM Payment is the first block on Modules > Module Manager > VibeFox PayU LATAM Payment > Configure, 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 shop. Below them are the line Product: presta-payment-payu-latam and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only employees with the Configure permission for the module can change the key. The texts of the block follow the back office 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 shop 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 main shop, also in a multistore setup. Removing the key from the shop 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. The PrestaShop storefront does not know that you are logged in to the back office, 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 Modules > Module Manager on the Alerts tab. Existing orders are not affected: payments already started are still confirmed by the PayU confirmation and the customer return.

When a license expires, the module keeps working, but updates and support need a renewal. The status is checked again automatically while you work in the back office: once a day for the first 14 days after the key is entered, then once a week. No cron job is needed. Uninstalling or resetting the module always removes the license key and license status.

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 cart currency is ARS, BRL, CLP, COP, MXN, PEN or USD. In Payment > Preferences check that the module is allowed for the cart currency, the customer's country and the customer's group.

The payment went through, but no order was created: the PayU confirmation did not reach your shop or was rejected. Check that the confirmation URL shown in the settings is reachable from the internet (no local site, firewall or password protection). Look at the Log field on the module page 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 Retry: the cart was being processed by another request at the same moment, or the order could not be created (for example, the module is disabled). Nothing was changed, and PayU sends the confirmation again. Look at the Log for the reason.

Confirmation answers Unknown reference: the payment reference was not issued by this shop.

The confirmation URL shows Method not allowed in the browser: this is normal. The URL accepts only requests from PayU.

The customer sees This payment method is not available: the module is not allowed for the customer's country, currency or group in Payment > Preferences, or Enable/Disable is off.

The order is PayU LATAM payment on hold: read the notes in the PayU LATAM payment block. The paid amount or currency differed from the cart, or the payment arrived after the order had been cancelled. Check the transaction in the PayU module.

Uninstall

Go to Modules > Module Manager, open the menu next to VibeFox PayU LATAM Payment and choose Uninstall. The license key and license status of this module are always removed. If Delete data is on, the settings and the log are removed. If it is off, all settings are kept for a later re-install. The payment attempts and the order statuses Awaiting PayU LATAM payment and PayU LATAM payment on hold are always kept, so a late PayU confirmation of an old attempt is still recognised after a re-install. Existing orders keep their payment notes, PayU references and transaction IDs.

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