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 commerces that require to integrate PayU with VTEX must have an account in PaymentsOS.
• You need an account with enough rights and permissions to access the VTEX admin. This account must have enabled the two-factor authentication.

Configuration procedure

The procedure to enable payment methods in VTEX processed by our gateway is divided in two steps. Before moving on, make sure you have meet the prerequisites above.

1. Configure your PaymentsOS account

The integration of PayU Latam with VTEX is performed using PaymentsOS as a middleware. As the first step, you need to configure in PaymentsOS your account the following objects.

• A Provider configuration.
• A Business unit.
• A WebHook.

You can configure these objects 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 for you).

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:

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.

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:

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.

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:

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.

When finish, 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:

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.

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 Payment conditions, you must create an affiliation to our gateway. In the top panel, click Gateway affiliations.

3. Click the plus icon. Scroll down to OTHERS section and locate the PayUv2 connector.

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

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.
Enable payout split and send payment recipients?	Select No for this field.

When finish, 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^*.

^*Processing in installments is not yet supported.

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 seven days.

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.

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. As a prerequisite, make sure your PaymentsOS account is in TEST mode, as well as the Environment selector in your Gateway 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.