HQ Rental Software
  1. Guides
  2. Booking Engine
HQ Rental Software
  • Authorization
  • Introduction
  • Guides
    • Booking Engine
      • Reservation Creation Flow
      • Reservation Update Flow
    • Toll Integration
      • Toll Integration Flow
  • Car Rental
    • Comments
      • Show a list of all the comments for an item
      • Creates a new comment
      • Updates a comment
      • Delete comment
      • Get Reservation comments
      • Update Reservation comments
      • Deletes a comment
    • Currencies
      • Returns all the currencies
    • Emails
      • Show a list of all email templates
      • Trigger an email template
      • Send reservation confirmation email by id
      • Send reservation contract email by id
      • Show a list of all applicable email templates for a reservation
      • Trigger an email template for a reservation
      • Store a quote and sends an email
    • Addresses
      • Shows a list of addresses
      • Create address
      • Finds address by id
      • Updates address by id
      • Delete address
    • Fields
      • Show a list of all fields for specific item_type
      • Show details of specific field
      • Show details of specific field
      • Show a list of all fields applicable for the customers in the reservations process
    • Blocked Days
      • List all blocked days
    • Customer Credits
      • List all credit transactions
      • Create a customer credit
      • Delete a credit transaction
      • Update a customer credit
    • Daily Manifest
      • shows mine dashboard
    • Fines
      • List all fines
      • Create a fine
      • Retrieve a fine
      • Update a fine
      • Deletes a fine
    • Packages
      • Shows a list of available package items
      • find a package item
      • Shows a list of available packages
      • find a package
    • Quotes
      • Shows a list of the reservation quotes in the system
      • Find a quote that matches the given ID
    • Rate Types
      • List all rate types
      • Updates a rate type
      • Creates a rate type
      • Find a specific rate type
      • Deletes a rate type
    • Rates
      • List all rates
      • Updates a rate
      • Creates a rate
      • Find a specific rate
      • Deletes a rates
      • List all rates v2
    • Reservation Attempts
      • Shows a list of reservation attempts
      • Find the reservation attempts based on a given email
    • Extensions
      • Show a list of all the extensions for a reservation
      • Creates an extension for one reservation
      • Deletes an extension
    • External Charges
      • Show a list of all the external charges for a reservation
      • Creates an external charge for one reservation
      • Deletes an external charge for one reservation
    • Adjustments
      • Show a list of all the adjustments made to a reservation
      • Creates an adjustment for one reservation
      • Deletes and adjustment for one reservation
    • Payments
      • Show a list of all the payments for a reservation
      • Creates a payment for one reservation
      • Updates a payment for one reservation
      • Initiate a refund of security deposit
      • Charges a credit card from customer's reservation
    • Refunds
      • Show a list of all the refunds for a reservation
      • Creates a refund for a reservation
      • Updates a refund for a reservation
      • Deletes a refund for a reservation
    • Reservations
      • Updates the status of a reservation to Open
      • Updates the status of a reservation to Cancel
      • Updates the status of a reservation to Pending
      • Updates the status of a reservation to Quote
      • Updates the status of a reservation to No Show
      • Returns the details and validations required for the dates step
      • Validates the dates and return a list of available classes for that period with the respective prices for each vehicle class
      • Updates the vehicle class of a reservation (Only Existing Bookings)
      • Returns a list of applicable additional charges based on the selection of dates, brand and vehicle class
      • Returns the price for the selection of charges and vehicle class
      • Creates or updates a customer in the system
      • Confirms and create the reservation in the system
      • Updates a reservation
      • shows a list of reservations
      • show rental agreement of specific reservation
      • Set date of sign
      • Find a specific reservation
      • Assign vehicle
      • Detach vehicle
      • Available Vehicles
      • Upload primary driver signature
      • Returns the available cars for a given location and reservation date range
    • Vehicle Replacements
      • Shows all vehicle replacements from a reservation
      • Creates a reservation vehicle replacement
      • Updates a reservation vehicle replacement
      • Deletes vehicle replacements from a reservation
    • Reservation Agents
      • Shows a list of available agents
      • Assign primary agent
      • Assign return agent
    • Seasons
      • Shows a list of available seasons
      • Creates a season
      • Find a specific season
      • Updates a season
      • Deletes a season
    • Security Deposits
      • Shows a list of security deposits
      • Shows an specific security deposit
    • Webhooks
      • Register a webhook
  • Filters
    • Returns an example of the allowed filters to the API
  • Preferences
    • Show a list of all preferences per module
  • Contacts
    • List all contact categories
    • List a specific contact category
    • List all contacts of a specific contact category
    • Create a new contact in the application.
    • List a specific contact
    • Update a contact in the application.
    • Merge contacts
  • files
    • Shows a list of files
    • upload file
    • Delete file
  • Fleets
    • Additional Charges
      • Shows a list of the additional charges
      • Returns a single additional charge
    • Features
      • Shows a list of features
      • Returns a single feature
    • Locations
      • Shows a list of locations
    • Blocked Periods
      • Shows a list of blocked periods for a vehicle
      • Create a blocked period for a vehicle
      • Update a blocked period for a vehicle
      • Deletes a blocked period
    • Branches
      • Shows a list of Vehicle Brands
      • Returns a single vehicle brand
    • Damages
      • Shows a list of vehicle damages
      • Create a damage for a vehicle
      • Show the details of a specific vehicle damage
      • Update a damage for a vehicle
    • Vehicles
      • Models
        • Shows a list of Vehicle Models
        • Returns a single vehicle model
      • Types
        • Shows a list of Vehicle Types
        • Returns a single vehicle type
      • Shows a list of vehicles
      • Show the details of a specific vehicle
      • Update Vehicle
      • Reserve vehicle
      • Cancel Reserve
    • Relocations
      • Shows a list of relocations
      • Create a relocation for a vehicle
      • Deletes a relocation
    • Telematics
      • Shows a list of the OBD history records of the vehicle
      • Shows a list of vehicle trips for the specified vehicle
  • Payment Gateways
    • Shows a list of credit cards for one customer
    • Delete payment gateway
    • Shows a list of payment methods
    • Finds payment method by ID
    • Returns payment method button
    • Returns payment method form
    • Finds payment transaction by UUID
    • shows a list of payment transactions
    • Create payment transaction
    • Refunds a payment transaction
    • Shows a list of stripe locations per gateway
    • Returns a connection token for a given location
    • Returns a connection token for stripe terminal
  • Sheets
    • Show a list of all items for specific sheet
    • Show details of sheet item
    • Update sheet item in the application
    • Create a new sheet item in the application
    • Show a list of all sheets
    • Show a list of all sheets
  1. Guides
  2. Booking Engine

