Table of Contents

SwOTA API Integration Guide for Travel Partners

Quick Start

SwOTA (Seaware Web OTA) is a cruise booking API that enables travel agencies and partners to search, book, and manage cruise reservations directly integrated with our Seaware reservation system.

New to SwOTA? This guide provides a quick start overview. For comprehensive API documentation, see the SwOTA API Development Guide.

What You Can Do

  • Search & Book: Find available sailings, categories, and cabins

  • Manage Bookings: Create, modify, cancel bookings

  • Handle Payments: Process payments and refunds

  • Manage Profiles: Create and update customer profiles

  • Access Inventory: Real-time availability and pricing

  • Generate Documents: Booking confirmations, invoices

Technical Overview

API Protocols

SwOTA supports both REST and SOAP protocols.

  • Message Format: XML based on OpenTravel Alliance (OTA) standards with Seaware extensions

  • Security: REST uses Auth0 token authentication; SOAP uses SSL client certificate authentication

See API Protocols for detailed protocol comparison.

Environment URLs

REST Endpoints

  • Production: https://bookings.sw.travelhx.com/ota/rest/<MessageName>

  • Staging: https://bookings-stage.sw.travelhx.com/ota/rest/<MessageName>

  • Development: https://bookings-dev.sw.travelhx.com/ota/rest/<MessageName>

  • Example: https://bookings.sw.travelhx.com/ota/rest/OTA_PingRQ

SOAP Endpoints

Authentication & Security

REST Authentication (Auth0)

REST API access uses Auth0 token-based authentication.

To authenticate with the REST API:

  1. Obtain Credentials: Contact your integration manager to get your Auth0 client ID and client secret

  2. Get Access Token: Authenticate with Auth0 to receive a bearer token

  3. Make Requests: Include the bearer token in the Authorization header

Auth0 Token Endpoints

  • Staging: https://travelhx-backend-stage.eu.auth0.com/oauth/token

  • Production: https://partner-travelhx.eu.auth0.com/oauth/token

Audience Values

  • Staging: https://partner.dev.travelhx.dev/api

  • Production: https://partner.travelhx.com/api

Example Token Request:

curl --request POST \
  --url https://travelhx-backend-stage.eu.auth0.com/oauth/token \
  --header 'content-type: application/json' \
  --data '{"client_id":"YOUR_CLIENT_ID","client_secret":"YOUR_CLIENT_SECRET","audience":"https://partner.dev.travelhx.dev/api","grant_type":"client_credentials"}'

Making REST Requests with Bearer Token:

curl --request POST \
  --url https://bookings-dev.sw.travelhx.com/ota/rest/OTA_PingRQ \
  --header 'authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'content-type: application/xml' \
  --data '<OTA_PingRQ xmlns="http://www.opentravel.org/OTA/2003/05" Version="1.0" TimeStamp="2025-01-01T12:00:00Z"><EchoData>Test</EchoData></OTA_PingRQ>'

For more details, see the REST Testing Guide.

SOAP Authentication (SSL Client Certificates)

SOAP API access requires a valid SSL client certificate issued by HX.

  • Certificate Request: Contact your integration manager to request client certificates

  • Installation: Install the certificate in your HTTP client/application

  • Validation: Certificates are validated at the load balancer level before reaching the API

For more details, see the SOAP Testing Guide.

Point of Sale (POS) Element

Every request must include a POS element identifying your agency:

<POS>
  <Source>
    <RequestorID ID="YOUR_AGENCY_ID" Type="5" ID_Context="SEAWARE"/>
    <BookingChannel Type="1">
      <CompanyName>YOUR_COMPANY_NAME</CompanyName>
    </BookingChannel>
  </Source>
</POS>

Supported ID Types

Type

ID_Context

Description

5

SEAWARE

Our internal agency ID (Default)

5

IATA

IATA agency code

5

CLIA

CLIA agency ID

29

SEAWARE

Travel agent ID

1

SEAWARE

Direct customer ID

Core API Messages

1. Connection Test

Message: OTA_PingRQ/RS

<OTA_PingRQ Version="1.0" TimeStamp="2024-01-01T12:00:00Z">
  <EchoData>Test connection</EchoData>
</OTA_PingRQ>

2. Sailing Search

Message: OTA_CruiseSailAvailRQ/RS

<OTA_CruiseSailAvailRQ Version="1.0" TimeStamp="2024-01-01T12:00:00Z">
  <POS><!-- Your POS info --></POS>
  <SailingDateRange>
    <StartDateWindow EarliestDate="2024-06-01"/>
    <EndDateWindow LatestDate="2024-08-31"/>
  </SailingDateRange>
</OTA_CruiseSailAvailRQ>

3. Category Availability

Message: OTA_CruiseCategoryAvailRQ/RS

