Before you begin
This guide provides an overview of the hybrid checkout workflow. Each step links to a dedicated implementation guide covering the required configuration, APIs, and examples.
This guide explains how to build a hybrid checkout around the Ventrata Checkout Widget. Your application controls the customer journey, cart, payment flow, and business logic, while Checkout continues to manage booking creation, validation, and customer data collection.
Typical reasons for building a hybrid checkout include:
Custom cart or checkout UI
Custom payment processing
CRM or loyalty integrations
Additional business validation before payment
Custom marketing or upsell flows
Hybrid Checkout Flow
During a hybrid checkout, control moves between the Checkout Widget and your application as the customer progresses through the booking journey.
📒 NOTE
The diagram and Step 1 below describe the Checkout-first path. Control starts in Checkout and hands off to your application partway through. If your application create the order itself, before the customer ever sees Checkout, see the application-first variant under Step 1.
Checkout Widget
│
Customer selects products
│
Order created
│
Checkout hands control to your application
│
Your application manages the cart
│
├── Order complete?
├── Yes → Continue to payment
└── No
│
Determine the first incomplete step
│
Re-open Checkout on the required page
│
Customer completes missing information
│
Return to your application
│
Proceed to payment
The Checkout Widget continues to own booking creation, validation, and order updates, while your application controls the overall checkout experience, including payment and any custom business logic.
Step 1: Create a Hybrid Cart
Every hybrid checkout starts with an order. There are two ways to create it, depending on where your custom flow needs to begin:
Checkout-first
The customer starts in the Checkout Widget, and it created the order for you. Configure Checkout to hand control to your application when the customer reaches the Contact Details page.
This creates the booking and order inside Ventrata while allowing your own application to continue the checkout journey.
Application-first
Your application create the order itself, for example, once the customer has chosen a date, time, or experience in your UI, before Checkout ever loads. In this case, when you later open Checkout, you must also pass the recoveryToken returned when the order was created. Checkout cannot otherwise confirm your application's browser is allowed to open that order.
Step 2: Listen for Checkout Events
Checkout communicates with your application through Custom Events.
These events notify your application when important actions occur, such as:
Order creation
Order updates
Customer details being updated
Checkout completion
Opening the external cart
Rather than polling the API, your application should respond to these events to keep its own state synchronised with Checkout.
Step 3: Validate the Order Before Payment
Before starting payment, verify that the order is complete.
For most implementations, call Ventrata.validate() immediately before payment and inspect the returned validation result.
If validation fails, return the customer to Checkout to complete the missing information before continuing.
Step 4: Return the Customer to Checkout
If additional information is required, send the customer back into Checkout on the page that requires their attention.
Instead of restarting Checkout from the beginning, launch it directly on the appropriate page, allowing the customer to continue where they left off.
The validation result identifies the type of missing information. Your application should map that result to the appropriate Checkout page.
Recommended Integration Flow
📒 NOTE
The numbered flow below describes the Checkout-first path. For an application-first order, start at step 4 (opening Checkout on the appropriate page with your order's orderID and recoveryToken) and continue from there.
The customer selects products using the Checkout Widget.
Checkout creates the order.
Checkout transfers control to your external cart.
Your application listens for Checkout events and synchronises its state.
Call
Ventrata.validate()before payment.If required information is missing, reopen Checkout on the appropriate page.
Continue listening for order updates.
When the order is complete, begin payment.
Complete the booking.
Following this workflow lets your application deliver a fully customised checkout experience while continuing to rely on Checkout for booking creation, validation, and customer data collection.