VTEX

VTEX is an enterprise digital commerce platform that enables you to quickly create an online store with built-in capabilities. For more information, visit the official VTEX website

Prerequisites

Before integrating PayU with VTEX, ensure you have the following:

• An active PayU Latam account.
• An active PayU Enterprise (PaymentsOS) account in production/live mode. For details on how to enable live mode, refer to Activating Your PayU Enterprise Account.
• A VTEX account with sufficient rights and permissions to access the VTEX administrative panel. This account must have two-factor authentication enabled.

Availability by Country and Payment Methods

The table below outlines VTEX’s availability by country and the supported payment methods:

Country	Credit Cards	Cash Payments	Other Methods
Argentina	Credit cards	Cash payments	-
Brazil	AMEX, MasterCard, Visa	Boleto Bancário	-
Colombia	AMEX, Codensa, Diners, MasterCard, Visa	Efecty, Su Red, bank reference	PSE
Chile	Credit cards	Cash payments	-
Mexico	Credit cards	Cash payments	SPEI
Peru	AMEX, MasterCard, Visa	-	-

Activating Your PayU Enterprise Account (Live Mode)

By default, new accounts are set to test mode. To enable live transactions, contact your account manager and submit a request with the following details:

• Merchant ID: Locate your LATAM account’s Merchant ID in the PayU Management Panel.
• Account ID: Find your Account ID in the PayU Enterprise control panel by clicking your username in the upper-right corner.
  

Configuring Your PayU Enterprise Account

To configure payment methods in VTEX for processing through our gateway, follow the steps below. The configuration consists of two stages. Before proceeding, ensure that you have met the prerequisites listed above.

1. Initial Setup

PayU Enterprise operates through PaymentsOS, which acts as middleware between PayU Latam and VTEX. The first step is to configure the following components within your PayU Enterprise account:

• Provider configuration
• Business unit
• Webhook

You can configure these components using one of the following methods:

• Configuring the account using Postman.
• Configuring the account manually using PayU Enterprise dashboard.

Configuring the Account Using Postman

Follow these steps to configure your account using Postman:

1. Click the button below to import our Postman collection (refresh the page if the button does not work).

2. After importing the collection, set the global variables. Download the globals file here.

3. In Postman, click Import next to your workspace name and select the downloaded JSON file.

4. Click Import to finalize the process.

5. Run the collection methods in the displayed order. First, select the POST method called 1. Login, then navigate to the Body tab.

6. Enter the email and password for your PayU Enterprise account, then click Send. If the login is successful, the authentication data will be set for the next method.

7. Click the GET method 2. Retrieve PayU Latam ID.

8. In the top-right corner, click the eye icon to locate the env parameter. Click the pencil icon and set it to test for the test environment or live for production.

9. Click Send to proceed.

10. Next, configure a provider, which stores your payment-processing credentials. Select the POST method 3. Create Provider Configuration and navigate to the Body tab.

Fill in the following details:

Parameter	Description
name	Enter a name for the provider configuration.
description	Provide an optional description.
configuration_data.apiLogin	Username or login provided by PayU. How do I get my API Login
configuration_data.apiKey	Unique key of your commerce. How do I get my API Key
configuration_data.accountId	PayU account ID based on your operating country.
configuration_data.merchantId	Your commerce ID in PayU Latam.
configuration_data.paymentCountry	Processing country in ISO 3166 Alpha-3 format.
configuration_data.partnerID	PayU identifier. Enter ZOOZ_VTEX_V2.
configuration_data.cashRedirect	Set to true to ensure proper order flow with cash payments in VTEX.

11. Configure a business unit, which links the provider configuration with PayU Enterprise API credentials for processing transactions. Select the POST method 4. Create Business Unit, then navigate to the Body tab.

Fill in the following details:

Parameter	Description
id	Identifier of the business unit (lowercase, no spaces). This value cannot be changed later, so ensure accuracy..
description	Optional description.

