VibeFox PayU LATAM for Adobe Commerce — Aide

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.

Currency: the order currency must be 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 store: PayU sends the payment result to your store from its servers, so the store 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

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

2. Run bin/magento module:enable Vibefox_PayuLatamPayment 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 LATAM 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 sandbox credentials and your live credentials (see Configuration), keep Sandbox at Yes, set Enable to Yes, click Save Config and place a test order. When everything works, set Sandbox to No and click Save Config to accept real payments with the live credentials.

The module adds the PayU LATAM 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 its own tables for the PayU payment attempts and for the notifications already processed. The confirmation URL is sent to PayU automatically with every payment. Nothing has to be configured in PayU.

Configuration

All settings are in Stores > Configuration > Sales > Payment Methods > VibeFox PayU LATAM Payment, 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. Delete data on uninstall exists only in the Default Config. Save Config saves the whole page. Amounts use a dot as the decimal separator ("9.99").

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 LATAM: enter a title of 1 to 128 characters.); a Sort Order that is empty or not a whole number (PayU LATAM: Sort Order must be a whole number.); a Minimum Order Total or Maximum Order Total that is empty, negative or not a number (PayU LATAM: order limits must be non-negative numbers.). Spaces at the start or end of a credential are removed; the format of the credentials is not checked when you save.

When Enable is Yes and a credential of the current environment is missing, Magento saves the page and shows the warning PayU LATAM: enter the merchant ID, account ID and API key of the selected environment. While credentials are missing, PayU LATAM is not shown at checkout.

PayU LATAM information

The first row after the license block says PayU LATAM WebCheckout supports ARS, BRL, CLP, COP, MXN, PEN and USD. No refund API is provided; refund in the PayU Dashboard. and Confirmation URL is sent automatically with every payment., followed by the URL to which PayU reports every payment result. It looks like https://your-store/wcppayulatampayment/checkout/confirmation/. Each payment sends the confirmation URL of the store view where the order was placed, so there is nothing to configure in PayU. It only has to be reachable from the internet.

While Enable is Yes, the row also shows Sandbox mode: no real money is charged. while the sandbox is on, and Enter all three credentials of the selected environment. when a credential is missing.

Settings

The settings are one list on the page, in this order.

Enable: shows or hides PayU LATAM at checkout. It is shown only when the merchant ID, account ID and API key of the current environment are set. Default: No.

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

Description: shown in the payment method list at checkout, under the method when the customer selects it. Default: Pay with a card, cash or bank transfer on the secure PayU page. You will be redirected to PayU to complete your payment.

Sandbox: payments go to the PayU sandbox with the sandbox credentials, and no real money is charged. When No, the live credentials and the live PayU checkout are used. Default: Yes. While it is on, customers see TEST MODE: no real money is charged. under the payment method.

Live Merchant ID: the numeric identifier of your PayU commerce. Find it in the PayU module under Settings > Technical configuration.

Live Account ID: the identifier of the PayU account. There is one account per country. Find it in the PayU module under Accounts.

Live API Key: the secret key used to sign payments and to verify PayU notifications. Find it in the PayU module under Settings > Technical configuration.

Sandbox Merchant ID: the merchant ID for the PayU sandbox. PayU publishes public test credentials and test cards on the "Test your solution" page of its documentation.

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

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

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

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. Keep the credentials of the old environment until its payments are finished. The note of the approved payment and the payment information of the order show the environment.

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

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

Minimum Order Total: offer PayU LATAM only from this order total, in the base currency of your store. Zero disables the limit. Default: 0.

Maximum Order Total: offer PayU LATAM only up to this order total, in the base currency. Zero disables the limit. Default: 0.

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

Debug log: writes payment requests and PayU notifications to var/log/payu_lp_debug.log.php in the Magento folder. The file cannot be opened from the web and is rotated at 5 MB. API keys and e-mail addresses are hidden in the log. Errors and rejected notifications are always logged, even when this setting is No. Default: No.

Delete data on uninstall: when Yes, uninstalling the module with its data removes the module settings of all scopes and the log (see Uninstall). The license key is always removed. Orders, invoices and the PayU payment attempts are always kept. Default: No.

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

PayU transaction states

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 are rejected. The module handles these PayU transaction states:

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

Checkout

At the payment step the customer chooses the payment method (by default PayU LATAM) and sees the description and the note You will pay on the PayU LATAM 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. A page of your store shows You are being redirected to PayU LATAM. and sends a signed form to the PayU WebCheckout page automatically. If that does not happen, the customer clicks Continue to PayU LATAM.

The form contains the order total and order 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), a description with the order number and the store name of the store view in one line (only the order number when the store has no name), and the customer's e-mail, name, phone and billing address. CLP amounts are sent as whole pesos, rounded from the Magento order total, because PayU does not accept decimals in Chilean pesos. The invoice still covers the full order total, so a CLP order total with decimals can differ from the amount charged at PayU by less than one peso. The PayU page opens in Spanish, Portuguese or English, following the locale of the store view. On the PayU page the customer pays with any method enabled in your PayU account. Card data never touches your site.

