Skip to main content
All CollectionsWeb CheckoutManuals
Web Checkout Implementation Guide
Web Checkout Implementation Guide

Discover the Ventrata checkout widget features and how to implement them.

Lucia Burin Sestakova avatar
Written by Lucia Burin Sestakova
Updated this week

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

Embedded Mode

Pop-up 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:
​

API Key

API Key

πŸ“’ 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.


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


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.

Globe Icon

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

disableGiftAmountInput

false

true / false

disables the ability to adjust the per unit price of the gift card

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

restrictedTicketType

by default not set

fixed / flexible

control which ticket date type is displayed to customers

preselectFirstAvailableDateModalCalendar

false

true / false

automatically preselects the earliest available date

πŸ“’ 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.


Gift Cards Feature List

Gift cards typically have a stored value that can be spent over multiple transactions until the balance is depleted, for example, for an experience and/or a gift shop item.

Set up the basic properties for your gift cards and take advantage of features that allow you to offer gift cards redeemable for any product or ones tied to a specific pre-selected product.

πŸ“— TIP

Learn more in our article on gift cards.


Option Selector Feature List

The Option Selector feature, along with its sub-features, lets you customise how product options and tour commentary languages are presented. With various settings, you can create a highly tailored layout.

πŸ“— TIP

Learn more in our article on the option selector feature.


Colour Themes

Ventrata checkout offers two basic colour modes: LIGHT and DARK. You can customise these modes using the data-config attribute in your checkout.

Additionally, specific elements of your web checkout can be configured as a JavaScript object for further customisation.

πŸ“— TIP

Learn more in our article on colour themes.


Manage My Booking (Check-in Portal)

The Check-In, also known as Manage My Booking (MMB), portal allows customers to reschedule, cancel or update their bookings, as well as redeem reseller vouchers.

πŸ“’ NOTE

The current Manage My Booking solution is part of the old checkout (V2 and older), which is no longer supported. You can, however, implement this solution into your new checkout (V3) using the steps in this article.

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


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}`)
}
)

Did this answer your question?