VibeFox PayU LATAM for OpenCart — Help

Requirements

OpenCart: 3.0.x (tested on 3.0.5.0) or 4.0.2 and later (tested on 4.1.0.3).

PHP: 8.0 or later.

Currency: the checkout currency of the customer 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 extension 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 download is one zip file with the packages for both OpenCart versions. Unpack it on your computer. It contains README.txt, the OpenCart 3 package wcp_payu_latam_payment-oc3-(version).ocmod.zip and the OpenCart 4 package wcp_payu_latam_payment.ocmod.zip. Install only the package for your OpenCart version. The license key is the same for both versions.

OpenCart 3

1. In the admin go to Extensions > Installer, click Upload and choose the file wcp_payu_latam_payment-oc3-(version).ocmod.zip. The extension has no OCMOD modifications, so Extensions > Modifications does not need a refresh. Instead of the installer you can copy the contents of the upload folder of this package into the root folder of your store.

2. Go to Extensions > Extensions and choose the type Payments. Find VibeFox PayU LATAM Payment and click Install (the green + button). Your admin user needs the right to modify the payment extensions list.

3. Click Edit (the pencil button) to open the settings page. Paste your VibeFox license key into License key in the license block at the top of the 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.

OpenCart 4

1. In the admin go to Extensions > Installer, click Upload and choose the file wcp_payu_latam_payment.ocmod.zip. Do not rename the file: OpenCart 4 takes the extension code from the file name, and a renamed package does not work.

2. The package appears in the list of installed extensions on the same page. Click Install (the green + button) next to it.

3. Go to Extensions > Extensions and choose the type Payments. Find VibeFox PayU LATAM Payment, click Install (the green + button), then Edit (the pencil button).

4. Enter the license key and the PayU credentials as in steps 3 to 5 for OpenCart 3. The settings page and its fields are the same in both versions. Only the confirmation URL is different (see Confirmation URL).

A new install starts with the payment method turned off and the sandbox on.

Configuration

All settings are on the extension page: Extensions > Extensions > Payments > VibeFox PayU LATAM Payment > Edit. The sections are listed on the left; the Save button under the list saves the whole page. Above the settings 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 (PayU LATAM is then not offered at checkout), and a warning when PayU LATAM does not process the default currency of the store. Without the right to modify the extension the page shows the settings but cannot save them.

When you save, Title must not be empty or longer than 128 characters (the page shows Enter a title for the payment method (at most 128 characters).), Sort Order must be a whole number (negative numbers are allowed), Total must be a number, 0 or greater, and the geo zone and order statuses must exist. Otherwise nothing is saved. Spaces at the start or end of a credential are ignored.

PayU LATAM

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

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: the text shown to the customer at the Confirm Order step, above the confirm button. Default: Pay with a card, cash or bank transfer on the secure PayU page. You will be redirected to PayU to complete your payment.

Sort Order: the position of PayU LATAM among the payment methods at checkout. Leave it empty or enter a whole number.

Geo Zone: offer PayU LATAM only for payment addresses in the selected geo zone. Default: All zones. Geo zones are set up in System > Localisation > Geo Zones.

Total: the checkout total, in the default currency of the store, that an order must reach before PayU LATAM is offered. Leave it empty to offer PayU LATAM for any total.

Environment

Sandbox: payments go to the PayU sandbox with the sandbox credentials, 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. at the Confirm Order step.

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. To remove a saved key, tick Clear saved secret on save under the field and click Save.

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. Sandbox payments are marked as sandbox in the order notes.

Confirmation URL

This section shows the URL to which PayU reports every payment result. On OpenCart 3 it looks like https://your-store/index.php?route=extension/payment/wcp_payu_latam_payment/confirmation, on OpenCart 4 like https://your-store/index.php?route=extension/wcp_payu_latam_payment/payment/wcp_payu_latam_payment.confirmation. It is built from the storefront address of your OpenCart installation. The extension 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 store is in maintenance mode (on OpenCart 4 through the startup action of the extension, which also lets the customer return from PayU). 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 extension handles these PayU transaction states:

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