Each payment attempt has its own reference (MG, the order ID, a timestamp and a random part). If the customer opens the start page again while the order is waiting, a new attempt is started and the older ones are remembered: if the customer pays in an older PayU tab, the payment is still accepted. While a pending payment or a payment under review exists for the cart, no new attempt is started and the customer goes to the waiting page.

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. The confirmation is handled even when Enable is No or the license is not active, and it is matched to the order by its reference, whichever store view the request arrives on. After an approved confirmation Magento creates the invoice with the PayU transaction as the transaction ID and the order moves to Processing. The order e-mail is then sent by a cron job of the module that runs every 15 minutes, if order e-mails are enabled in the Magento sales e-mail settings. So the Magento cron must be running.

When the customer comes back:

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 LATAM is not configured. Please choose another payment method. (the module is disabled or a credential of the current environment is missing), PayU LATAM does not support this currency., PayU LATAM is unavailable for this order amount., PayU LATAM is unavailable for this billing country. or PayU LATAM could not start the payment. Please try again. If the cart is already paid, the customer goes to the order success page.

Magento cancels orders that stay in Pending Payment longer than the Pending Payment Order Lifetime (Stores > Configuration > Sales > Sales > Orders Cron Settings). The module does not stop this cancellation, also not for a cash or bank payment that is still pending at PayU, so set the lifetime long enough for the cash and bank methods you offer. If PayU later approves a payment for a cancelled order, the order is not invoiced and not reopened: it stays Canceled and a note asks you to restore the fulfillment or refund the payment in PayU.

The module works with the standard Magento checkout. It has no payment form in your store, no online refunds, 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 marks an order paid. PayU LATAM is not offered for orders created in the Admin or for checkout with multiple addresses.

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. When PayU reports a cash or bank payment as pending, a note shows the transaction and the reference. There is no invoice. The order is invoiced when PayU confirms the payment.

Processing: PayU confirmed the payment and the amount and currency match. The invoice is created with the PayU transaction as the transaction ID, and a note shows the transaction, the amount, the reference and the environment (sandbox or live).

On Hold: the paid amount or currency does not match the order total (for CLP, the total rounded to whole pesos), or the invoice state of the order changed. No invoice is created. The note shows the received and the expected amount. Check the payment in the PayU module, then process the order or refund the payment in PayU.

Canceled: a payment of the latest attempt was declined, expired or ended with an error, the customer came back without paying, the payment could not be started, or the order was cancelled in Magento. 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 invoice an order twice 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: review it and refund any duplicate in the PayU Dashboard. The notes are order comments that the customer does not see.

PayU LATAM payment information

On the admin order page (Sales > Orders > View) the payment information shows the payment method title and, when known, Reference, Transaction ID, PayU reference, Environment and Payment method. The section PayU LATAM payment history lists all payment attempts of the cart with the reference, transaction ID, PayU reference, environment, status, the expected and the reported amount, the payment method and the PayU message. The customer sees only the payment method title.

Refunds

Refunds are not made from Magento: the module does not call a refund API. Refund the transaction in the PayU Dashboard. Then record it in Magento with a credit memo and Refund Offline, which does not send money back. A refund made in the PayU Dashboard is not reported to Magento by the module.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox PayU LATAM Payment is the first row of the VibeFox PayU LATAM Payment group in Stores > Configuration > Sales > Payment Methods (Default Config scope), 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-latam 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 LATAM 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 by the PayU confirmation.

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 LATAM does not appear at checkout: check that the license is active and Enable is Yes for the website of the store, and that the merchant ID, account ID and API key of the current environment are filled in: the sandbox credentials when Sandbox is Yes, the live credentials when it is No. Check that the cart currency is ARS, BRL, CLP, COP, MXN, PEN or USD. Check Payment from Applicable Countries and Payment from Specific Countries against the customer's billing address, and Minimum Order Total and Maximum Order Total.

The payment went through, but the order stays Pending Payment: the PayU confirmation did not reach your store, was rejected, or reports a pending payment. 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 for rejected confirmations. PayU sends the confirmation again after any error answer.

The order e-mail arrives late or not at all: the module sends it by cron after the invoice. Check that the Magento cron is running and that order e-mails are enabled.

Confirmation answers Invalid signature: the confirmation was not signed with the API key of the environment of the payment. Check Live API Key for live payments and Sandbox API Key for sandbox payments, for the website of the store where the order was placed.

Confirmation answers Merchant mismatch: the merchant ID of the confirmation differs from Live 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 updated. 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 store.

The confirmation URL shows Missing fields in the browser: this is normal. The URL accepts only the data sent by PayU.

Confirmations fail while the store is in maintenance mode: Magento maintenance mode closes the whole site, the confirmation URL too. The order is confirmed by the next confirmation PayU sends after the store is open again.

The order is On Hold or stays Canceled with a note about a payment: read the note on the order and the PayU LATAM payment history section. 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.

The Refund button is missing on the credit memo: this is normal. The module has no online refunds. Refund in the PayU Dashboard and use Refund Offline.

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

Installed in app/code: run bin/magento module:uninstall --non-composer Vibefox_PayuLatamPayment to remove the data, then bin/magento module:disable Vibefox_PayuLatamPayment, delete the folder app/code/Vibefox/PayuLatamPayment 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 of all scopes and the log are removed too. If it is No, the settings and the log are kept for a re-install. The tables with the PayU payment attempts are always kept, so a late PayU confirmation of an old attempt is still recognised 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.