VTEX

This article shows you the procedure to enable PayU on your VTEX website.

VTEX is an enterprise digital commerce platform that allows you to create an online store with out-of-the-box capabilities fast. For more information, refer to official VTEX webpage.

Prerequisites

  • You need an active account in PayU Latam.
  • You need an active account in PaymentsOS. If you don’t have an account, click here to create one.
    All the merchants that require to integrate PayU with VTEX must have a PaymentsOS account in productive/live mode.
  • You require a VTEX account with sufficient rights and permissions to access the VTEX administrative panel. This account must have two-factor authentication enabled.

Configuration procedure

To configure the payment methods in VTEX that our gateway processes, follow the steps below, which include 2 stages. Before proceeding, ensure you have met the prerequisites mentioned above.

1. Configure your PaymentsOS account

Integration of PayU Latam with VTEX occurs via PaymentsOS as a middleware. The initial step involves configuring the following items within PaymentsOS for your account:

  • Provider configuration.
  • Business unit.
  • WebHook.

You can configure the items using one of the following options:

Configure the account using Postman

Follow these steps to configure your account using Postman:

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


  1. After you run the collection, you need to set the globals. Download the globals file here.

  2. In the Postman collection, click Import next to your workspace name and locate the json file recently downloaded.

  3. When finish, click Import.

  4. It is mandatory to run the collection methods in the order displayed. First, click the POST method called 1. Login and go to Body tab.

PrintScreen

  1. Provide the email and password of your PaymentsOS account. Then, click Send.

  2. If the login was successful, the authentication data is set for the second method.
    Click the GET method 2. Retrieve PayU Latam ID.

  3. In the top right corner, click the eye icon and locate the env parameter. Then, click the pencil icon and set test if you are processing in the test environment and live otherwise.

PrintScreen

  1. Once configured, click Send.

  2. Click the POST method 3. Create Provider Configuration, this method creates the Provider Configuration in PaymentsOS. Then, go to Body tab.

PrintScreen

Provide the following information:

Parameter Description
name Provide a to the Provider Configuration.
description Provide a meaningful description for the Provider Configuration.
This value is optional.
configuration_data.apiLogin User 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 ID of the PayU account according to the country where you want to sell.
configuration_data.merchantId ID of your commerce in PayU Latam.
configuration_data.paymentCountry Processing country in format ISO 3166 Alpha-3.
configuration_data.partnerID PayU identifier. Enter ZOOZ_VTEX_V2 as the value.
configuration_data.cashRedirect Send True to ensure proper order flow with cash payment methods in VTEX.
Note: This configuration is important for all merchants that process cash payments with VTEX.
  1. Click the POST method 4. Create Business Unit this method creates the Business Unit in PaymentsOS. Then, go to Body tab.

PrintScreen

Provide the following information:

Parameter Description
id Identifier of the Business Unit. This id must be in lowercase and without blank spaces.
Make sure you have provided the correct value for the id as this cannot be updated later.
description Provide a meaningful description for the Business Unit.
This value is optional.
  1. Click the POST method 5. Create Webhook this method creates the WebHook in PaymentsOS. This WebHook is the confirmation URL that will receive the notifications sent by VTEX when a transaction changes its state.
    Then, go to Body tab.

PrintScreen

Set the endpoint parameter with the following values according to your environment.

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

Leave the other parameters with their default value.

At this point, your PaymentsOS account has been configured as a middleware, the next step is the configuration of the VTEX provider.

Configure the account manually using PaymentsOS dashboard

Follow these steps to configure your account using PaymentsOS dashboard.

  1. Create the Provider configuration.
    In the PaymentsOS dashboard, expand the Account menu, then select Services.

PrintScreen

Use the Search field in the Create a new Provider configuration section and enter PayU to find the PayU Latam provider.

PrintScreen

Provide the following information for the Provider Configuration:

Parameter Description
Configuration Name Provide a name to the Provider Configuration.
Description Provide a meaningful description for the Provider Configuration.
This value is optional.
apiLogin User or login provided by PayU. How do I get my API Login
apiKey Unique key of your commerce. How do I get my API Key
accountId ID of the PayU account according to the country where you want to sell.
merchantId ID of your commerce in PayU Latam.
paymentCountry Processing country in format ISO 3166 Alpha-3.
cashRedirect Select True to ensure the correct order flow with cash payment methods in VTEX.
Note: This configuration is important for all merchants that process cash payments with VTEX.

Once done, click Create.

PrintScreen

  1. Create the Business Unit.
    Back in the PaymentsOS dashboard, expand the Account menu, then select Business Units.

PrintScreen

Click the Create Business Unit button and provide the following information:

Parameter Description
Business Unit Name Name of the Business Unit. This name must be in lowercase and without blank spaces.
Make sure you have provided the correct name as this cannot be updated later.
description Provide a meaningful description for the Business Unit.
This value is optional.

In the Choose a default Provider for this Business Unit section, select the Provider Configuration created in the last step.
When finish, click Create.

