VTEX 🅱️

November 07, 2024

Accept payments for your products and services with the Kushki’s plugin in your VTEX store.

Considering the growth reached by VTEX in the industry, Kushki has developed a plugin that allows you to receive and make payments with credit card, debit card, cash, and transfers. This platform is used in around 38 countries worldwide, with approximately 3.200 active stores.

Through this platform, your customers can enter their payment details and finish their purchase without leaving VTEX. Kushki’s plugin integration is available for your customers in Chile, Colombia, Ecuador, Mexico, and Peru.

Get to know the integration and configuration details, by following the steps detailed below.

In Colombia, our customers can enable the following services:

1. Credentials Generation

1.1. Requirements

Sign up and get Kushki products and services: Complete this form to include the best payment solutions on the market in your VTEX store and use our plugin. A sales representative will contact you to enable your account and provide you with the credentials with which you can integrate this plugin.

1.2. Assignment of the domain of your store

To integrate the Kushki’s plugin, it is necessary that you generate the credentials and the public and private merchant ID that will be associated with your merchant. This process can be performed through the UAT test environment of your merchant. We will evaluate your request.

Perform the following steps:

1.2.1. Login to the Kushki’s test account (UAT) or your Production account with your user and password, then select Login.
1.2.2. In the side menu, select the Settings module.
1.2.3. Select Plugins in the Integrations section.
1.2.4. Select the VTEX plugin.

1.2.5. In the Integration form, enter the name of the VTEX Domain you want to integrate the plugin.
1.2.6. Click on Save. There you go! Your domain has been successfully created. Once you have clicked it, the system will show you the Public and private key information of your merchant.

The following video will show you the step-by-step process that you must follow on your UAT test account; however, it also applies to your production account.

Additionally, it is important to keep in mind that:

• You can update your merchant’s domain, and keep the public and private merchant ID associated with it: To do so, you just require to modify your merchant’s name in the VTEX Domain field, by following the steps from the video below:

• The system will validate that the domain has not been used before, and it will notify you. In this case, you will have to create a different domain to the one used by the other merchant.

2. Integration and Configuration

2.1. Enabling Kushki’s plugin in the VTEX store

Follow the steps below to enable the Kuski’s plugin in the VTEX store.

2.1.1. Login to the VTEX platform.
2.1.2. In the main side menu, select the Store Settings icon ⚙️, which is located at the bottom of the screen.
2.1.3. In PAYMENT, choose Providers.
2.1.4. In the Providers screen, click on the New Provider button.
2.1.5. Select the connector according to the payment method you will configure: Kushki-cash, Kushki-TRANSFER, or KushkiCard.

2.1.6. For the chosen payment method, complete each of the Provider Authorization fields:
2.1.6.1. App key: VTEX application Key
2.1.6.2. App token: VTEX application Token.

2.1.7. For the chosen payment method, complete the Name field of Basic Information section.
2.1.8. For the chosen payment method, check/uncheck the boxes of the Payment Control section:
2.1.8.1 Enable test mode uncheck the box to activate the connector.
2.1.8.2. Enable payout split and sending payment recipients (for card): enabling the VTEX platform to automatically send invoices. This setting is not available; for this reason, please uncheck the box.

2.1.9. For the chosen payment method, complete each of the Provider Fields
2.1.9.1. Country-Kushki: the country where the payment method will be enabled. For transfers, please enter one of the following codes according to the country you are setting:

• Colombia: COL
  
• Chile: CHL
  
• Ecuador: ECU
  
• Mexico: MXN
  
• Peru: PER
  

2.1.9.2. Credential ID (production)-Kushki (cash and transfer): identification of Kushki’s production credentials environment.
2.1.9.3. Public Merchant ID (production)-Kushki (cash and transfer) or Public Merchant ID Production (card): public Merchant ID assigned in the production environment of your merchant.
2.1.9.4. Private Merchant ID (production)-Kushki (cash and transfer) or Private Merchant ID Production (card): private Merchant ID assigned in the production environment of your merchant.
2.1.9.5. Credential ID (test)-Kushki (cash and transfer): identification of Kushki’s test environment (UAT) credentials.
2.1.9.6. Public Merchant ID (test)-Kushki (cash and transfer) or Public Merchant ID Test (card): public Merchant ID assigned in the test environment (UAT) of your merchant.
2.1.9.7. Private Merchant ID (test)-Kushki (cash and transfer) or Private Merchant ID Test (card): private Merchant ID assigned in the test environment (UAT) of your merchant.
2.1.9.8. Authorization and Capture deferred payments (card): enabling/disabling of payment processing with authorization and capture for card transactions; which when Yes is selected, will be captured manually by your merchant.

