Book

The Book operation requests a booking confirmation for the specified optionId obtained from the Quote. It provides a concise summary of the option, along with the reservation status. Please note that the returned information may vary depending on the Seller. The returned fields include:

• holder
• hotel
• price
• cancelPolicy
• bookingID
• status (Make sure you add this field to your Query in order to receive the reservation status in the book response.)
• clientReference (The booking locator in your system - alphanumerical value.)
• supplierReference (Make sure you add this field to your Query in order to receive the provider locator in the book response.)

Book Inputs

This mutation offers versatility in book options, with certain fields marked as mandatory (optionRefId, clientReference, holder etc.) and others as optional (language, deltaPrice, paymentCard etc.). This flexibility empowers you to create a personalized Book Multation, tailoring the requested fields to your specific needs.

When creating your book mutation, you have two different inputs to fill based on your specific needs:

1. Input
2. Settings

mutation {
    hotelX {
    book
      input: {}
      settings: {}
	}
}

Remember

It's important to note that even if certain fields in the "criteria" or "settings" inputs are labeled as optional, we still need to use some value internally. This value will either come from your query/mutation request or your default settings. You have the ability to manage your default API settings by visiting the API Settings section on our website.

1. Input

To specify your book input you need to use the input HotelBookInput in your mutation variables:

{
    "bookInput" : {
        "optionRefId" : "11!11?1$241028?241029?1?1?0?ES?ES?es?EUR?0?2?1?1?1?0?15091142?BAR[%@BAR?146.0$0$false$EUR$$0$?1|30#30|1|2024-10-28|1|4132467|4132468|1|11|0?2269!2269?30$30??Double Standard?1??After$146.0!Before$146.0!ExpireDate$29/10/2024!mercado$ES!tgx_sess$f6152cba-f792-4e81-a2c1-e73ca63ecd02?OK?Sith?0?",
        "clientReference" : "test_0123456789",
        "deltaPrice" : {
            "amount" : 10,
            "percent" : 10,
            "applyBoth" : true
        },
        "holder" : {
            "name" : "Jane",
            "surname" : "Doe"
        },
        "remarks" : "This is just a test booking! Feel free to include any extra information in the remarks section that you'd like the supplier to know.",
        "rooms" : [
            {
                "occupancyRefId" : 1,
                "paxes" : [
                    {
                        "name" : "Jane",
                        "surname" : "Doe",
                        "age" : 30
                    },
                    {
                        "name" : "John",
                        "surname" : "Smith",
                        "age" : 30
                    }
                ]
            }
        ]
    }
}

Mandatory input:

