Direct Connect - Hotel Service v4 - Getting Started

Hotel Service v4 API provides a method for Custom Hotel Source suppliers to provide hotel inventory, rates, and booking related functionality to users of the SAP Concur Online Booking Tool (OBT).

This guide provides information on how the hotel supplier can make their content available for Concur Travel users. Once the interface has been developed and certified with SAP Concur, the inventory will begin appearing in hotel searches by opted-in Travel users.

This API has client/server architecture, where SAP Concur services act as client, pulling information from the hotel suppliers, who acts as server, responding to requests.

Limitations

Access to this documentation does not provide access to the API. SAP Concur products are highly configurable, and not all clients will have access to all features.

Prior Versions

Hotel Service v2 documentation is available here.

Process Flow

This is a basic scenario encompassing all the functionality provided by Hotel Service v4 incorporated into Concur Travel starting from a hotel search through to confirmation of a booking, modification of booking, and ending with a cancellation.

A process flow diagram of the Hotel Service v4 API

Products and Editions

  • Concur Travel Professional Edition
  • Concur Travel Standard Edition

Scope Usage

  • None

Dependencies

  • None

Access Token Usage

  • None

Reservation and Read Requests

If a Read request does not arrive within five minutes for a given reservation, the supplier should treat that reservation as an orphan and should seek to cancel it.

Supported Operations

Operation Description
/hotels/search Perform the initial search for hotels.
/hotels/rates Retrieve hotel rates.
/hotels/ratedetails Retrieve details the rates of a property, guarantee, cancellation penalty, or nightly prices. This action is required if these details are missing from the /hotels/rates response.
/hotels/details Retrieve hotel description info including media.
/hotels/reservation Reserve hotel rate.
/hotels/reservation/read Read reservation details. Used to acknowledge the receipt of booking confirmation, as well as write information to itinerary while reserving a hotel.
/hotels/reservation/modify Modify given reservation.
/hotels/reservation/cancel Cancel specified reservation.

Supported OTA Codes

The current list of supported OTA codes for different code list types (RMA, HAC etc.) can be found here.

Supported Error Codes

The current list of supported OTA error codes can be found here.

Non Functional Requirements

Payload Limits

Please note that any responses higher than the suggested content-length may be dropped/truncated and result in an error.

Operation Maximum Response (content-length)
/hotels/search 5 MB
/hotels/rates 5 MB
/hotels/details 5 MB
/hotels/ratedetails 5 MB

All endpoints carry a timeout of 55 seconds. Some operations below support retries in case of 5xx errors as noted. No endpoints will attempt a retry in the event there is a timeout.

SAP Concur services have monitoring in place for each endpoint and will open a ticket with suppliers if a significant degradation or variance of service quality is detected.

Operation Recommended Response Times Support Retries (for 5xx errors)
/hotels/search < 5 seconds Yes
/hotels/rates < 5 seconds Yes
/hotels/details < 1 second Yes
/hotels/ratedetails < 1 second Yes
/hotels/reservation < 5 seconds No
/hotels/reservation/read < 1 second Yes
/hotels/reservation/modify < 5 seconds No
/hotels/reservation/cancel < 5 seconds No

Higher throughput allows system to scale and serve large number of travelers. We recommend suppliers provision for resources to support the following throughput.

Operation Recommended Throughput (Requests Per Minute)
/hotels/search < 50
/hotels/rates < 100
/hotels/details < 100
/hotels/ratedetails < 50
/hotels/reservation < 20
/hotels/reservation/read < 20
/hotels/reservation/modify < 10
/hotels/reservation/cancel < 10

Note: To prevent no show fees, duplicate bookings and other similar issues, we requires the Hotel Supplier auto-cancel a reservation if a corresponding /hotels/reservations/read call is not made by SAP Concur systems within 5 minutes after the /hotels/reservation call was made.

Emergency Technical Contact

The hotel supplier needs to provide emergency technical contact email that will be used for communication in case of blocking technical issues.

Testing Environment

We require the hotel supplier to provide a testing URL or specify properties for testing in a production URL. We require the ability to preform test bookings with test credit cards.

Security

PCI DSS Compliance

As sensitive data and payment card details are transferred via API, hotel suppliers are required to comply with PCI DSS standards.

HTTPS

We require Transport Layer Security v1.2 (TLS 1.2) or higher SSL protocol for data transfers. The hotel supplier is required to provide HTTPS URLs of its endpoint. Standard HTTPS port 443 should be used.

URLs

We will receive a single URL for each environment (Test and Production) from the hotel supplier. All requests will go to that URL.

Authentication

SAP Concur services will send a username and password in the HTTP header (Authorization) where the value of the header will be a base64 encoded string in the form of Basic <username:password>. If the username and password generates an authentication error, then there will be a HTTP 401 response.

HTTP Headers

SAP Concur services will send the following HTTP headers in every request. Please note that some libraries used to handle the requests may be case sensitive and that the SAP Concur login-id and traveler uuid are now part of the payload for each request and no longer available as headers.

Name Type Format Description
Authorization string base64 An encoded string in the form of Basic <username:password>.
Content-Type string - All communication with the HS4 API is by way of a application/json content type.
Accept string - SAP Concur will always set the Accept header to application/json.
concur-correlationid string - In order to assist with troubleshooting, SAP Concur provides a unique correlationId in the request header. This unique code can be used during troubleshooting as it identifies the API call in the log files.

On this page