2.1.10. Click on the blue Save button.

2.2. Configure payment conditions

Follow these instructions to add a special payment condition to a Kushki connector according to the payment methods you need to enable in your VTEX store:

2.2.1. Payment Methods

2.2.1.1. Cash

You can configure the payment conditions to receive cash from your customers. Follow the steps below:

2.2.1.1.1. Log in to your VTEX Admin Store.
2.2.1.1.2. Click on Store Settings. ⚙️
2.2.1.1.3. In PAYMENT, choose Settings.
2.2.1.1.4. In the Payment Conditions table, click on “+”.
2.2.1.1.5. Click on Kushki-cash.
2.2.1.1.6. Activate the Kushki-cash payment condition, by sliding the Status button.
2.2.1.1.7. You can also Add Special Conditions, specifying the Expiration Date, the Country where your customer is located, the Trade Policies applied in your store, the Commercial Conditions, and the Commercial Name to which the special conditions apply.
2.2.1.1.8. Click on Save.

2.2.1.2. Transfer

You can configure the payment conditions to receive transfers from your customers.

Follow the steps below:

2.2.1.2.1. Login to your VTEX Admin Store.
2.2.1.2.2. Click on Store Settings. ⚙️
2.2.1.2.3. Go to the PAYMENT section and then choose Settings.
2.2.1.2.4. In the Payment Conditions table, click on “+”.
2.2.1.2.5. Click on Kushki-Transfer.
2.2.1.2.6. In Process with affiliation, select KushkiTRANSFER.
2.2.1.2.7. Activate the payment condition, by sliding the Status button.
2.2.1.2.8. You can also add special conditions, specifying the Expiration Date, the Country where your customer is located, the Trade Policies applied in your store, the Commercial Conditions, and the Account Name to which the special conditions apply.
2.2.1.2.9. Click on Save.

2.2.1.3. Card

You can configure the payment conditions to receive payments through debit or credit cards.

Follow the instructions below:

2.2.1.3.1. Login to your VTEX administration store.
2.2.1.3.2. Click on Store Settings ⚙️.
2.2.1.3.3. Go to the PAYMENT section and then choose Settings.
2.2.1.3.4. In the Payment Conditions table, click on “+”.
2.2.1.3.5. Look for the payment condition of the Card Franchise with which you will receive payments for this payment method.

2.2.1.3.6. In Process with affiliation, choose the KushkiCards connector.
2.2.1.3.7. Activate the KushkiCards payment condition, by sliding the Status button.
2.2.1.3.8. In Prepaid in full or in installments? you can specify whether or not your merchant will receive deferred payments.

2.2.1.3.8.1. If you select In installments, you must specify the Total number of installments (interval 1-12 or single 1,3,6,12), the value of the Minimum Installment, the Billing method (Beginning of period or End of period), Set Installment Interest rate, and enable Third-party interest rate.

2.2.1.3.9. For the two options (In Installments or Prepaid in full), you can also Add special conditions, specifying the Expiration Date, the Card Issuer, the Trade Policy that applies in your store, the Commercial Conditions, and the Account name to which the delimited special conditions apply.
2.2.1.3.10. Click on Save.

2.2.2. Connector customization

If you need to customize the name of the Kushki connectors you have configured in your store to receive payments with different payment methods, you can do so with the following steps:

2.2.2.1. Log in to your VTEX admin store.

2.2.2.2. Click the Store Settings icon ⚙️.