• optionRefId (Identifier of the option used in Quote.)
• clientReference (Booking ID in client's system.)
• holder
• rooms

Optional input:

• language
• deltaPrice (Indicates price variation permitted by the Buyer.)
• paymentCard (If the payment is done by credit card, it's mandatory to specify the payment type and the credit card information, unless you're using our VCC Plugin to generate virtual credit cards. Know more about VCC payments here.)
• remarks (Any customer comments for the supplier to consider.)

Key Recommendations

• Customize the timeout according to your needs, taking into consideration the maximum values in Book is 180,000ms.

• Consider that the deltaPrice sets the price tolerance between Quote and Book. For instance, if the Quote stage displays a price of 100€ and the deltaPrice is 5, a change up to 105€ will still secure a confirmed booking.

Payment Card

If the option or rate you want to book has a payment type such as DIRECT, CARD_BOOKING, or CARD_CHECK_IN, it is mandatory to provide payment card information when making the booking. This should be done using the PaymentCardInput in the book mutation.

Note that isVCC, virtualCreditCard and threeDomainSecurity, are all optionals.

{
			"cardType": "VI",
			"holder": {
				"name": "test_name",
				"surname": "test_surname"
			},
			"number": "4874495143042809",
			"CVC": "330",
			"expire": {
				"month": 9,
				"year": 2028
			},
			"isVCC": true,
			"virtualCreditCard": {
				"activationDate": "2020-10-02",
				"deactivationDate": "2021-01-02",
				"currentBalance": 50.58,
				"currencyCode": "EUR"
			},
			"threeDomainSecurity": {
				"version": "1.0.1",
				"DSTransactionID": "transaction 1",
				"XID": "id123456",
				"ECI": "05",
				"CAVV": "CAVV",
				"payerResponse": "base64xml response",
				"payerResponseStatus": "AUTHENTICATION_SUCCESS",
				"cardEnrolledStatus": "CARD_ENROLLED",
				"merchantName": "test_name",
				"signatureStatus": "SIGNATURE_NOT_VALIDATED"
			}
		}

Possible values for the threeDomainSecurity fields

Visa, American Express, Diners Club and JCB

ECI Value	Description
05	3DS authentication was successful, transactions are secured by 3DS.
06	Authentication was attempted but was not or could not be completed; possible reasons being either the card or its Issuing Bank has yet to participate in 3DS.
07	3DS authentication is either failed or could not be attempted; possible reasons being both card and Issuing Bank are not secured by 3DS, technical errors, or improper configuration.

Mastercard

ECI Value	Description
00	3DS authentication is either failed or could not be attempted; possible reasons being both card and Issuing Bank are not secured by 3DS, technical errors, or improper configuration.
01	3DS authentication was attempted but was not or could not be completed; possible reasons being either the card or its Issuing Bank has yet to participate in 3DS, or cardholder ran out of time to authorize.
02	3DS authentication is successful.

Payer response status

Status Value	Description
AUTHENTICATION_SUCCESS	Successful Authentication.
AUTHENTICATION_FAILED	Failed Authentication.
AUTHENTICATION_INCOMPLETE	Unable to complete Authentication.
TRANSACTION_ATTEMPT_SUCCESS_A	Successful Attempts Transaction.
TRANSACTION_ATTEMPT_SUCCESS_B	You can proceed to authorisation using the information received.
AUTHENTICATION_REJECTED	Authentication Rejected.

Card enrollment status

Status Value	Description
CARD_ENROLLED	Cardholder is enrolled. Bank is participating in 3-D Secure protocol and will return the ACSUrl.
CARD_NOT_ENROLLED	Cardholder Not Participating – Cardholder is not enrolled.
CANT_AUTHENTICATE	Unavailable. The DS or ACS is not available for authentication at the time of the request.

Signature verification status

Status Value	Description
SIGNATURE_VALIDATED	Signature of the PARes has been validated successfully.
SIGNATURE_NOT_VALIDATED	PARes could not be validated.

2. Settings

Settings are the common configurations used to construct requests to the supplier/s. By default, we apply the same configuration to all Hotel-X clients.

To specify your quote settings you need to use the HotelSettingsInput input in your query variables:

{
	"settings": {
		"client": "client_demo",
		"context": "HOTELTEST",
		"testMode": true,
		"auditTransactions": false,
		"timeout": 60000
	}
}

Mandatory Settings:

• client
• context (You have the flexibility to choose between using the supplier's context or your own, depending on which codes you want to see in the response. If you prefer to receive responses with your custom codes, please ensure that your context code is linked to the mapping files that you've previously uploaded to your FTP account.)
• timeout (Timeout in milliseconds for the supplier connection. Won't close client connection if exceeded.)

Optional Settings:

• group
• auditTransactions
• suppliers (Each one contains its own code, settings and accesses.)
• plugins
• testMode (This flag allows only the accesses checked as test.)
• clientTokens (Used to identify the origin of the request, this is only used in plugins.)
• businessRules
• operationTimeout (Timeout in milliseconds for Hotel-X connection. Will close Buyer connection if exceeded. Must be higher than timeout.)

Key Recommendations

• Customize the timeout according to your needs, taking into consideration the maximum values in Book is 180,000ms.

• Set the auditTransaction to "true" in Book when investigating errors.

Important: Test Bookings

For development and testing purposes, you are provided with the supplier test HOTELTEST (accessCode 2). We recommend using this during your development phase.

However, if you prefer testing with real suppliers, please note that any bookings made using test access but involving live suppliers are your responsibility, and must be cancelled in order to avoid any booking costs from Travelgate. This also means that the Buyer must handle any costs directly with the supplier if bookings are not canceled. Even if an access is labeled as "live" or "production" but uses test credentials internally, you're still responsible for any bookings made and not cancelled. Please keep this in mind when using our API services.

Requests Examples

Book Response

Book output fields

Explore all the book output fields and their descriptions in our detailed Graphql API Reference section here.

Book Status

Once a Book (Reservation) method is run, our API response will provide its book status. This status represents the current status of the reservation and can be categorized into four possible values:

Status	Description
OK	The reservation was successfully completed without any issues.
ON_REQUEST	Please note that a Book status may change over time: you may receive an ON_REQUEST status in Book response, and after running a Booking Query some seconds later the status may have already changed to OK.
UNKNOWN	The reservation process through Travelgate was completed but due to a supplier error or a timeout, the reservation status is unknown (our system was unable to confirm if the booking has been confirmed or not the on Seller's system). It is the Buyer’s responsibility to check if the booking is OK.

Frequently Asked Questions

What should I do if I receive both an OK status and an error in the same Book response?

If you receive an error and a booking status OK in the Book response, the reservation status prevails over the error. Although you may also run a Booking Query in order to check the status of a reservation, please note that you should always contact the Seller in order to check the actual status of a booking in those cases you receive a booking status different than OK or no response at all.

What is the DeltaPrice? Why should I use it?

The Delta Price indicates the price variation permitted by the Buyer (amount or percentage), so that an error will be returned if the new price does not abide to DeltaPrice. If DeltaPrice is not sent and the integration implements it, we assume that the price range is 0 and the process will continue (price is lower or equal to the price returned in Quote). This field is implemented if it’s native to the Seller or if another Search/Quote request needs to be done in Book. Please note DeltaPrice should be implemented by a Seller in order to be available to a Buyer.

What does DeltaPrice "applyBoth" mean?

• If the value is 'false' it indicates that one of the conditions (amount or percentage) has to meet the DeltaPrice criteria before reservation.
• If the value is 'true' it indicates that the new price cannot exceed the amount and percentage indicated by the Buyer.

Why do I receive a status "ON_REQUEST" and a holder name "test" in my reservations the test environment?

In the test environment, it is common for some Sellers to consistently return an ON_REQUEST status. Furthermore, as a standard practice in the test environment, we automatically replace the holder and passenger names with "test".

Will the currency in Book be the same as the currency in Quote?

The currency used for the transaction will remain the same throughout the entire Booking Flow, including cancellation policies.

Do I have to provide real names and ages for all the passengers?

No, you are not required to provide real ages and names for all passengers. You can use default values for each age group and name. The only information that should be real is the holder's information.

How do I define the total number of rooms in my Book request?

To define the number of rooms in your reservation, you need to utilize the occupancyRefId previously returned in Search response.For instance, for a room of two adults:

"rooms": [
	{
		"occupancyRefId": 1,
		"paxes": [
			{
				"name": "TestName",
				"surname": "Surname",
				"age": 30
			},
			{
				"name": "TestName",
				"surname": "Surname",
				"age": 30
			}
		]
	}
]

What payment details should I add to my Book request?

The payment type and details to be added in your Book request depend on the payment type returned for the option to be booked, note that payment types depend on the commercial agreement established by a Buyer with their Sellers.

Where can I get the Hotel Confirmation Number (HCN)?

Once a booking has been successfully confirmed in Travelgate you may retrieve 2 different locators from its logs:

• The Buyer's locator (client reference).
• The Seller's locator (provider reference).

The Seller may also provide a third type of locator, issued by the hotel when it confirms the booking. This is known as the Hotel Confirmation Number (HCN) or Hotel Reference Booking (HRB). Please note we are only able to provide this code if the Seller returns it in their response.