VTEX integration

What is VTEX?

VTEX is an e-commerce platform and cloud commerce solution that enables businesses to create and manage highly customized and scalable online stores. This platform offers a wide range of features and tools for product management, payment processing, logistics, and personalized shopping experiences. VTEX is used worldwide and is known for its focus on omnichannel and ability to adapt to the needs of businesses of all sizes and industries.

VTEX Integration Guide

To integrate Zenkipay with the VTEX platform, you need to follow the steps below:

1 - Register an account

It is necessary to have a Zenkipay merchant account to perform the integration. In the following link you can find in detail the steps to follow to open your account: Open a merchant account.

2 - Site integration

Once you have registered your account, select the Integration with Plugins or API option displayed on the main page.

3 - Scan your website URL

Enter in the text box the URL of your site so we can offer you the best option based on the technology you are using.

4 - Select the platform of interest

Zenkipay will offer you the best option once it has scanned your site, however, you are free to select the option that best suits your needs.

For VTEX merchants it will show you the following option:

5 -Integration keys

Once the platform is selected, you will see a new screen where the integration keys will be displayed, these will be used later in the VTEX portal for the configuration of the payment connector.

• Client ID: Unique application key
• Client Secret: Confidential secret key to authenticate the application.
• VTEX Account Name: The merchant identifier in the VTEX system, must match the Account name of your VTEX store.

You can also decide if you want to perform a series of tests once your store is synchronized, which will be reflected in step 3 of the integration flow.

These integration keys must be entered in the configuration screen of your VTEX store.

Once you have entered the VTEX Account Name you must click on the "Generate signing secret" button, then the signing secret will be generated.

• Signing secret: Signature of the webhook to validate the origin of the notifications in your VTEX store.

6 - Installation

6.1 - VTEX Application Key

• Inside your VTEX store administration portal, select the Account Settings > Account Management > Application Keys option and click on the Manage my keys button.

• Click on the + Generate New button

• Type the name you want to give to your key and click on the + Add Roles button, select the roles with Administrator permissions, and click on the Generate button.

• Search and select the roles to access the keys, they must have an Administrator level for the correct functioning.
• Click on the Add Roles button

• Click on the Generate button

• The key and secret key will be created.

6.2 - Payment connector configuration

• Within your VTEX merchant administration portal, select the Transactions > Payments > Settings option.

• Select the Gateway Affiliations option and click on the + icon.

• Select the Zenki payment connector at the bottom of the list

• The payment connector configuration screen will be displayed where you must enter the data generated from the Zenkipay gateway and the previous step:
  • Application key: Key generated from the Application keys option of your store.
  • Application token: Application token generated from the Application keys option of your store.
  • Client ID: Corresponds to the client ID shown in the Zenkipay portal.
  • Client Secret: Corresponds to the client's secret key displayed in the Zenkipay portal.
  • Webhook signing secret: Corresponds to the secret signature generated in the Zenkipay portal with the account name of your store.

• Click on the Save button
• Select the Payment Conditions option and click on the + button.

• Find the Zenkipay - Pay with Crypto option and select it.

• The following screen will appear where you must enable it and click the Savebutton:
  • Status: Enable the Active option

6.3 - Installing the Payment App

To install the Zenkipay payment app in VTEX it is necessary to execute the following command in the VTEX IO CLI:

• vtex install zenkipartnermx.zenkipay@0.2.0

Once installed the application will be displayed in the Installed Apps section along with the connector:

• zenkipartnermx.zenki
• zenkipartnermx.zenkipay

6.4 - Google Tag Manager (GTM) configuration

For your VTEX store to work properly with Zenkipay, additional data is required and is obtained through Google Tag Manager (we recommend creating a dedicated account for VTEX integration with Zenkipay to avoid possible conflicts with other containers).

Once inside the Container and the Workspace is selected (the default one can be used), a Ttrigger and a Tag must be configured.

6.4.1 - Configure Trigger

• Select event type: Custom Event
• Event name: .*
• Check the checkbox for the option Use regex matching
• Select the Some custom events option for the option This trigger fires on.
• Set condition: Event -> contains -> payment

6.4.2 - Configure Tag

• Tag type: Custom HTML
• Add next script
• Link previously configured Trigger

<script>
  $( document ).ready(function() {
  setTimeout(function(){    
    console.log('GTM Zenkipay')    
    $("#payment-group-ZenkipayPaymentGroup > .payment-group-item-text").text("Zenkipay - Pay with Cripto");
    $(".ZenkipayPaymentGroup").empty()
    $(".ZenkipayPaymentGroup").append('<iframe style="width: 100%;height: 593px;border: none;margin: auto;" src="https://vtex-layout-checkout.zenki.fi/"></iframe>')    
  }, 1000)
  });
</script>

6.4.3 - Configure Google Tag Manager into VTEX

Once the configuration process in Google Tag Manager is finished, it will be necessary to copy the GTM Container ID inside the VTEX storefront, for this we will follow the following steps:

1. Enter Storefront > Checkout
2. Click on the configure button (gear icon)
3. In the next screen select the Checkout tab
4. Enter the GTM Container ID (which has a format like this GTM-XXXXXXXX)
5. Click on Save

6.5 - Hook configuration to apply Crypto Love discount

In order to apply the Crypto Love discount (if enabled) to the paid orders, it is necessary to configure a hook in the VTEX store. In order to apply this discount and have the numbers match on both platforms, it is necessary that the status of the order in VTEX changes to "handling" and also that VTEX notifies Zenkipay when this status change happens (this is the function of the hook) to apply the discount.

For this you have to consume a VTEX API service, in this link, you can find the official documentation.

POST https://{accountName}.{environment}.com.br/api/orders/hook/config

{
	"filter": {
		"type": "FromWorkflow",
		"status": ["handling"]
	},
	"hook": {
		"url": "https://vtex-connector.zenki.fi/order-updates/hook",
		"headers": {
			"x-zenki-client-id": "value",
			"x-zenki-client-secret": "value"
		}
	}
}

Where the "value" values, should be replaced with the integration keys obtained from the Zenkipay portal.

7 - Testing

Once your store is integrated you will be able to make test purchases, which will be reflected in the following screen.

You can also skip testing if you wish and click "Next" to finish the integration flow.

8 - Go Live

At the end of the integration flow, a screen like the one in step 5 will be displayed, but with the production keys, in this screen, you must enter again the name of the VTEX account to generate the productive Secret Signature.