2.2.2.3. Go to the STOREFRONT section, and then select Checkout.
2.2.2.4. Select your store website by clicking on the settings icon 2.2.2.5 Go to the Code tab. In Files, select checkout6-custom.css.
2.2.2.6. Add two lines of code to customize the Kushki payment connectors you have set up. You can use the following examples:

2.2.2.6.1. Transfer connector

/* /files/checkout5-custom.css */

[id="payment-group-kushki - TransferPaymentGroup"] span {display: none;}
[id="payment-group-kushki - TransferPaymentGroup"]:after {content: "XXX";}

2.2.2.6.2. Cash connector

/* /files/checkout5-custom.css */

[id="payment-group-kushki - CashPaymentGroup"] span {display: none;}
[id="payment-group-kushki - CashPaymentGroup"]:after {content: "XXX";}

2.2.2.7. Click Save to set up these changes.

2.2.3. Add a special payment condition

To add a special condition to one of the connectors, follow the route Store Settings ⚙️> PAYMENT > Settings > Payment Conditions > Select the connector where you require to add a special condition > Choose the + Add special condition option > You will be able to add conditions such as: Expiration date, Card Issuer, Trade Policy, Commercial condition, or Account name.

Once added to the special condition, you will be able to activate it by sliding the Status button to Active. > Click on Save. This configuration will be automatically associated with the connector that has been configured. You will be able to check all the payment conditions for the different payment methods that you have configured in the route Store Settings ⚙️> PAYMENT > Settings> Payment Conditions.

2.2.3.1. Configure the Trade Policies

To configure the Trade Policy, follow the route Main site menu> Store Settings ⚙️> CHANNELS > Trade Policies; and make sure that both the country code and the currency correspond to your merchant’s country.

2.2.3.2. Configure the Shipping Policies

At the same time, we recommend you to check the Shipping Policy, by entering the Main side menu > Shipping icon > Shipping Strategy> Loading Docks, and make sure that the dock corresponds to the country where the merchant is active. To activate, click on the 3 dots icon> select Edit > drag the Sliding Box that shows up in the upper right side of the screen to Activate the selected dock > Click on Save changes.

2.3. Additional configurations

For your store in Colombia, it is necessary to do an additional configuration so that the figures do not contain decimals; in this way, you will avoid inconsistencies in the purchase and the sales process.

The route you should follow to make these additional configurations in VTEX is Store Settings ⚙️> Orders > Settings. In the General option that is available in the Cart section and then in Orders, enter the number 0 (zero) in the field Number of decimal digits to be considered > click on the Save button to successfully apply your changes.

2.4. Kushki app update in your VTEX store

To update the Kushki app in your VTEX store, you will be able to perform one of the following two options:

Option A: Through the command in the VTEX IO CLI

You can also execute a command by using the Command Line Interface VTEX IO CLI.

Make sure to:

1. Validate that you have installed the VTEX IO CLI.
   
2. Use the VTEX IO CLI in your VTEX admin store.
   
3. Run the following command:
   vtex install kushkipartnercl.kushki-app@1.x.
   
4. Validate that the Kushki Payment Authentication Kushki App is installed.

Option B: Through the Kushki app (coming soon)

1. Enter your VTEX app store.
   
2. In the left side menu, select the Apps icon .
   
3. In EXTENSIONS HUB, enter the App Management option.
   
4. Look for the Kushki payment app called Payment Authentication Kushki App.
   
5. On the Settings button, validate that the test environment check box is not selected.
   
6. Click Save.
   

3. Uninstalling

If you need to delete the credentials of your merchant and create a new domain for your store, you can do it through your merchant’s UAT test environment. Then, please notify us about this requirement.

Follow the steps indicated below:

3.1. Login to the Kushki’s test account (UAT) with your user and password, then select Login.
3.2. In the side menu, select the Developers module.
3.3. Click on Credentials.
3.4. Select the Credential ID you want to delete.
3.5. Click on the icon at the right side of the screen (…) and click on Delete.
3.6. Choose Delete again.

Do not forget to notify us about the process you have completed.

If you require, you can generate a new domain for your merchant by following the steps indicated in the credentials generation section.

The following video will show you the step-by-step process on how to delete the credentials associated with your merchant:

In the following video, we show you how to deactivate the credentials of your merchant: