Booking Processes

Synchronous Mode

(i)    Details

A synchronous response will be provided to the request.

(ii)  Advantages

  • Immediate booking update without having to program for either the push mechanism or the token retrieval method

(iii) Disadvantages

  • Not suitable for multi-item booking requests
  • Only suitable for clients who work with immediately available items and not with on request items
  • Not suitable for booking modification messages if several modifications for one booking are sent within one request (multiple sub-requests within one XML message)
  • If bookings are updated by the GTA staff or by your own staff on the call centre site no booking updates will be sent to your systems

Asynchronous Mode

a)    Push Mechanism

(i)    Details

In order to use the push mechanism the client has to include the element <ResponseURL></ResponseURL> in the xml string as follows:

<?xml version="1.0" encoding="UTF-8" ?>
<Request>
<Source>
<RequestorID Client="123" EMailAddress="abc@abc.com" Password="XXX" />
<RequestorPreferences Language="en">
<RequestMode>ASYNCHRONOUS</RequestMode>
<ResponseURL>https://www.client.com/xml.asp/response</ResponseURL>
</RequestorPreferences>	

In between the opening and closing tags of the <ResponseURL> parameter the client has to specify a URL as to where the requests should be posted to from the GTA server once the response has been generated.

At the client side, an application has to be constantly listening for any updates attempted to be posted by the GTA server. 

As long as the GTA server receives a HTTP 200 OK response from the client we will assume that the response has been successfully posted. If no response or any other

HTTP code is being received from the client GTA will attempt the posting again until x times in the space of x hours after which no further attempts will be made.  

For all responses relating to a given request the ResponseReference will be the same and the ResponseSequence will start at 1 (for the initial response) and increment by 1 for each subsequent update message. Due to the possible use of multi-threaded request/response processing it cannot be guaranteed that the receiver will always receive responses in exactly the same order as they were built, so for the auto updates the client must be aware that it is possible to receive responses for the same ResponseReference with the ResponseSequence out of sequence.

The IP addresses GTA are pushing the responses back from, on our stage and production server, are:

83.244.143.1-62 
83.244.142.33-62
213.146.191.193-254
83.244.143.65-126
213.212.78.1-62
176.62.135.33-62

Please also note that we only allow access via ports 80 and 443.

If the client needs to change the IP address that the URL used for the push mechanism resolves to or the certificate associated with this <ResponseURL>, we require 2 weeks advance notice. On the date and time of change advised by the client we will make the necessary changes at our side.  After that it can take up to 48 hours for the IP change to propagate through the DNS.

 

The Initial Request (ASYNCHRONOUS with URL)

(1) Client’s Web/Application Server makes an HTTP POST Request to XML Interface - Body of HTTP Request contains an XML Request.

(2) Client’s Web/Application Server receives an HTTP Response from XML Interface – Body of HTTP Response contains an XML Response with a ResponseReference.

(3) Application (eg. Java Servlet or CGI Program or PHP code or may other examples.) running on Client Web/Application Server processes the HTTP Response above (2) by extracting the XML Response from the body of the HTTP POST Request, parsing the XML, then extracting the ResponseReference and storing it somewhere related to the request.

The Asynchronous Response

(4) XML Interface makes an HTTP POST Request to Client Web/Application Server - Body of HTTP Request contains an XML Response with the same ResponseReference returned in the above response (2).

(5) Application (eg. Java Servlet or CGI Program or PHP code or may other examples.) running on Client Web/Application Server processes the HTTP POST Request above (4) by extracting the XML Response from the body of the HTTP POST Request, parsing the XML, extracting the ResponseReference, then matching it to the ResponseReference extracted from the original request (3). It then processes the Response.

