📣 UPDATE NOTICE 📣

Please note that we have changed how features related to the gift card functionality are recorded in the script. Please see Gift Cards Feature List below for more information.

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 the Embedded mode implementation specifics section.

Embededded Mode

Pop-up Mode

Integrate Ventrata 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>

📒 NOTE

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. That 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>

Locate Your apiKey

You can find your apiKey in the Ventrata dashboard under the Web Checkout section:

📒 NOTE

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.

📗 TIP
Button elements are preferred because of their natural semantic correctness.

Try out the Ventrata checkout yourself

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 preferable 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"
})

Try Dynamic Execution with the embedded mode

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 Supported Configuration Inputs section.

What is really important is to use embedded: true and productID in your configuration setup.

📒 NOTE

Please note that the height and width values used in class="h-[50rem] w-[31.25rem]" may not be applicable for your web page. Please replace these values with ones that 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.

📒 NOTE

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`

📒 NOTE

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 works with the multibooking flow where your page has your own cart and you would like to use our edit flow.

Input	Default	Mandatory	Description
`env`	by default not set	NO	`live` OR `test` ; if left empty checkout defaults to `test`
`apiKey`	your apiKey MUST be defined	❗YES❗ needs to be defined at least once per script import	available via the dashboard, see Locate Your apiKey. For more info see Layered configuration.
`embedded`	`false`	NO	allows the usage of embedded mode The page requires the presence of an HTML element with the `ventrata-embedded-widget` attribute. The setup is discussed here.
`multibooking`	`false`	NO	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`	by default not set	NO	ID of the product If not set, product list will be shown.
`optionID`	by default not set	NO	ID of the option
`bookingID`	by default not set	NO	ID of the booking (used only for `multibooking` edit flow). Its presence needs to be paired with `orderID`.
`orderID`	by default not set	NO	ID of the order (used only for `multibooking` edit flow). Its presence needs to be paired with `bookingID` .
`checkMarketingConsent`	`false`	NO	if set to true, marketing consent will be pre-selected for users during contact form flow
`referrer`	by default not set	NO	string value, for example, `hilton.com`
`page`	by default not set	NO	string; how to trigger checkout with a specific page; use only in combination with `orderID`, supported values: [”checkout”]. Example here: `{"page": "checkout"}`

Checkout Feature List

We try to accommodate client needs by continuously expanding our checkout's capabilities, recognising the benefits for both our clients and their customers. Feel free to revisit this section as we keep adding new features to the list.

Checkout features can be added to your Ventrata checkout solution by doing one of two things:

Update Data-Config Attribute - by adding the below piece of code, replacing the featureName with the name of one of the supported features and specifying its value, see feature table below.

📗 TIP
If you wish to include multiple features, include all of them in the same feature object.
```
"features": {
     "featureName": value, 
     "featureName1": value
}
```

Add feature to Script or Button - add the feature to your data-config for script or button in the following format:

📗 TIP
If you wish to include multiple features, include all of them in the same feature object, each feature separated by a comma.
```
<script src="https://cdn.checkout.ventrata.com/v3/production/ventrata-checkout.min.js" type="module" data-config='{"apiKey":"<YOUR_API_TOKEN>", "features": { "featureName": value, "featureName1": value } }'></script>
```

Ventrata checkout supports the following features:

Feature	Default	Available Values	Description
`promoAndGiftCardInput`	`true`	`true` / `false`	displays a field to enter promo or gift card code
`showRemainingSeats`	`false`	`true` / `false`	displays the number of remaining seats for the tour
`bottomBar`	`true`	`true` / `false`	displays a bar at the bottom of the screen when multiple bookings are made in one order
`waitlistsAllowed`	`false`	`true` / `false`	enables the Waitlists functionality, a mechanism for guests to express interest in booking a tour on dates that are currently sold out
`quotesAllowed`	`false`	`true` / `false`	enables the Quotes functionality, which allows customers to postpone payment and review a booking without commitment
`timePickerType`	by default not set	`select`	transforms the time selection interface from individual buttons to a dropdown menu; this feature is a prerequisite to the showTourGroupsHeadlines feature
`showTourGroupsHeadlines`	`false`	`true` / `false`	organise timeslots into distinct tour groups, each with its own headline; to use this feature, make sure include the timePickerType: select first
`openGiftFlow`	`false`	`true` / `false`	allows the purchase of gift cards via web checkout; 📣 PLEASE NOTE THAT WE HAVE CHANGED HOW GIFT CARDS FEATURES ARE RECORDED IN THE SCRIPT, SEE GIFT CARDS FEATURE LIST BELOW 📣
`disableGiftAmountInput`	`false`	`true` / `false`	disables the ability to adjust the per unit price of the gift card; 📣 PLEASE NOTE THAT WE HAVE CHANGED HOW GIFT CARDS FEATURES ARE RECORDED IN THE SCRIPT, SEE GIFT CARDS FEATURE LIST BELOW 📣
`viewModeMap`	by default not set	`"cross-sell": "popup"` / `"upgrade": "popup"` / `"questions": "popup"` / `"pickups": "popup"`	enables the switch from embedded mode to pop-up mode on the specified checkout page
`preselectFirstUnit`	by default not set	`true` / `false`	automatically preselects the first unit of the product with a default count of 1.

📣 Gift Cards Feature List

Due to the introduction of numerous new features related to the Gift Cards functionality, we have decided to optimise how gift card features are recorded in the checkout script.

While we will maintain backwards compatibility with the existing structure, we recommend that you gradually transition to the new syntax. The new syntax contains the gifts feature in the features object. All gift sub-features are then recorded under the gifts object. This change affects the above openGiftFlow and disableGiftAmountInput features.

📗 TIP

Learn more in our Gift Card article.

Feature	Sub-feature	Default	Available Values	Description
`gifts`	by default not set			contains sub-features to modify the behaviour of the gift cards functionality
	`allowed`	`true`	`true` / `false`	when enabled from the dashboard, this feature may appear in the script
	`mode`	by default not set	`simple`	default mode is the standard mode where the process begins with the selection of a product before proceeding to the gift card flow, as it is the default mode, it does not have to be defined in the script; simple mode allows the purchase of a standalone gift card without selecting a specific product using a dedicated button
	`openByDefault`	`false`	`true` / `false`	allows the purchase of gift cards via web checkout
	`disableAmountInput`	`false`	`true` / `false`	disables the ability to adjust the per unit price of the gift card

📒 NOTE

Please note that the default states of most features are already implemented. With the exception of the timePickerType feature, there is no need to specify the feature in the data-config or script unless you wish to change the default behaviour.

Color Themes

Ability to customise colours according to brand.

LIGHT mode or DARK mode is supported.

📒 NOTE
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:

📗 TIP

To support light or dark mode, use "defaultTheme": "light" or "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	Details
Name	`ventrata-order-created`
Description	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	Details
Name	`ventrata-order-updated`
Description	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	Details
Name	`ventrata-order-confirmed`
Description	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	Details
Name	`ventrata-order-expired`
Description	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	Details
Name	`ventrata-booking-created`
Description	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	Details
Name	`ventrata-booking-updated`
Description	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	Details
Name	`ventrata-booking-removed`
Description	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	Details
Name	`ventrata-bottom-bar-visibility`
Description	fires when bottom bar is shown or hidden
Usage	document.addEventListener('ventrata-bottom-bar-visibility', (event) => { alert(`bottom bar visibility is ${event.detail.visible}`) } )

Try out the Ventrata checkout yourself

Manage my Booking (Check-in Page)

📗 TIP
If you would like to implement a check-in page (manage my booking) into your website, please follow this stay tuned for more information coming soon.

How to Use Gift Cards on the Web Checkout

How to Use Quotes

How to Use the Multi-Booking Feature

How to Use the Promo / Gift Card Input Feature

How to Switch from Embedded to Pop-up Mode

Integrate Ventrata Checkout

Locate Your apiKey

Layered configuration

Display the Checkout after the Element is Clicked (Pop-up & Embedded)

Static Analysis

Dynamic Execution via Global Function Ventrata

Embedded Mode Implementation Specifics

Multi-booking

Supported Configuration Inputs

Checkout Feature List

📣 Gift Cards Feature List

Color Themes

Custom Events

Manage my Booking (Check-in Page)

Dynamic Execution via Global Function `Ventrata`