6 (declined), 5 (expired), 104 (error): the payment failed. An order without a status keeps no status, 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 gets Awaiting Payment Status.

Other states are only added as a note. Without the confirmation, the order gets no status.

Orders

OpenCart creates the order at the Confirm Order step without a status (a missing order). The order gets a status only after the signed PayU confirmation. Each field below lists your OpenCart order statuses.

Order Status After Payment: an approved payment (PayU state 4) with the expected amount and currency. Default: Processing.

Awaiting Payment Status: a pending payment (states 7, 10, 12, 14, 15, 18, for example a cash or bank payment not completed yet). The order gets Order Status After Payment when PayU confirms it. Default: Pending.

On Hold (Review) Status: PayU approved a payment, but with another amount or currency than the order, or for an order that had been cancelled. A note shows the details; the order is not marked as paid. Default: Pending, because OpenCart has no On hold status. You can create your own status in System > Localisation > Order Statuses and select it here.

Failed Payment Status: a pending payment of the latest attempt that PayU then reported as declined, expired or failed. Default: Failed.

Cancelled Order Status: the status your store uses for cancelled orders. A payment approved for such an order puts it into On Hold (Review) Status instead of marking it as paid. The extension never sets this status. Default: Canceled.

Advanced

Debug log: logs payment requests and PayU notifications to payu_lp_debug.log.php in the OpenCart logs folder (storage/logs). The file cannot be opened from the web, and at 5 MB it is moved to payu_lp_debug.old.log.php. 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: when on, uninstalling the extension removes the gateway settings and the log. Orders and the PayU payment records (payment attempts) are never deleted. Default: off.

Import / Export

Export: Download JSON saves the settings as a JSON file. The API keys are not exported.

Import: paste previously exported JSON and click Import to restore the settings. The saved API keys are kept.

Checkout

At the Payment Method step the customer chooses the payment method (by default PayU LATAM). At the Confirm Order step the customer sees your description; OpenCart creates the order at this step, still without a status. On OpenCart 4 the customer picks the payment method with the Choose button of the payment method block, in the window Payment method options, and clicks Confirm Order at the bottom of the checkout page. When the customer clicks Confirm Order, the extension prepares a signed payment form, the page shows You are being redirected to PayU LATAM to complete the payment... and sends the form to the PayU WebCheckout page automatically. If that does not happen, the customer clicks Pay with PayU LATAM.

The form contains the order total in the 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), 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 customer's language. On the PayU page the customer pays with any method enabled in your PayU account.

Each click on Confirm Order starts a new payment attempt with its own reference (OC, the order number and a timestamp). On OpenCart 4 a new attempt pays the same order of the checkout. Older attempts are remembered: if the customer pays in an older PayU tab, the payment is still recognised.

The order is marked paid only after PayU confirms it with the signed confirmation. The order then gets its status the standard OpenCart way, with the usual order e-mails and stock update. 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 has a status: the customer sees the OpenCart order success page. For a pending payment it also 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 a payment on review it says We have received your PayU LATAM payment and are reviewing it. We will contact you if anything is needed. If a pending payment later failed, the customer is back at checkout with the reason.

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 and a Back to checkout button. The confirmation sets the order status as soon as it arrives.

On OpenCart 4 the checkout messages are shown above the checkout page.

OpenCart 3 creates a new order every time the Confirm Order step is shown, OpenCart 4 updates the order of the checkout, but a cart is paid only once: if another order of the same cart is already paid, awaiting payment or on review, Confirm Order leads straight to the success page. A change of the cart, including a new quantity, counts as a new cart that needs its own 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.

OpenCart 4 keeps the order in the checkout until the success page is shown. If that order was closed without a payment meanwhile (for example its cash payment failed or you cancelled it), the customer is sent back to the checkout with Your PayU LATAM payment was not approved and the PayU reason if there is one. If it was paid and then closed by the store, or it was paid for an earlier cart and the cart has changed since, the message is Your previous order is already closed. Please confirm the order again: the cart will be paid with a new order. The next Confirm Order pays a new order. A closed order is never shown as paid.