12. Create the webhook, which receives notifications from VTEX when a transaction changes status. Select the POST method 5. Create Webhook, then navigating to the Body tab.

Set the endpoint parameter based on your environment:

• Test: https://sandbox.api.payulatam.com/vtex-payments-integration/paymentsos/webhook
• Live: https://api.payulatam.com/vtex-payments-integration/paymentsos/webhook

Leave all other parameters at their default values.

At this point, your PayU Enterprise account using PaymentsOS is configured. The next step is Configuring the VTEX Provider.

Configuring the Account Manually Using PayU Enterprise Dashboard

Follow these steps to configure your account using PayU Enterprise dashboard.

1. Create the Provider Configuration

A provider stores your payment-processing credentials. Follow these steps to configure one:

1.1 In the PayU Enterprise dashboard, navigate to Configurations > Providers.

1.2 Click the module corresponding to the country or division you are configuring.

1.3 Complete the following fields:

Field	Description
Configuration Name	Enter a name for the provider configuration.
Description	Provide an optional description.
apiLogin	Username or login provided by PayU. Get API Login
apiKey	Unique key of your commerce. Get API Key
accountId	PayU account ID based on your operating country.
merchantId	Your commerce ID in PayU Latam.
paymentCountry	The processing country in ISO 3166 Alpha-3 format.
cashRedirect	Select true to ensure the correct order flow for cash payments in VTEX. Note: This configuration is essential for merchants processing cash payments with VTEX.

1.4 Click Create.

2. Create the Business Unit

A business unit links the provider configuration with PayU Enterprise API credentials for processing transactions. Follow these steps:

2.1 In the dashboard, go to Configurations > Business Units.

2.2 Click Create Business Unit and enter:

Field	Description
Business Unit Name	Must be lowercase and contain no spaces. This value cannot be changed later, so ensure accuracy.
Description	Optional description.

2.3 In the Choose a Default Provider for This Business Unit section, select the Provider Configuration created in Step 1. Once done, click Create.

3. Create the Webhook

The webhook receives notifications from VTEX when a transaction changes status. Follow these steps:

3.1 In the dashboard, navigate to Configurations > Webhooks.

3.2 Click Create a Webhook Endpoint and enter the appropriate URL based on your environment:

• Test: https://sandbox.api.payulatam.com/vtex-payments-integration/paymentsos/webhook
• Live: https://api.payulatam.com/vtex-payments-integration/paymentsos/webhook

3.3 In the Payment Event Alerts table, enable the Update slider for Authorization and Charge. Then, in the Associated Business Units field, enter the Business Unit created in the previous step. Finally, click Create.

At this point, your PayU Enterprise account using PaymentsOS is fully configured. The next step is configuring the VTEX provider.

2. Configuring the VTEX Provider

Once you have configured your PayU Enterprise account, the next step is to configure the VTEX provider for each payment method. To proceed, you must have a valid user account to access the VTEX admin.

Creating a New Provider

1. In the left panel, select Store Settings > Providers > New Provider:

2. Locate PayU, and select PayUv2:

3. In the connector configuration, install the connector by clicking the Install app button. Then, complete the following fields:

Field	Description
Affiliation name	The name used to identify the Gateway affiliation.
Environment selector	Select the environment for processing transactions. Ensure that all parameters match the selected environment in PayU Enterprise.
Application Key	App ID of the Business Unit.
Application Token	Private API Key of the Business Unit.
Payment capture	Choose how to settle (charge) payments: For a one-step flow, select Automatic capture immediately after payment authorization. For a two-step flow, select Deactivated: Not automatically captured to settle payments upon invoicing. To schedule automatic capture, select Scheduled: Schedules the automatic capture, and define a capture timeframe in hours. For more details, refer to Custom Auto Capture Feature. The default auto-capture timeframe is seven (7) days after approval.
Scheduled time frame in hours for automatic capture	Available when Scheduled: Schedules the automatic capture is selected. Define the automatic capture timeframe (integer values only; no decimals allowed).
Tipo Autorizacion	Choose between one-step and two-step payment flows: For a one-step flow, select Autorización y Captura. For a two-step flow, select Pre-Autorización. Refer to Payment flows for more information.
Public Key	Public API Key of the Business Unit.
Idioma	Select the language for order issuance. Supported languages: Spanish English Portuguese
Expiración pago (días)	Defines the validity period for cash payments. Important: This value must match the Promissory note validity field in the Configure cash payment methods section.
Enable payout split and send payment recipients?	Select No.

