VTEX

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.
• Configure the account manually using PaymentsOS dashboard.

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).

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

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

4. When finish, click Import.

5. 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.

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

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

8. 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.

9. Once configured, click Send.

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

Provide the following information:

11. Click the POST method 4. Create Business Unit this method creates the Business Unit in PaymentsOS. Then, go to Body tab.

Provide the following information:

12. 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.

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.

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

Provide the following information for the Provider Configuration:

Once done, click Create.

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

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

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

3. 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.

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.

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.

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

3. Locate PayU, and select PayUv2:

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

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.

2. 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.

3. 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^*.

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

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.

2. 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.

3. Provide the following data of the card using the case displayed.

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

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.

4. 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.

2. 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.

3. 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.

4. 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.

2. 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.

• Once you complete the configuration, you can perform transactions in a productive 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 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.

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

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

4. 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

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

• VTEX Admin: Payments > Transactions.

• PaymentsOS dashboard: Payments > Search.
  
  
  The parameter External Transaction ID inside the Transaction Activity is the Order ID in PayU.

• PayU Module: in the Sales Report module.

• 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.

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

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.