<OTA_CruiseCategoryAvailRQ Version="1.0" TimeStamp="2024-01-01T12:00:00Z">
  <POS><!-- Your POS info --></POS>
  <Guest/>
  <Guest/>
  <GuestCounts>
    <GuestCount Code="10" Quantity="2"/>
  </GuestCounts>
  <SailingInfo>
    <SelectedSailing VoyageID="VOYAGE123">
      <CruiseLine/>
    </SelectedSailing>
  </SailingInfo>
  <SelectedFare FareCode="BESTPRICE"/>
</OTA_CruiseCategoryAvailRQ>

4. Create Booking

Message: OTA_CruiseBookRQ/RS

<OTA_CruiseBookRQ Version="1.0" TimeStamp="2024-01-01T12:00:00Z">
  <POS><!-- Your POS info --></POS>
  <SailingInfo>
    <SelectedSailing VoyageID="VOYAGE123">
      <CruiseLine/>
    </SelectedSailing>
    <SelectedCategory PricedCategoryCode="A">
      <SelectedCabin CabinNumber="1001" GuestRefNumbers="1 2"/>
    </SelectedCategory>
  </SailingInfo>
  <ReservationInfo>
    <GuestDetails>
      <GuestDetail>
        <ContactInfo>
          <PersonName>
            <GivenName>John</GivenName>
            <Surname>Doe</Surname>
          </PersonName>
        </ContactInfo>
      </GuestDetail>
      <!-- Additional guests -->
    </GuestDetails>
  </ReservationInfo>
</OTA_CruiseBookRQ>

Payment Processing

Credit Card Payment

Message: OTA_CruisePaymentRQ/RS

<OTA_CruisePaymentRQ Version="1.0">
  <POS><!-- Your POS info --></POS>
  <ReservationPayment>
    <ReservationID ID="12345" Type="14" ID_Context="SEAWARE"/>
    <PaymentDetail PaymentType="5">
      <PaymentCard ExpireDate="1225">
        <CardType Code="1">VISA</CardType>
        <CardHolderName>John Doe</CardHolderName>
        <CardNumber>
          <PlainText>4111111111111111</PlainText>
        </CardNumber>
      </PaymentCard>
      <PaymentAmount Amount="500.00" CurrencyCode="USD"/>
    </PaymentDetail>
  </ReservationPayment>
</OTA_CruisePaymentRQ>

Testing Your Integration

Development Environment Setup

  1. Install Development Certificate: Request and install SSL certificate

  2. Test Credentials: Use agency ID TEST with booking source OPENTRAVEL

  3. Expected Response: Error Code 168 (Agent not recognised) - This confirms your message format and certificate are working!

Sample Requests

We provide the following sample requests for API calls:

Request Type

File

Description

Connection Test

Ping

Basic connectivity test

Sailing Search

Sailing-Availability

Search for available sailings within a given date range.

Category Availability

Category-Availability

Get available cabin categories for a specific sailing for a certain number of guests.

Cabin Availability

Cabin-Availability

Get specific, assignable cabins within a chosen category.

Price a Booking

Price-a-Booking

Get an itemized price for a full booking configuration before creating it.

Hold a Cabin

Hold-a-Cabin

Temporarily reserve one or more cabins without immediate payment.

Create a Booking

Create-a-Booking

Create a (Multi-Cabin) Booking

Retrieve a Booking

Retrieve-a-Booking

Fetch the details of an existing booking using its confirmation ID.

Cancel a Booking

Cancel-a-Booking

Cancel a confirmed reservation.

Unhold a Cabin

Unhold-a-Cabin

Release a cabin that was previously on hold.

Dining Availability

Dining-Availability

Query for available dining times and venues on a sailing.

Shore Excursion Availability

Shore-Excursion-Availability

Get a list of available tours for a given sailing.

Cancellation Pricing

Cancellation-Pricing

Check the cancellation fees before cancelling.

Booking History

Booking-History

Get a log of all changes made to a booking.

Create a Guest Profile

Create-a-Guest-Profile

Create a guest profile in the system.

Read a Guest Profile

Read-a-Guest-Profile

Retrieve a guest profile from the system.

Modify a Guest Profile

Modify-a-Guest-Profile

Update a guest profile in the system.

Fare Availability

Fare-Availability

Get a list of available fares for a specific sailing.

Make a Payment

Make-a-Payment

Submit a payment for an existing booking.

Send Booking Documents

Send-Booking-Documents

Send Booking Documents

Complete Message Catalog

Availability & Search

  • OTA_CruiseSailAvailRQ/RS - Search available sailings

  • OTA_CruiseCategoryAvailRQ/RS - Get cabin categories

  • OTA_CruiseCabinAvailRQ/RS - Find available cabins

  • OTA_CruiseFareAvailRQ/RS - Search fare options

  • OTA_CruiseDiningAvailRQ/RS - Dining availability

  • OTA_CruiseShorexAvailRQ/RS - Shore excursion options