Reservation Creation Flow

The booking engine is a core component of a car rental company's website. While reservations can be created in the HQ backend and integrated with your website using our pre-built snippets, you can also build your own booking engine through HQ’s API integration.

Step 1 - Get Info to build Step 1 Dates#

GET /car-rental/reservations/dates?brand_id=1
Returns the details and validations required to build the form for selecting the pickup/return dates and location. Call this endpoint and use the response to build the Step 1 Dates form.
Below is an example of the query params that can be sent:
brand_id: 1
image.png

Step 2 - Validate selected Dates and List Available Vehicle Classes#

POST /car-rental/reservations/dates
Validate the dates and location. Return a list of available classes for that period with the respective prices for each vehicle class. Use this endpoint to submit and validate the selected dates and location, the response with the vehicle classes is used to build the Step 2 Vehicles form.
Below is an example of the body params that can be sent:
pick_up_date: 2025-02-28
pick_up_time: 10:00:00
return_date: 2025-03-01
return_time: 10:00:00
pick_up_location: 1
return_location: 1
brand_id: 1
The response can be used to build the Step 2 Vehicles form.
image.png

Step 3 - Get Applicable Additional Charges#

GET /car-rental/reservations/additional-charges
Get Applicable Additional Charges based on the Selection of Dates and Vehicle Class.
Below is an example of the query params that can be sent:
pick_up_date: 2025-02-26
pick_up_time: 08:00:00
return_date: 2025-02-27
return_time: 08:00:00
pick_up_location: 2
return_location: 2
brand_id: 1
vehicle_class_id: 2
The response can be used to build the Step 3 Features form.
image.png

Step 4 - Return Price for the Selection of Charges#

POST /car-rental/reservations/additional-charges
Post the selected additional charges, and use the response to update the summary with the reservation total price and the applicable security deposit/excess amount.
Below is an example of the query params that can be sent:
pick_up_date: 2025-03-18
pick_up_time: 10:00:00
return_date: 2025-03-21
return_time: 10:00:00
pick_up_location: 1
return_location: 1
brand_id: 1
vehicle_class_id: 1
additional_charges[]: 3
additional_charges[]: 8_2
Optional query params:
coupon_code: 2012
manual_discount: 10
manual_discount_is_percentage: 1

How to add coupon codes#

You can apply coupon codes, which are configured in the HQ backend.
coupon_code: 2012
image.png

How to add discount (amount)#

