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.
Copy and save the secret key displayed, as it cannot be viewed again.
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.
Valid that the connector mode and keys entered correspond to the desired operation mode Test if testing is required, Live/Production to start operation and receiving payments in 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 email@example.com
Once installed the application will be displayed in the Installed Apps section along with the connector:
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.
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:
Enter Storefront > Checkout
Click on the configure button (gear icon)
In the next screen select the Checkout tab
Enter the GTM Container ID (which has a format like this GTM-XXXXXXXX)
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.
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.
Don't forget to change the mode of your Gateway Affiliation to Live/Production and update the Client ID, Client Secret, Webhook signing secret fields with the production values.
Was this article helpful?
Thank you for your feedback! Our team will get back to you