(ii)  Advantages

  • Immediate booking updates are being pushed back to your server as soon as any booking changes have taken place on the GTA systems  
  • If bookings are updated by the GTA staff or by your own staff on the call centre site you will receive immediate booking updates  
  • Suitable booking method for processing bookings for on request items
  • Suitable for multi-item booking requests
  • Suitable for booking modification messages if several modifications for one booking are sent within one request (multiple sub-requests within one XML message)

(iii) Disadvantages

  • Requires the set-up of an application that has to be constantly listening for any updates attempted to be posted by the GTA server

b)   Token Retrieval Method

(i)    Details

If a ResponseURL is not supplied within the request, the response will remain on the GTA ‘Processed Queue’ waiting for the client to make another request to pick up the results. A short conversation will be established where the client request is received, authenticated and after a unique ResponseReference assigned it is queued for background processing. The client is then returned the unique ResponseReference for storing against their original request. Hence the immediate response returned to the client will contain only a ResponseReference which should subsequently be used by the client to retrieve the results of the original request.

After receiving the ResponseReference for the asynchronous request the client should perform an HTTP to retrieve the results. This would be made to the retrieval URL in the format of:

https://interface.demo.gta-travel.com/gtaapi/RetrieveListenerServlet?TOKEN=REF_123456

(The beginning of the URL will be the same as the submission URL but  ‘RequestListenerServlet’ needs to be replaced with ‘RetrieveListenerServlet?TOKEN=’ and the relevant unique ResponseReference number returned for the initial request.)

Retrieve Response for given Reference – ready

If the response for the given reference is ready to be sent, the API retrieves it.

Retrieve Response for given Reference – not ready

If the response for the given reference is not ready to be sent, a corresponding XML error message will be returned:

<Errors>
    <Error>
        <ErrorId>XML0017</ErrorId>
        <ErrorText><![CDATA[The following TOKEN was not found: REF_123-12345678912345]]></ErrorText>
    </Error>
</Errors>

Some logic should be used when setting up the timings for the retrieval process. We suggest that you attempt the initial retrieval after 5 seconds. If the response is not ready at that stage we suggest you attempt further retrievals in the following intervals: 10 seconds – 30 seconds – 60 seconds – 5 minutes and after that in hourly intervals. This is only a suggestion and your settings will heavily depend on your business model as well as the fact whether you will use the token retrieval method for immediately available items only or also for on request items.

This method is not suitable for multi-item bookings as only one ResponseReference is returned for all booking items. If this ResponseReference is then retrieved, only the information about the booking item that was last updated by the GTA systems will be returned.

(ii)  Advantages

  • Having control over the timings updates are being requested and processed rather than having to process them as and when GTA pushes them back

(iii) Disadvantages

  • Not suitable for multi-item booking requests
  • Not suitable for booking modification messages if several modifications for one booking are sent within one request (multiple sub-requests within one XML message)
  • If bookings are updated by the GTA staff or by your own staff on the call centre site no booking updates will be sent to your systems
  • If used for processing on request items then a setting has to be worked out and put in place in regards to the intervals updates are being requested

Synchronous Mode With Response URL

i)     Details

It is possible to use the synchronous mode (refer to section 1) in conjunction with the response URL (refer to section 2a). In that case the initial response will be provided when we receive the request (for multi-item bookings this will only contain the update for one item), but any updates on the other items or further changes to the booking made by GTA staff or the client’s staff on the GTA web site will be pushed back to the response URL provided.

(i)    Advantages

  • Suitable for multi-item booking requests
  • Immediate booking updates are being pushed back to your server as soon as any booking changes have taken place on the GTA systems  
  • If bookings are updated by the GTA staff or by your own staff on the call centre site you will receive immediate booking updates  
  • Most suitable booking method for processing bookings for on request items
  • Suitable for booking modification messages if several modifications for one booking are sent within one request (multiple sub-requests within one XML message)

(ii)  Disadvantages

  • Requires the set-up of an application that has to be constantly listening for any updates attempted to be posted by the GTA server

General Information

1.    Booking Response Times