You can also apply manual discounts. For a 10 USD discount, add manual_discount.
manual_discount: 10

How to add discount (percentage)#

For a 10% discount, add manual_discount and manual_discount_is_percentage.
manual_discount: 10
manual_discount_is_percentage: 1

Step 5 - Get Info to build Step 4 Customer#

GET /car-rental/reservations/fields/customer
Returns the details and validations required to build the Step 4 Customers form.
image.png

Step 6 - Create a customer#

POST /car-rental/reservations/customer
Submit the customer form and create the customer.
Below is an example of the query params that can be sent in a default system:
pick_up_date: 2025-02-26
pick_up_time: 08:00:00
return_date: 2025-02-27
return_time: 08:00:00
pick_up_location: 2
return_location: 2
brand_id: 1
vehicle_class_id: 1
contact_entity: person
field_2: Here goes the First Name
field_3: Here goes the Last Name
field_9: Here goes the Email Address
field_193: Here goes the Street
field_195: Here goes the City
field_198: Here goes the Zip
field_62: Here goes the Country, ISO 3166-1 alpha-2 code
field_8: Here goes the Phone Number
field_15: Here goes the Birthdate
field_274: Here goes the Passport content
field_273: Here goes the Nationality content
field_6: Here goes the Website content
field_194: Here goes the Street 2 content
field_196: Here goes the State content
field_254: Here goes the DL Number content
field_256: Here goes the Expiration Date
The fields might be different or be required fields depending on your system’s configuration. The created contact ID is available in the response as data.customer.id
image.png
If your system has customized the customer form with additional fields, you may review the fields from the response from Step 5, or the HQ backend in Settings > Contacts > Fields and Settings > Contacts > Customers > Fields.
image.png

Step 7 - Upload Driver’s License File#

POST /files/upload
Upload the driver’s license.
Below is an example of the body params that can be sent in a default system:
item_type: To upload to a field in the customer form, the value should be 'contacts.3’
item_id: Enter the ID of the customer you just created. For example, if the new customer has an ID of 64, use this same ID as item_id.
file: The file to be uploaded.
filename: The name of the file you are uploading.
field_id: The ID of the field used for the file upload. For a driver's license, the default is 252.
If your system has the driver’s license field customized or modified, you can go to Settings > Fields and search for DL Number (or the label you use for the driver’s license field). The # column is the field ID. If you have issues finding the field_id to upload the driver’s license image, you can open a support ticket to ask for assistance.
image.png

Step 8 - Confirm Reservation and Generate Payment Link#

POST /car-rental/reservations/confirm
Confirms and creates the reservation in the system.
Below is an example of the query params that can be sent:
customer_id: 40
brand_id: 1
pick_up_date: 2025-12-31
return_date: 2026-01-05
pick_up_time: 15:30
return_time: 14:00
vehicle_class_id: 2
pick_up_location: 2
return_location: 2
Optional query params related to online payment:
return_payment_link: true
payment_method_id: 5
payment_external_redirect: https://test.com/reservation-payments
set_amount_to_pay_online_from_settings: 1
Optional query params related to discounts:
coupon_code: 2010
manual_discount: 10
manual_discount_is_percentage: 1

How to Implement Online Payment Link#

Determine the payment method id#

Go to Settings > Payment Gateways > Gateways and select the payment gateway. Click on the Methods tab and note the payment method ID.
image.png
When confirming the reservation, make sure to pass these optional query params related to online payment:
return_payment_link: true
payment_method_id: 5
payment_external_redirect: https://test.com/reservation-payments
set_amount_to_pay_online_from_settings: 1
Review the response, below is an example simplified with “…”, see the payment_link key-value pair.
It is a URL link loading the online payment form. The UI might differ slightly depending on the payment gateway.
image.png

Payment Form Implementation Options#

Option 1 - Using an Iframe
For a seamless customer experience, the payment link can be loaded within an iframe on the website. This approach keeps the user within the platform, reducing friction and maintaining brand consistency. However, keep in mind that some payment gateways may have dynamic UI changes that could affect the structure or usability of the iframe.
Option 2 - Redirecting to a New Tab or Window
Alternatively, the user can be redirected to the payment link in a new tab or window. This ensures full compatibility with all payment gateways, but may result in a less seamless experience compared to an iframe.

Test and Verify the Online Transaction#

You may set the payment gateway to test mode to test the implementation.
After the payment form is filled and successfully processed, the payment is reflected in the corresponding reservation in HQ and also in the online payment gateway.
image.png
Modified at 2025-03-05 19:19:34
Previous
Introduction
Next
Reservation Update Flow
Built with