Articles on: New Web Checkout

Implementation Guide

📣 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 this section Embedded mode implementation specifics



Pop-Up Mode

Embedded Mode


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:

API Key

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



InputDescription
langoptional, lower case, for example, en, cs
currencyoptional, 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 works with the multibooking flow where your page has your own cart and you would like to use our edit flow.
Globe Icon

InputDescription
envoptional, live OR test ; if left empty checkout defaults to test
apiKeymandatory (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.
embeddedoptional, 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.
multibookingoptional, 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.
productIDoptional, ID of the product. If not set, product list will be shown.
optionIDoptional, ID of the option
bookingIDoptional, ID of the booking; used only for multibooking edit flow). Its presence needs to be paired with** orderID .
orderIDoptional, ID of the order; used only for multibooking edit flow). Its presence needs to be paired with bookingID .
checkMarketingConsentoptional, by default set to false; if set to true, marketing consent will be pre-selected for users during contact form flow
referreroptional, string value, for example, hilton.com
pagestring, 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



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.

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:

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:

FeatureDefaultAvailable ValuesDescription
promoAndGiftCardInputtruetrue / falsedisplays a field to enter promo or gift card code
showRemainingSeatsfalsetrue / falsedisplays the number of remaining seats for the tour
bottomBartruetrue / falsedisplays a bar at the bottom of the screen when multiple bookings are made in one order
waitlistsAllowedfalsetrue / falseenables the Waitlists functionality, a mechanism for guests to express interest in booking a tour on dates that are currently sold out
quotesAllowedfalsetrue / falseenables the Quotes functionality, which allows customers to postpone payment and review a booking without commitment
timePickerTypeby default not setselecttransforms the time selection interface from individual buttons to a dropdown menu; this feature is a prerequisite to the showTourGroupsHeadlines feature
showTourGroupsHeadlinesfalsetrue / falseorganise timeslots into distinct tour groups, each with its own headline; to use this feature, make sure include the timePickerType: select first
openGiftFlowfalsetrue / falseallows 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 📣
disableGiftAmountInputfalsetrue / falsedisables 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 📣


📣 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. Learn more in our Gift Card article.

FeatureSub-featureDefaultAvailable ValuesDescription
giftsby default not setcontains sub-features to modify the behaviour of the gift cards functionality
allowedtruetrue / falsewhen enabled from the dashboard, this feature may appear in the script
modeby default not setsimpledefault 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
openByDefaultfalsetrue / falseallows the purchase of gift cards via web checkout
disableAmountInputfalsetrue / falsedisables the ability to adjust the per unit price of the gift card


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.

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:

EventDescription
ventrata-order-createdfires 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}`)
    	}
    )


EventDescription
ventrata-order-updatedfires 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`)
    	}
    )


EventDescription
ventrata-order-confirmedfires 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`)
    	}
    )


EventDescription
ventrata-order-expiredfires 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`)
    	}
    )


EventDescription
ventrata-booking-createdfires 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}`)
    	}
    )


EventDescription
ventrata-booking-updatedfires 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}`)
    	}
    )


EventDescription
ventrata-booking-removedfires 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}`)
    	}
    )


EventDescription
ventrata-bottom-bar-visibilityfires 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: 20/06/2024

Was this article helpful?

Share your feedback

Cancel

Thank you!