4. Click Save to complete the setup.

Configuring Payment Methods

Configure the payment methods that will be displayed on the website during checkout. View the available payment methods.

Configuring Credit or Debit Cards

Depending on your processing country, you can configure the affiliation you created to use credit or debit cards^*. Follow the steps below to add this payment method to your VTEX store.

^* The availability of debit cards depends on your processing country.

1. In the left panel, select Transactions > Payments > Settings. Select the Payment Conditions tab and click the plus icon.

2. Select the payment method you want to add. Payment methods are grouped by type.
   For this example, we select American Express under the Credit Card section.

3. Provide the following details:

• Rule Name (to help you quickly identify): Enter a descriptive name for the payment condition.
• Status: Set the payment condition’s status. You can have only one active payment condition per payment method.
• Process with affiliation: Select the previously configured gateway affiliation.
• Prepaid in full or in installments?: Select Prepaid in full.

4. Click Save. The new payment condition will now be listed in the Payment Conditions tab.

Configuring Co-Branded or Private Label Cards

Co-branded and private label cards are credit cards issued by a store or brand, sometimes in partnership with networks like AMEX, VISA, or MasterCard. Follow these steps to add this payment method to your VTEX store.

1. In the left panel, select Transactions > Payments > Settings. Select the Custom Payments tab.

2. The Custom Payments tab provides five (5) slots for configuring co-branded and private label cards. In this example, we configure the Colombian card Codensa, which is a private label card.
   Click any available box in the Private Labels section.

3. Enter the following card details, maintaining the exact formatting:

• Name: Codensa.
• Description: Codensa
• BIN ranges: 590712-590712
• Acquirer payment code: codensa

Use the table below to configure co-branded and private label cards, you can leave the remaining values with their default input.

Country	Name	Description	BIN ranges	Acquirer payment code
	Argencard	Argencard	501105-532362	argencard
	Cabal	Cabal	60423,60400,589657	cabal
	Cencosud	Cencosud	603493-603493	cencosud
	Naranja	Naranja	589562	naranja
	Shopping	Shopping	603488	shopping
	Codensa	Codensa	590712-590712	codensa

For more details on configuring co-branded and private label cards, visit the VTEX Help Center.

4. Click Save. After creating the custom payment, you will be redirected to the option for creating a Payment Condition. Follow the instructions in the Configuring Credit or Debit Cards section to complete this step.

Configuring Cash Payment Methods

Since cash payments require customers to pay at physical locations, you can configure this payment method in VTEX as promissory notes (Notes Payables).

When you configure a cash payment method, customers are redirected to PayU’s checkout, where they can download the payment voucher and pay it at the corresponding physical location. Follow the instructions below to add this payment method to your VTEX shop.

1. In the left panel, select Transactions > Payments > Settings. Select the Custom Payments tab.

2. In this tab, you have five (5) available slots to configure cash payment methods. In this example, we will set up OXXO, a Mexican cash payment method.
   Click any available box in the Notes Payables section.

3. Provide the following information:

• Name: Use the value listed here in the paymentMethod parameter column. For this example, enter OXXO.
  • Description: Enter a description to display when the customer selects this payment method (optional).
  • Notes Payable Expiration Date: Specify the number of days before the cash payment expires. The default is 7 days. Ensure this value matches the Payment Expiration (days) setting configured in the VTEX affiliation to prevent processing issues.

