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

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