PrintScreen

  1. Create the Webhook. This WebHook is the confirmation URL that will receive the notifications sent by VTEX when a transaction changes its state.

Back in the PaymentsOS dashboard, expand the Account menu, then select Webhooks.

PrintScreen

Click the Create a Webhook Endpoint button and provide the URL according to your environment:

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

In the Payment Events Alert table, enable the Update event for Authorization and Charge. Furthermore, select in the Associated Business Units combo the Business Unit created in the last step.
When finish, click Create.

PrintScreen

At this point, your PaymentsOS account has been configured as a middleware, the next step is the configuration of the VTEX provider.

2. Configure the VTEX provider

Once you have configured your PaymentsOS account, the next step is the configuration of the VTEX provider per each payment method. For this step, it is mandatory that you have a valid user to access the VTEX admin.

Configure the Gateway affiliation

Before configuring the Gateway affiliation, make sure you have configured FingerPrint for PayU. To do so, refer to this article.

  1. In the VTEX admin, expand the Payments menu inside Transactions group. Then, select Settings.

PrintScreen

  1. Before configuring the Payment conditions, you must create a new provider. In the left panel, select Store Settings > Providers > New Provider:

PrintScreen

  1. Locate PayU, and select PayUv2:

PrintScreen

  1. In the connector configuration, you must install the connector by clicking the Install app button. Then, provide the following information for the connector.

PrintScreen

Field Description
Affiliation name Name you want to set to identify the Gateway affiliation.
Environment selector Choose the environment where you want to create the transactions.
According to the selection you make here, you must provide the other parameters selecting the same environment in PaymentsOS.
Application Key App ID of the Business Unit.
Application Token Private API Key of the Business Unit.
Payment capture Select how you want to perform the settlement (charge) in your affiliation.
  • For one-step flow, select Automatic capture immediately after payment authorization.
  • For two-step flow, select Deactivated: Not automatically captured to execute the settlement once you invoice the order.
  • Select Scheduled: Schedules the automatic capture to configure a time in hours to automatically capture the order.

For more information about this parameter, refer to Custom Auto Capture Feature in the developers documentation.
The default value for this option is seven (7) days after the approval.
Scheduled time frame in hours for automatic capture This field appears when selecting Scheduled: Schedules the automatic capture as the Payment capture method; select the automatic capture time frame you want to configure according to your own configuration. This value must be integer, thus, no decimals are permitted.
Tipo Autorizacion Choose if your payment transactions are executed in using one-step or two-step flow.
  • For one-step flow, select Autorizacion y Captura.
  • For two-step flow, select Pre-Autorizacion.

Refer to the following link to learn more about the Payment flows.
Public Key Public API Key of the Business Unit.
Idioma Select the language in which you want the system to issue the orders, the supported languages are:
  • Spanish
  • English
  • Portuguese
Expiración pago (días) Refers to the number of days you wish to customize for cash payments.
Important: This value must match the value configured in the payment method in the Promissory note validity field explained in the Configure cash payment methods section of this documentation.
Enable payout split and send payment recipients? Select No for this field.

Once done, click Save.

Configure Payment methods

Configure the payment methods to be displayed on the website for checkout. Consult our available Payment methods.

Configure credit or debit cards.

According to your processing country, you can configure the affiliation you create to use credit or debit cards*. Follow the instructions below to add this payment method to your VTEX shop.

* Debit cards usage depends on your processing country.

  1. In the Settings option (Transactions > Payments > Settings), select the Payment conditions tab and click the plus icon.

PrintScreen

  1. Select the Payment method you want to include. Payments methods are grouped by their type.
    For the sake of our example, we select American Express in the Credit Card section.

PrintScreen

  1. Provide the following information.
  • Rule Name (to help you quickly identify): provide a meaningful name for the payment condition next to the payment method you selected.
  • Status: set the status of the payment condition. You can only have one active payment condition per payment method.
  • Process with affiliation: select the gateway affiliation configured before.
  • Prepaid in full or in installments?: select Prepaid in full*.

PrintScreen

  1. Click Save. When the payment condition has been created, it is listed in the Payment conditions tab.

PrintScreen

Configure Co-branded or Private labels cards.

Co-branded and Private label cards are credit cards issued by an store or brand which can be issued in partnership with a network such as AMEX, VISA, MasterCard, etc. Follow the instructions below to add this payment method to your VTEX shop.

  1. In the Settings option (Transactions > Payments > Settings), go to Custom payments tab.

PrintScreen

  1. In this tab, you have five (5) available space to configure both Co-branded and Private label cards. In this example, we will set up the Colombian card Codensa which is a Private label card.
    Click in any of the available boxes in the Private labels section.

PrintScreen

  1. Provide the following data of the card using the case displayed.
  • Name: Codensa.
  • Description: Codensa
  • BIN ranges: 590712-590712
  • Acquirer payment code: codensa

PrintScreen

The remaining values can be left as default. Use the following values to configure Co-branded and Private label cards.

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 information about how to configure Co-branded and Private label cards, refer to the VTEX Help Center.

  1. Click Save. When the custom payment has been created, you are redirected to the option to create a new Payment conditions. This payment condition is created as explained in Configure credit or debit cards section.
