Implementation Guide
Checkout is currently available in two modes:
Embedded mode
Pop-Up Mode
Most of the settings are the same for both modes, however, if you decide to implement the embedded mode, please have a look at this section Embedded mode implementation specifics
For production release, you will need to add our production checkout to your HTML pages. You can do this by using this script tag:
If you do not add the "env": "live" attribute in your script, it will remain a test environment by default.
This will load the configuration for your specific account with the production gateway. This means that all payments and orders will be real. If you simply want to test something for yourself without real orders, you can use this script with "env": "test".
You can find the apiKey in the Ventrata dashboard under the Web Checkout section:
Please note, that each layer of our flow is optional. Only the presence of an apiKey in one of the elements on the page is required. It is recommended to use it as suggested in the How to Integrate our Checkout section.
Ventrata Checkout has a sophisticated customisation flow. Each user can have a general - apiToken wide - configuration in the cloud. Such a configuration can be used as a template for any checkout without additional specification of colours, Google Analytics, etc. Such configuration is managed via our Ventrata dashboard or via specific customer support requests.
Additionally, any page element can have a different configuration and serve as a pop-up trigger. This means you can load the configuration (like language, option, currency, etc) and trigger a pop-up with it.
The configuration flow is as follows:
Cloud > Script Tag > specific page element (button, anchor …)
The flow begins with the most general and proceeds to the most specific. At each step, the final configuration is merged or overwritten by a more specific configuration.
Example: Let's say you have a button colour set to #AE8173 in the cloud. Then you have a page where the script tag will use button colour #820857. This means that this particular page will have all your checkout pop-ups with colour #820857 and not the one from the cloud.
Now let's say you have 3 pop-up triggering buttons on this page. All of them have the aforementioned colour #820857. But you want to have a different colour - #6FD316 - on the last button. After you set this, it means that only this one button will be set to have #6FD316. The other two will use the colour from the script tag. If you remove the colour from the script tag, the first 2 buttons will default to a colour from your cloud. The last button is unaffected.
For practical examples, visit this JSFiddle link and see the flow for yourself.
Button elements are preferred because of their natural semantic correctness.
There are two ways to configure checkout to display:
Static analysis
-------- using the ventrata-checkout attribute on HTML element for Pop-up mode
-------- using the ventrata-embedded-widget attribute on HTML element for Embedded mode
Dynamic execution via a global Javascript function called Ventrata
To offer checkout to your customers, you need to add ventrata-checkout or ventrata-embedded-widget to the HTML element of your choice. In case of ventrata-checkout, it is preferrable to have this attribute on the button element. But it can also be an anchor or simply a div. It really depends on your needs.
Example: Using the below, the checkout will be displayed with the specified product, with the predefined language set to English.
Our checkout is directly fully compatible with any Javascript-based integration. So, in theory, you don’t need any visible HTML element as a trigger. You can just react to events - for example, if you have a 3rd party application and it fires the event you are looking for. Or just show the pop-up automatically, for example, when the user scrolls to a specific area on your page.
It provides the same flow and supports the same parameters as static analysis. Only the format is different. It can be called as shown in comparison 1:1 with the static analysis example:
An example of the dynamic execution with the embedded mode can be found here.
The usage of embedded mode differs in setup requirements, which have more requirements to fulfil.
To successfully enable embedded mode, you will need an HTML element on your page, which will serve as a container for the widget. The HTML element needs the ventrata-embedded-widget attribute to trigger the functionality. This element supports the same setup flow as discussed in the above. For a list of supported configuration inputs, visit this section.
What is really important is to use embedded: true and productID in your configuration setup.
Please note that you do not have to use the specific height and width values used in class="h-[50rem] w-[31.25rem]" but rather ones to fit your web page.
Example:
Multi-booking is an application flow, where your users are able to add multiple products to the cart. It allows you to have a fully managed shopping cart flow through our application or just provide an edit action for already created bookings within the order.
For a full description of this flow, please refer to Multi-Booking.
If you set both lang & currency in your data-config, the globe icon for selecting language and currency will be disabled and hidden, as the language and currency are pre-selected by default. Such a combination is works with the multibooking flow where your page has your own cart and you would like to use our edit flow.
These will work, but will no longer be actively supported, please use showRemainingSeats attribute instead.
Ability to customise colours according to brand.
LIGHT mode or DARK mode is supported.
Use hex values such as #336699.
By default, LIGHT mode is set and you can simply change just the PRIMARY colour by adding the “theme” attribute:
If you would like to use more complex settings, add it as a javascript object:
To support ‘light’ or ‘dark’ mode, use "defaultTheme": "dark".
More complex settings:
For better external integration the checkout application currently supports these events:
USAGE
USAGE
USAGE
USAGE
USAGE
USAGE
USAGE
USAGE
For practical examples visit this JSFiddle link.
If you would like to implement check-in page (manage my booking) into your website, please follow this page.
Embedded mode
Pop-Up Mode
Most of the settings are the same for both modes, however, if you decide to implement the embedded mode, please have a look at this section Embedded mode implementation specifics
How to Integrate our Checkout
For production release, you will need to add our production checkout to your HTML pages. You can do this by using this script tag:
<script src="https://cdn.checkout.ventrata.com/v3/production/ventrata-checkout.min.js" type="module" data-config='{"apiKey":"<YOUR_API_TOKEN>", "env": "live" }'></script>
If you do not add the "env": "live" attribute in your script, it will remain a test environment by default.
This will load the configuration for your specific account with the production gateway. This means that all payments and orders will be real. If you simply want to test something for yourself without real orders, you can use this script with "env": "test".
<script src="https://cdn.checkout.ventrata.com/v3/production/ventrata-checkout.min.js" type="module" data-config='{"apiKey":"<YOUR_API_TOKEN>", "env": "test" }'></script>
Where to Find the apiKey
You can find the apiKey in the Ventrata dashboard under the Web Checkout section:
Please note, that each layer of our flow is optional. Only the presence of an apiKey in one of the elements on the page is required. It is recommended to use it as suggested in the How to Integrate our Checkout section.
Layered configuration
Ventrata Checkout has a sophisticated customisation flow. Each user can have a general - apiToken wide - configuration in the cloud. Such a configuration can be used as a template for any checkout without additional specification of colours, Google Analytics, etc. Such configuration is managed via our Ventrata dashboard or via specific customer support requests.
Additionally, any page element can have a different configuration and serve as a pop-up trigger. This means you can load the configuration (like language, option, currency, etc) and trigger a pop-up with it.
The configuration flow is as follows:
Cloud > Script Tag > specific page element (button, anchor …)
The flow begins with the most general and proceeds to the most specific. At each step, the final configuration is merged or overwritten by a more specific configuration.
Example: Let's say you have a button colour set to #AE8173 in the cloud. Then you have a page where the script tag will use button colour #820857. This means that this particular page will have all your checkout pop-ups with colour #820857 and not the one from the cloud.
Now let's say you have 3 pop-up triggering buttons on this page. All of them have the aforementioned colour #820857. But you want to have a different colour - #6FD316 - on the last button. After you set this, it means that only this one button will be set to have #6FD316. The other two will use the colour from the script tag. If you remove the colour from the script tag, the first 2 buttons will default to a colour from your cloud. The last button is unaffected.
For practical examples, visit this JSFiddle link and see the flow for yourself.
Button elements are preferred because of their natural semantic correctness.
How to Display the Checkout after the Element is Clicked (Pop-up & Embedded)
There are two ways to configure checkout to display:
Static analysis
-------- using the ventrata-checkout attribute on HTML element for Pop-up mode
-------- using the ventrata-embedded-widget attribute on HTML element for Embedded mode
Dynamic execution via a global Javascript function called Ventrata
Static Analysis
To offer checkout to your customers, you need to add ventrata-checkout or ventrata-embedded-widget to the HTML element of your choice. In case of ventrata-checkout, it is preferrable to have this attribute on the button element. But it can also be an anchor or simply a div. It really depends on your needs.
Example: Using the below, the checkout will be displayed with the specified product, with the predefined language set to English.
<button
type="button"
data-config='{"productID":"lwdvpS7Z8jmrxZ9TvRVMQ9KrEHPuCwtTT2bS", "lang":"en", "referrer": "hilton.com" }'
ventrata-checkout
>
Book Now
</button>
Dynamic Execution via Global Function Ventrata
Our checkout is directly fully compatible with any Javascript-based integration. So, in theory, you don’t need any visible HTML element as a trigger. You can just react to events - for example, if you have a 3rd party application and it fires the event you are looking for. Or just show the pop-up automatically, for example, when the user scrolls to a specific area on your page.
It provides the same flow and supports the same parameters as static analysis. Only the format is different. It can be called as shown in comparison 1:1 with the static analysis example:
window.Ventrata({
"productID":"lwdvpS7Z8jmrxZ9TvRVMQ9KrEHPuCwtTT2bS",
"lang":"en",
"referrer": "hilton.com"
})
An example of the dynamic execution with the embedded mode can be found here.
Embedded Mode Implementation Specifics
The usage of embedded mode differs in setup requirements, which have more requirements to fulfil.
To successfully enable embedded mode, you will need an HTML element on your page, which will serve as a container for the widget. The HTML element needs the ventrata-embedded-widget attribute to trigger the functionality. This element supports the same setup flow as discussed in the above. For a list of supported configuration inputs, visit this section.
What is really important is to use embedded: true and productID in your configuration setup.
Please note that you do not have to use the specific height and width values used in class="h-[50rem] w-[31.25rem]" but rather ones to fit your web page.
Example:
<script
src="https://cdn.checkout.ventrata.com/v3/production/ventrata-checkout.min.js"
type="module"
data-config='{"apiKey":"<YOUR_API_TOKEN>", "env": "test", "embedded": true }'>
</script>
...
SITE CONTENT
...
<aside
class="h-[50rem] w-[31.25rem]"
ventrata-embedded-widget
data-config='{"productID":"5789d12f-029c-42f3-80af-8223379d1816" }'
>
</aside>
Multi-booking
Multi-booking is an application flow, where your users are able to add multiple products to the cart. It allows you to have a fully managed shopping cart flow through our application or just provide an edit action for already created bookings within the order.
For a full description of this flow, please refer to Multi-Booking.
Supported Configuration Inputs
Input | Description |
---|---|
lang | optional, lower case, for example, en, cs |
currency | optional, upper case, for example, USD, EUR, CZK |
If you set both lang & currency in your data-config, the globe icon for selecting language and currency will be disabled and hidden, as the language and currency are pre-selected by default. Such a combination is works with the multibooking flow where your page has your own cart and you would like to use our edit flow.
Input | Description |
---|---|
env | optional, live OR test ; if left empty checkout defaults to test |
apiKey | ❗ mandatory (needs to be defined at least once per script import); available via the dashboard, see Where to Find the apiKey. For more info see Layered configuration. |
embedded | optional, by default set to false; it allows the usage of embedded mode. The page needs the presence of an HTML element with the ventrata-embedded-widget attribute. The setup is discussed here. |
multibooking | optional, by default set to false; it allows the usage of a cart (having multiple bookings for the same order). It will trigger the bottom bar, which informs users about the current order content. The Multi-booking flow is described here. |
productID | optional, ID of the product. If not set, product list will be shown. |
optionID | optional, ID of the option |
bookingID | optional, ID of the booking; used only for multibooking edit flow). Its presence needs to be paired with** orderID . |
orderID | optional, ID of the order; used only for multibooking edit flow). Its presence needs to be paired with bookingID . |
checkMarketingConsent | optional, by default set to false; if set to true, marketing consent will be pre-selected for users during contact form flow |
referrer | optional, string value, for example, hilton.com |
page | string, optional, by default empty; how to trigger checkout with a specific page; use only in a combination with orderID, supported values: [”checkout”]. Example here: {"page": "checkout"} |
Checkout feature list
Input | Description |
---|---|
features | optional, object |
features: {
promoAndGiftCardInput: boolean; // by default set to true
showRemainingSeats: boolean; // by default set to false
bottomBar: boolean; // by default set to true
waitlistsAllowed: boolean; // by default set to false
quotesAllowed: boolean; // by default set to false
openGiftFlow: boolean; // by default set to false
disableGiftAmountInput; // by default set to false
}
Deprecated Attributes
Input | Description |
---|---|
hideAvailability | optional, by default set to false; displays remaining seats in time slots. |
These will work, but will no longer be actively supported, please use showRemainingSeats attribute instead.
Color Themes
Ability to customise colours according to brand.
LIGHT mode or DARK mode is supported.
Use hex values such as #336699.
By default, LIGHT mode is set and you can simply change just the PRIMARY colour by adding the “theme” attribute:
data-config='{"productID":"XXX", "apiKey":"XXX", "theme": "#6FD316" }’
If you would like to use more complex settings, add it as a javascript object:
To support ‘light’ or ‘dark’ mode, use "defaultTheme": "dark".
data-config='{"productID":"XXX", "apiKey":"XXX", "defaultTheme": "dark" }’
More complex settings:
{
defaultTheme: "dark", // only "light" and "dark"
theme: {
light: {
"theme-color": "#ffffff", // color of the background
primary: "#F11D46",
"text-primary": "#000000",
"text-secondary": "#767676",
"text-disabled": "#C2C2C2",
"gradient-A": "#A41256", // composite color for hover/active/focus effects on button
"gradient-B": "#5E0864", // composite color for hover/active/focus effects on button
backdropOpacity: "0.25", // adjust backdrop opacity (values between 0-1)
},
dark: {
"theme-color": "#1c1c1c", // color of the background
primary: "#f84b4b",
"text-primary": "#ffffff",
"text-secondary": "#D1D1D1",
"text-disabled": "#6b6b6b",
"gradient-A": "#c4005d", // composite color for hover/active/focus effects on button
"gradient-B": "#8c1a8c", // composite color for hover/active/focus effects on button
backdropOpacity: "0.75", // adjust backdrop opacity (values between 0-1)
},
}
}
Custom Events
For better external integration the checkout application currently supports these events:
Event | Description |
---|---|
ventrata-order-created | fires after order creation with order id as event detail |
USAGE
document.addEventListener('ventrata-order-created',
(event) => {
alert(`ventrata order created with ID :${event.detail.id}`)
}
)
Event | Description |
---|---|
ventrata-order-updated | fires after the order is updated with order id as event detail |
USAGE
document.addEventListener('ventrata-order-updated',
(event) => {
alert(`ventrata order with ID :${event.detail.id} was updated`)
}
)
Event | Description |
---|---|
ventrata-order-confirmed | fires after the order gets confirmed (set as paid) with order id as event detail |
USAGE
document.addEventListener('ventrata-order-confirmed',
(event) => {
alert(`ventrata order with ID :${event.detail.id} was successfully paid`)
}
)
Event | Description |
---|---|
ventrata-order-expired | fires after the order expires with order id as event detail |
USAGE
document.addEventListener('ventrata-order-expired',
(event) => {
alert(`ventrata order with ID :${event.detail.id} expired`)
}
)
Event | Description |
---|---|
ventrata-booking-created | fires after booking creation with booking id as event detail |
USAGE
document.addEventListener('ventrata-booking-created',
(event) => {
alert(`ventrata booking created with ID :${event.detail.id}`)
}
)
Event | Description |
---|---|
ventrata-booking-updated | fires after booking is updated with booking id as event detail |
USAGE
document.addEventListener('ventrata-booking-updated',
(event) => {
alert(`ventrata booking updated with ID :${event.detail.id}`)
}
)
Event | Description |
---|---|
ventrata-booking-removed | fires after booking is removed with booking id as event detail |
USAGE
document.addEventListener('ventrata-booking-removed',
(event) => {
alert(`ventrata booking removed with ID :${event.detail.id}`)
}
)
Event | Description |
---|---|
ventrata-bottom-bar-visibility | fires when bottom bar is shown or hidden |
USAGE
document.addEventListener('ventrata-bottom-bar-visibility',
(event) => {
alert(`bottom bar visibility is ${event.detail.visible}`)
}
)
For practical examples visit this JSFiddle link.
Manage my Booking (Check-in Page)
If you would like to implement check-in page (manage my booking) into your website, please follow this page.
Updated on: 09/05/2024
Thank you!