Leave the remaining fields with their default values.

4. Click Save. Once the custom payment is created, you will be redirected to set up a new Payment Condition. Follow the instructions in the Configuring Credit or Debit Cards section.

Configuring PSE

Prerequisites:

• This payment method is only available for merchants processing in Colombia.
• To offer PSE as a payment method, you must install the PSE App developed by VTEX. If you haven’t done so, go to Account Settings > Applications > App Store and search for Banks for PSE.
  If the app is unavailable in the store, you can request its installation from the VTEX team by submitting a ticket at VTEX Support.
• If you are using a VTEX Legacy integration, VTEX must perform an additional configuration before you can set up this payment method. Contact your VTEX representative or request assistance via VTEX Support.

1. To configure PSE, access the VTEX administration panel and navigate to Store Settings > Payments > Settings > Payment Conditions. Then, follow these steps:

  1.1 Click the + button.

  1.2 Under the Other category, locate PSE.

  1.3 Complete the following fields:

    • Rule Name: Enter a descriptive name to identify this payment method.
    • Process with Affiliation: Select the gateway affiliation configured to process payments with PayUV2.
    • Status: Activate the payment condition.

  1.4 Click Save to apply the settings.

2. Configure the Banks for PSE app with your PayU credentials by following these steps:

  2.1 Log in to the VTEX administration panel and go to Apps > Installed Apps > Banks for PSE.

  2.2 Complete the form and click Save.

Field	Description
Connector Used to Process the PSE	Select PayUv2 from the dropdown list.
Application Code	Enter the Business Unit Private API Key. This information is available in the PayU Enterprise Control Panel, as explained here. Note: This field corresponds to the Application Token of the VTEX affiliation.
Application Key	Enter the ID of the Business Unit Application. This information is available in the PayU Enterprise Control Panel, as explained here. Note: This field corresponds to the Application Key of the VTEX affiliation.

• Once the configuration is complete, you can process transactions in a production environment with PSE.

Testing the Integration

Once you have configured the payment conditions for your payment methods, it is strongly recommended to test your integration before processing real transactions.

Prerequisites for Successful Testing:

• Ensure your PayU Enterprise account is in TEST mode.
• Verify that the Environment Selector in your VTEX Gateway Affiliation is set to TEST mode.
• Use the appropriate test credentials when setting up the VTEX Gateway Affiliation. You can find the test credentials here.
• After completing your tests, update the configuration with production information, including your PayU Enterprise account, environment selector in VTEX affiliation, and credentials.

Steps to Perform a Test Transaction

1. In the VTEX admin panel, click VISIT STORE in the top menu.

   

2. The store configured for your VTEX account opens. Select any product and proceed to purchase.

   

3. In the shopping cart, click the Place Order button.

   

4. In the payment section, the available payment methods appear grouped by type. Select the one you want to test and enter the test data. You can find test card numbers and relevant information here.
   Finally, click Complete Purchase.

   

Verifying the Transaction

Once the purchase is approved, you can verify the transaction in the following locations:

• VTEX Admin: Navigate to Payments > Transactions.

  

• PayU Enterprise Dashboard: Go to Payments > Search.

  

  Note

  The parameter External Transaction ID within Transaction Activity corresponds to the Order ID in PayU.

• PayU Management Panel: Check the transaction in the Sales Report module.

  

• Queries API: Use the External Transaction ID as the OrderID parameter.

Testing Two-Step Flows

If your Gateway Affiliation is configured to process transactions using a two-step flow, the funds authorized on the credit card are not settled until you explicitly request the settlement. To complete the settlement, you must invoice the order.

Steps to Invoice an Order

1. Locate the transaction in VTEX Admin under Payments > Transactions, and click on it.
   Then, click the Order button at the top right corner.

   

2. Scroll down to the Package section and click Invoice Package.

   

3. Enter the invoice details and click Send Invoice.
   Once the invoice is sent to the customer, the authorized amount is charged from the customer’s card.