Booking Management

  • OTA_CruiseBookRQ/RS - Create/modify bookings

  • OTA_CruisePriceBookingRQ/RS - Get detailed pricing

  • OTA_ReadRQ/OTA_ResRetrieveRS - Retrieve booking details

  • OTA_CancelRQ/RS - Cancel reservations

Inventory Management

  • OTA_CruiseCabinHoldRQ/RS - Hold cabin inventory

  • OTA_CruiseCabinUnholdRQ/RS - Release cabin holds

Payment & Financial

  • OTA_CruisePaymentRQ/RS - Process payments

  • OTA_CruiseCancellationPricingRQ/RS - Get cancellation fees

Profile Management

  • OTA_ProfileCreateRQ/RS - Create customer profile

  • OTA_ProfileModifyRQ/RS - Update profile

  • OTA_ReadRQ/OTA_ProfileReadRS - Retrieve profile

Documents & Communication

  • OTA_CruiseBookingDocumentRQ/RS - Send booking documents

Advanced Features

Stateful Mode (Temporary Storage)

Use TransactionActionCode attribute for complex booking scenarios:

  • Initiate - Start temporary booking

  • Hold - Update and keep in temporary storage

  • Book - Finalize and store booking

  • Ignore - Cancel temporary booking

Multi-Cabin Bookings

Book multiple cabins in single request using GuestRefNumbers attribute:

<SelectedCabin CabinNumber="101" GuestRefNumbers="1 2"/>
<SelectedCabin CabinNumber="102" GuestRefNumbers="3 4"/>

Currency Support

Specify preferred currency in POS element:

<Source ISOCurrency="EUR">

Schema & Technical References

WSDL & Schema Files

  • Primary WSDL: SwOTA.wsdl

  • OTA Schemas: Available on request from https://opentravel.org

  • Key Schemas:

    • OTA_CruiseCommonTypes.xsd - Common data types

    • OTA_CruiseBookRQ.xsd - Booking request structure

    • OTA_CommonTypes.xsd - General OTA types

Code Lists

API supports OpenTravel Alliance standard code lists:

  • Guest Types: Code "10" = Adult, "8" = Child, etc.

  • Reservation Types: Type "14" = Booking Reference

  • Payment Types: Type "5" = Credit Card, "1" = Cash

  • Status Codes: "36" = Available, "46" = Waitlisted

Message Patterns

All responses follow standard OTA patterns:

  • Success: element present

  • Warnings: element with non-blocking issues

  • Errors: element with blocking problems

Integration Pattern

Stateless Integration

Both REST and SOAP support stateless integration where each request contains all necessary information.

REST Integration

REST requests use Auth0 bearer tokens for authentication:

POST https://bookings.sw.travelhx.com/ota/rest/OTA_MessageTypeRQ
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/xml

<OTA_MessageTypeRQ xmlns="http://www.opentravel.org/OTA/2003/05" Version="1.0" TimeStamp="2024-01-01T12:00:00Z">
<!-- Always include POS with your agency identification -->
<POS>
<Source>
<RequestorID ID="YOUR_AGENCY_ID" Type="5" ID_Context="SEAWARE"/>
<BookingChannel Type="1">
<CompanyName>YOUR_COMPANY_NAME</CompanyName>
</BookingChannel>
</Source>
</POS>
<!-- Message-specific content -->
</OTA_MessageTypeRQ>

SOAP Integration

SOAP requests use SSL client certificates for authentication:

<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
  <Header/>
  <Body>
    <OTA_MessageTypeRQ xmlns="http://www.opentravel.org/OTA/2003/05" Version="1.0" TimeStamp="2024-01-01T12:00:00Z">
      <!-- Always include POS with your agency identification -->
      <POS>
        <Source>
          <RequestorID ID="YOUR_AGENCY_ID" Type="5" ID_Context="SEAWARE"/>
          <BookingChannel Type="1">
            <CompanyName>YOUR_COMPANY_NAME</CompanyName>
          </BookingChannel>
        </Source>
      </POS>
      <!-- Message-specific content -->
    </OTA_MessageTypeRQ>
  </Body>
</Envelope>

Key Requirements:

  • REST: Bearer token must be included in Authorization header with every request

  • SOAP: SSL client certificate must be presented with every request

  • POS element must identify your agency in every message

  • All requests are stateless - no session management needed

Support & Resources

Getting Production Access

  1. Contact: Your account manager

  2. Provide: Company details, expected volume, integration timeline

  3. Certificate Request: Request SSL client certificates

  4. Receive: Agency setup, client certificates

  5. Technical Review: Certificate installation and connectivity verification

  6. Certification: Complete booking flow validation

Next Steps

This guide covers the core integration requirements. For detailed technical documentation, see the SwOTA API Development Guide. For specific business rules, advanced features, or custom requirements, please contact our technical team.

Last Updated: December 2025