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.

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

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.

Recommended Response Times and Retries

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.

Recommended Throughput

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

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 with a 256-bit AES cipher 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.

Confirmation Codes

Please note current definitions of ConfirmationCodeType differ from what was used in Hotel Service v2 (HSv2).

• RESERVATION: Maps to OTA Unique ID Type 14 and has no equivalent for HSv2. This will be the record locator of supplier PNR and will be provided in all subsequent read/modify/cancel request on a booking. This is optional and will be mostly pass through for SAP Concur systems.
• SUPPLIER_CONFIRMATION: (Required) Maps to OTA Unique ID Type 40 and represents supplier’s confirmation number. This also be provided in all subsequent read/modify/cancel request on a booking, and it is also used in the passive segment created in the GDS. (Equivalent to 14 in HSv2).
• HOTEL_CONFIRMATION: Maps to OTA Unique ID Type 10. Used by travelers if they want to change their reservation outside of SAP Concur Online Booking Tool. If the property confirmation code is not available, the supplier may send the aggregator confirmation code in this field. (Equivalent to 1000 in HSv2). This field will appear on the itinerary page together with SUPPLIER_CONFIRMATION confirmation number.
• CANCELLATION: (Required) Maps to OTA Unique ID Type 15 and is same as HSv2 and must be provided as a part of CancelDetails response object.
• CONCUR_GDS_REFERENCE: This is custom code for future use (Type 14) which will be sent by SAP Concur in read/modify requests and will provide Concur Booking Record Locator for passives.
• PASSIVE_CONFIRMATION: Use this code type to provide confirmation code value that you need to use in passive segment. If not provided value from SUPPLIER_CONFIRMATION is used instead in passive segment.
• PIN: Use this code type to provide any pin number that may be required to modify the booking at a later point. If provided this code will be returned back in all subsequent calls for this booking. (Sometimes sent as 1000 in HSv2)

Vendor/Supplier Provided Virtual Payment

With the current Hotel Service v2, several mechanisms are in place to support vendor provided virtual payments (not managed by SAP Concur) as required by different suppliers. With HSv4, support for the vendor provided virtual payment will be achieved through the acceptedPayments element. Details of this are below.

1. Suppliers wanting to use their own virtual payment solution will need to provide VENDOR_PROVIDED as one of the option in acceptedPayments element of RoomRate as returned in response of /hotels/rates endpoint.
2. If user selects this payment option during booking (/hotels/reservation endpoint), ReservationCriteria will have paymentModeIndicator set to value VENDOR_VIRTUAL_CARD. This indicator suggests that all payment will be handled by suppliers and no other payment details will be provided for this scenario.

Note: The acceptedPayments element should also contain all the cards that are accepted at the property. In the first release for Hotel, customers will have the option of selecting their own personal card or the vendor’s virtual card as payment for their reservation. Support for Policy rules around this option will be introduced in a subsequent release. If a rule exists where a ghost/corporate card is Required, this will override the VENDOR_PROVIDED option.

Error Handling

All HSv4 endpoints use consistent error handling. API responses can have one of the following HTTP response code:

As noted above, please ensure to provide appropriate OTA code for all application level errors (with HTTP 400 response code). SAP Concur rely on OTA Code to display localized message to end users. Please refer to OTA error code list for extensive list of error codes that are supported today. If you see a need for additional OTA codes to be supported, please contact Concur Support.

Errors should always be returned in an Error schema response. For example:

{
  "otaCode": 69,
  "message": “Minimum stay criteria not fulfilled"
}

If otaCode is missing in an error, then only generic error is displayed to user and may not provide proper context. Any message text from the supplier will be logged but SAP Concur does not support displaying of supplier generated error messages directly in the UI.

Schema

The schema is available at: Direct Connect - Hotel Service v4 - Schemas.

API Testing

To enable faster certification, Suppliers can use the following testing tools to validate the majority of functional and non-functional requirements of this API during the development phase. Please use these tools both during development and once development is complete.

Functional Testing

To download our functional testing tool package.

• Includes a Postman collection that validates responses for all API endpoints against the OpenAPI schema.
• Validates basic features of the API, for example search response has properties in specified radius; all properties in details response have hotel images; checkin and checkout dates are valid; all hotel rates have appropriate amenity codes; cancel penalties have valid cancel deadlines; etc.
• For more detailed instructions on how to run these tests please refer to the README inside the testing tool zip.

Performance Testing

To download our non-functional testing tool package.

• Includes taurus and jmeter test scripts.
• Running these tests validates against our Non Functional Requirements.
• For more detailed instructions on how to run these tests please refer to the README inside the testing tool zip.