The extension has no payment form on your site, no refunds from OpenCart, 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 status (missing order): the customer was sent to PayU and has not paid, the payment was declined, or PayU has not sent the confirmation yet. In Sales > Orders such orders are shown only with the filter Order Status set to Missing Orders.

Order Status After Payment (default Processing): PayU confirmed the payment and the amount and currency match. A note shows the transaction, the amount, the payment method and whether it was a sandbox payment.

Awaiting Payment Status (default Pending): PayU reports the payment as pending (cash or bank payment). The order moves to Order Status After Payment when PayU confirms the payment, or to Failed Payment Status when it fails. OpenCart notifies the customer of these changes.

On Hold (Review) Status (default Pending): the paid amount or currency does not match the order total, or a payment was approved for an order that had been cancelled. The note says which one: check the payment in the PayU module, then process the order, restore it or refund the payment.

Failed Payment Status (default Failed): a pending payment of the latest attempt was later declined, expired or ended with an error. The note shows the PayU message. 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 change the order twice or add notes twice. A paid order is never downgraded. If another approved payment arrives for an order that is already paid, or for another order of the same cart, a note on the paid order says so: if the customer paid twice, refund the duplicate in the PayU module.

Notes are entries in the order History that the customer does not see.

VibeFox PayU LATAM Payment tab

In Sales > Orders open an order paid with PayU LATAM. At the bottom of the order page, next to History and Additional, the VibeFox PayU LATAM Payment tab shows 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. The tab is shown to users who have access to the extension.

Refunds

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

License key

The extension works with a VibeFox license key from vibefox.net. The license block License — VibeFox PayU LATAM Payment is the first block on Extensions > Extensions > Payments > VibeFox PayU LATAM Payment > Edit, 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: opencart-payment-payu-latam and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only admin users with the Modify permission for the extension can change the key. The texts of the block follow the admin 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 store address changes, or after you free a domain slot in your account, click Check now. If the license server cannot be reached, the extension keeps working on the last known status.

One key works on one domain: the store address from the OpenCart configuration. 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 customer sees This payment method is not available. Please choose another one. An admin user who is logged in to the admin in the same browser still sees the payment method in the store, marked (unlicensed — visible to admins only), so you can set up and test the extension before you buy a key. On OpenCart 4 this preview is not available: the store does not see the admin login, so without an active key the payment method is hidden for everybody. After you have opened the Edit page once, a reminder appears on the admin Dashboard. Close it with × to hide it for 7 days. Existing orders are not affected: payments already started are still confirmed by the PayU confirmation and the customer return.

When a license expires, the extension keeps working, but updates and support need a renewal. The status is checked again automatically when you open the admin Dashboard or the Edit page: once a day for the first 14 days after the key is entered, then once a week. No cron job is needed. Uninstalling the extension 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 customer's currency is ARS, BRL, CLP, COP, MXN, PEN or USD, that the payment address is in the selected Geo Zone and that the order reaches the Total set in the settings.

The payment went through, but the order stays without a status: 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, firewall or password protection). Look at the Log field on the extension 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 status could not be set. 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 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. Please reload the checkout page.: the checkout session no longer matches the order, or Enable/Disable was turned off meanwhile. The customer reloads the checkout.

The order is in the review status: read the notes in the VibeFox PayU LATAM Payment tab. 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.

Uninstall

Go to Extensions > Extensions, choose the type Payments and click Uninstall (the red − button) next to VibeFox PayU LATAM Payment. The license key and license status of this extension are always removed. OpenCart always removes its own settings of the extension: Enable/Disable, Sort Order, Geo Zone, Total and the order statuses of the Orders section, which return to their defaults on a re-install. The OpenCart event of the extension is removed too (on OpenCart 4 its events and its startup action, which lets the confirmation and the customer's return through in maintenance mode). If Delete data is on, the other gateway settings (title, description, sandbox, credentials, debug log switch) and the log are removed. If it is off, they are kept for a later re-install. The 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 payment notes.

On OpenCart 4, to remove the files of the extension as well, go to Extensions > Installer after the uninstall and click Uninstall (the orange − button) next to VibeFox PayU LATAM Payment in the list of installed extensions, then Delete (the red bin button) to remove the uploaded package.

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