Configure cash payment methods.

As cash payments require that your customer pays in physical offices, you can configure this payment method in VTEX as promissory notes (Notes payables).

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

  1. In the Settings option (Transactions > Payments > Settings), go to Custom payments tab.

PrintScreen

  1. In this tab, you have five (5) available space to configure Cash payments. In this example, we will set up OXXO, a Mexican cash payment method.
    Click in any of the available boxes in the Notes payables section.

PrintScreen

  1. Provide the following data for the cash payment.
  • Name: In this parameter, you need to use the value displayed here in the column paymentMethod parameter. For the sake of our example, set OXXO.
  • Description: Provide the description you want to show when the customer selects this payment method. This parameter is optional.
  • Notes payable expiration date: provide the number of days before the cash payment expires. By default, this value is assigned to 7 days. Keep in mind that, to avoid processing problems, this value must match the value selected in the Payment expiration (days) field that you configured in the VTEX affiliation.

Leave the other parameters with their default values.

  1. Click Save. When the custom payment has been created, you are redirected to the option to create a new Payment conditions. This payment condition is created as explained in Configure credit or debit cards section.
Configure PSE

Prerequisites:

  • This payment method only applies to merchants that have processing in Colombia.
  • To offer PSE as a payment method, you must first make sure to install the PSE App developed by VTEX. If you have not already done so, go to Account Settings > Applications > App Store and search for Banks for PSE.
    In case you cannot find the App in the store, you can request its installation from the VTEX team through a ticket at VTEX Support.
  • In case you have a VTEX Legacy integration, please note that VTEX must perform an additional configuration for you to set up the payment method. Contact your VTEX agent or request help through VTEX Support.
  1. To configure PSE, access the administration panel of your VTEX platform and navigate to Store Settings > Payments > Settings > Payment Conditions. Then, proceed as follows:
  • Click on the + button.
  • Under the Other category, locate PSE.
  • Fill out the fields displayed on the screen:
    • Enter a descriptive name for the rule to identify this payment method.
    • Choose the affiliation configured to process payments with PayUV2 from the Process with affiliation dropdown menu.
    • Activate the payment condition in the Status field.
    • Click Save to apply the settings.


  1. Configure the Banks for PSE app with your PayU credentials. To do so, follow these steps:
  • Login to the administration panel of your VTEX platform and access Apps > Installed apps > Banks for PSE.
  • Complete the form and click Save.
Field Description
Connector Used to process the PSE: Select PayUv2 from the dropdown list.
Application Code Business Unit Private API Key. Remember that this data can be found in the PaymentsOS Control Panel as explained above.
Note: This field is equivalent to the Application Token of the VTEX affiliation.
Application Key ID of the Business Unit application. Remember that this data can be found in the PaymentsOS Control Panel as explained above.
Note: This field is equivalent to the Application Key of the VTEX affiliation.
  • Once you complete the configuration, you can perform transactions in a productive environment with PSE.

PrintScreen

Testing the integration

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

Prerequisites for successful testing:

  • Make sure your PaymentsOS account is in TEST mode.
  • Check that the Environment Selector in your VTEX Gateway Affiliation is in TEST mode.
  • Be sure to use the appropriate credentials for the test environment when you are setting up the VTEX Gateway Affiliation. Remember that you can find the test credentials here.
  • Remember that once you perform your tests, you must modify the above points with the production information (PaymentsOS account, environment selector in VTEX affiliation, and Credentials configured in VTEX affiliation).
  1. In the VTEX admin, click VISIT STORE at the top panel.

PrintScreen

  1. The store configured for your VTEX account opens. Select any product and click purchase.

PrintScreen

  1. In the shopping cart, click the place order button.

PrintScreen

  1. In the payment section, the payment methods appears grouped by their type. Select the one you want to test and enter the test data, find here some test card numbers and information to test status.
    Finally, click in Complete purchase

PrintScreen

Once the purchase has been approved you can check it in:

  • VTEX Admin: Payments > Transactions.

PrintScreen

  • PaymentsOS dashboard: Payments > Search.

    PrintScreen
    The parameter External Transaction ID inside the Transaction Activity is the Order ID in PayU.

  • PayU Module: in the Sales Report module.

PrintScreen

  • Queries API using the parameter External Transaction ID as OrderID.

Testing two-step flows

When you have configured your Gateway affiliation to process transactions in two-step flows, the funds authorized in the credit card are not settled until you explicitly request the settlement. To request the settlement, you need to invoice the order.

To invoice an order, locate the transaction in the VTEX Admin (Payments_ > Transactions) and click it. Then, click the Order button at the top right corner.

PrintScreen

Scroll down to the Package section, and click Invoice package.

PrintScreen

Provide the information of the invoice and click Send Invoice at the end of the panel. Once the invoice is sent to the customer, the amount authorized is charged fom the customer’s card.

PrintScreen

Last modified February 26, 2024: VTEX updates (18bff8dde)