a)    Immediately Available Bookings

For bookings that are immediately available a response is generated by our server with a ‘Confirmed’ status within a few seconds.

b)   On Request Bookings

For bookings that are on request (or immediately available bookings which carry a free-format remark) it will take 90 seconds before the first response is generated by our server, usually with a ‘Confirmation Pending’ status, regardless which of the booking methods described above is used. This is due to the fact that for those clients using the synchronous mode we are trying for this long to generate an immediate confirmation. Only if we cannot return a ‘Confirmed’ response after 90 seconds we will generate a response with the current actual bookings status, which is usually a ‘Pending Confirmation’ status. This cannot be changed and since it should be known before posting a booking request whether an immediate confirmation is expected or not and instant response for an on request booking should not be required and an alternative message can be displayed to the customer instead of waiting 90 seconds for the ‘Pending Confirmation’  response.

2.    Booking Confirmations

a)    Immediately Available Bookings

For bookings that are immediately available a response should be generated by our server with a ‘Confirmed’ status within a few seconds. However, on very few occasions it is possible that even though we returned immediate availability for a property moments before this is no longer available at the time you post the booking to us. You always MUST check the booking item status in the booking response message before reconfirming any bookings to your customers and before issuing vouchers. Please note that if you add a free-format remark to an immediately available booking this will convert the booking request to an on-request booking.

b)   On Request Bookings

For bookings that are on request we aim to return the final booking status within 24 hours. Please be aware that on occasions, especially weekends and bank holidays, we are unable to contact the hotel within this time frame and a final booking response might take longer.

3.    Credit Card Processing

(This only applies to those of our XML clients for whom we are acting as the merchant)

When adding a booking with a credit card payment, it is necessary to check the payment status. The booking status; e.g.: C (Confirmed) or CP (Pending Confirmation) will not be an indication whether the payment by credit card was successful or has failed.

It is therefore necessary to check the <BookingPaymentStatus> by running a <SearchBookingRequest> regardless of the booking status. If the <BookingPaymentStatus> is <Success>true</Success> the credit card has been accepted and the transaction was successful. If the <BookingPaymentStatus> is <Success>false</Success> the credit card transaction has failed and if payment is not assigned to the booking by the deadline date*, the booking will be cancelled automatically by our systems.

Another indicator whether the payment has gone through or not is the value returned for the <BalanceAmount> parameter. As long as this is not ‘0.00’ the payment is still outstanding.

*Deadline date: The bookings will auto-cancel 3 days after creation date if payment has not been made. If a booking is made within 3 days from the departure date then the booking will cancel at midnight on the day it was made.

We only process the credit card validation after the booking request and when the BookingStatus ( not the ItemStatus) has moved to ’C’. It is therefore possible that a booking can be in a confirmed status even if the credit card has been declined or rejected.


4.    Failed Booking Requests

If you have any failed booking requests for which you did not receive a response at all or for which you received ANY kind of error, you MUST send a cancellation request if you no longer require the booking. Occasionally it is possible that we processed and confirmed your request and you were unable to receive the response and would be liable for payment.

In order to cancel a booking for which you have received no response via the XML API it is not necessary to use the GTA API reference number (which you would not have received in these cases anyway). It is possible and recommended to cancel all bookings using the unique <BookingReference> you used with your <AddBookingRequest>.

5. Time-Out For Booking Confirmations

If you are only working with immediately available properties you may have set a time-out value at your end by which you would expect to have received a confirmation from us to your booking request. If this is the case and you no longer require a confirmation after the set time-out value you MUST send a cancellation request to us otherwise we will return a confirmation at a later stage and you would be liable for payment.

In order to cancel a booking for which you have received no response via the XML API it is not necessary to use the GTA API reference number (which you would not have received in these cases anyway). It is possible and recommended to cancel all bookings using the unique <BookingReference> you used with your <AddBookingRequest>.

 

 

Docs Navigation