1.0 Authorization

For Authorization, we use the The OAuth 2.0 Authorization Framework

The OAuth 2.0 protocol is implemented as described in RFC 6749.
The client needs to obtain an Access Token using the Authorization Code Grant flow.

Two pieces of data is needed to register as a client -

Once we receive these, the client will be registered and a clientID will be provided; which should be used in the above Authorization flow.

The endpoint addresses are as follows -

  • Authorization Endpoint - https://connect.classicvacations.com/AuthorizationServer/OAuth/Authorize
  • Token Endpoint - https://connect.classicvacations.com/AuthorizationServer/OAuth/Token

PLEASE NOTE :

As part of the Authorization JWT response, the access_token and the refresh_token are generated.
TTL(Time to Live) for the generated access_token = 30 minutes
TTL(Time to Live) for the generated refresh_token = 12 hours

With the above information in mind:
  • Within 12 hours, a new access_token can be obtained using the same refresh_token.
  • After 12 hours, users will have to generate a new Authorization JWT response where a new set of access_token and refresh_token can be obtained again. This is as per the configuration defined in auth-service (where time is given in seconds).

Please find below the table of specific scopes to be added during Authorization to get access to a particular API

API Scope
GetBookings GetBookings
GetBookingDetails GetBookingDetails
GetGroupBookingDetails GetGroupBookingDetails
GetGroupOverView GetGroupOverView
GeneratePaymentContext MakePayment
MakePayment MakePayment
GetPaymentDetails GetPayment

2.1 FIT APIs

2.1.1 GetBookings

Booking with full payment, partial payment, and Options are now available via the following APIs.

2.1.1.1 ByTravellersLastName

End point Address -
  • https://connect.classicvacations.com/ResourceServer/api/GetBookings/ByTravellersLastName/{lastname}

Input fields 

lastname
The last name of the lead traveller, whose booking/(s) needs to be viewed.

2.1.1.2 ByBookedDateRange

This API can be used to get all the bookings made during the specified date range.
End point Address -
  • https://connect.classicvacations.com/ResourceServer/api/GetBookings/ByBookedDateRange/start={startDate}&end={endDate}

Input fields 

startDate
The start date in the yyyy-mm-dd format 
endDate
The end date in the yyyy-mm-dd format

Output fields

The above two APIs return an array Bookings -

Booking object

  • AgentName - The Travel Agent who made the booking
  • LeadTravellerName - The lead traveller on the booking
  • BookingID - The unique identifier associated with this booking
  • BookingDate - The date when this booking was made
  • DepartureDate - The date when the travel is started
  • Destination - The region to where the booking is departing
  • AmountPosted - The amount paid, for this booking
  • AmountDue - The amount due, for this booking
  • DueDate - The payment due date for this booking
  • TotalSell - Total amount on this booking
  • Commission - The commission earned for this booking

Example result

2.1.2 GetBookingDetails

This API can be used to get all components of a booking.
End point Address -
  • https://connect.classicvacations.com/ResourceServer/api/GetBookingDetails/{BookingID}

2.1.2.1 Input fields 

BookingID
The unique identifier for the booking

2.1.2.2 Output fields

Bookings object

Names

An array of all the passenger names.
  • Title
  • FirstName
  • LastName
  • MiddleName

Detail Item

An array of all the items in this booking.
  • BeginDate - Start date of service for this item

  • BeginTime - Time when the service begins

  • VendorID - An ID for the Vendor who is providing the service

  • ProductID - An ID for the product, eg TourID, RoomID etc

  • PartyName - The Lead passenger's name

  • ArrivalLoc - The arrival location for this item

  • UseLoc - The departure location for this item

  • EndDate - Last date of service for this item

  • EndTime - Time when the service ends

  • VendorConf - Confirmation number provided by the Vendor

  • VendorName - Name of the Vendor who is providing the service

  • ProductName - Name of the product, eg Tour Name, Room name etc

  • ItemKey - A unique identifier for this item

  • InternalComments - Comments issued by Classic Vacations to the Vendor

  • FlightPassengers - Will be populated only when DetailType is AIR. The Passengers travelling in this Flight

  • FlightSeatMapping - Will be populated only when DetailType is AIR. The seats, if chosen, of the passengers

  • FlightStartAirportCity - Will be populated only when DetailType is AIR. The Airport name and city of the departing location

  • FlightEndAirportCity - Will be populated only when DetailType is AIR. The Airport name and city of the arriving location

  • DurationHours - Will be populated only when DetailType is EXCURSION. Duration of the tour

  • TourTime - Will be populated only when DetailType is EXCURSION. Start time of the tour

  • Conditions - Conditions of the Vendors for use of this service

  • HotelPassengers - Will be populated only when DetailType is HOTEL. All the passengers staying at this room.

  • DriverPickUpLoc - Will be populated only when DetailType is CAR. The lead Driver and the pick-up location of the Car Rental

  • DetailType - These are all the detail types.

    1. FLIGHT

    2. HOTEL

    3. HOTEL_SERVICES

    4. TRANSFERS

    5. CRUISE

    6. CAR

    7. EXCURSION

    8. CONCIERGE

    9. MERCHANDISE

    10. RAIL

    11. TSP_WAIVER

    12. SERVICE_FEE

    13. CANCEL


  • BaseAmount - Base amount of the current detail item.

  • TaxAmount - Tax of the current detail item.

  • CommissionAmount - Commission for the current detail item.

  • VendorInfo - Vendor Information of the current detail item.

Payment Info

  • SellAmount - Total amount on this booking
  • CommAmount - The commission earned for this booking
  • TaxAmount - Total tax charged on this booking
  • AmountBeforeTax - Cost before tax
  • DepAmountDue - The first minimun payment amount required
  • AmountPosted - The amount paid, for this booking
  • CurrAmountDue - The amount due
  • DueDate - The payment due date for this booking

Adults

The number of adults travelling in this booking

Children

The number of children travelling in this booking

Example result


3.1 Group APIs

3.1.1 GetGroupOverView

This API can be used to get all components of a Group.
End point Address -
  • https://connect.classicvacations.com/ResourceServer/api/GetGroupOverView/{GroupID}

3.1.1.1 Input fields 

GroupID
The unique identifier for the Group

3.1.1.2 Output fields

GroupOverView object

GroupTitle

The title of the Group

GroupNumber

Unique ID for this Group, also called GroupID.

GroupStatus

Integer indicating the status of the Group.

GroupType

Type of the group.

Destination

The detination to where this Group is travelling to.

GroupBooking

An array of all the individual bookings in this Group.
  • BookingID - Start date of service for this item

  • BookingName - Time when the service begins

Payment Info

  • SellAmount - Total amount on this booking
  • CommAmount - The commission earned for this booking
  • TaxAmount - Total tax charged on this booking
  • AmountBeforeTax - Cost before tax
  • DepAmountDue - The first minimun payment amount required
  • AmountPosted - The amount paid, for this booking
  • CurrAmountDue - The amount due
  • DueDate - The payment due date for this booking

Example result


3.1.2 GetGroupBookingDetails

This API can be used to get all components of a group booking.
End point Address -
  • https://connect.classicvacations.com/ResourceServer/api/GetGroupBookingDetails/groupID={GroupID}&bookingID={BookingID}

3.1.2.1 Input fields 

GroupID
The unique identifier for the Group 
BookingID
The unique identifier for a particular booking under this group.

3.1.2.2 Output fields

Group Bookings object

BookingID

An array of all the passenger names.

Booking Description

An array of all the passenger names.

Departure Date

An array of all the passenger names.

PassengersName

An array of all the passenger names.
  • Title
  • FirstName
  • LastName
  • MiddleName

GroupDetail Item

An array of all the items in this booking.
  • BeginDate - Start date of service for this item

  • BeginTime - Time when the service begins

  • VendorID - An ID for the Vendor who is providing the service

  • ProductID - An ID for the product, eg TourID, RoomID etc

  • PartyName - The Lead passenger's name

  • ArrivalLoc - The arrival location for this item

  • UseLoc - The departure location for this item

  • EndDate - Last date of service for this item

  • EndTime - Time when the service ends

  • VendorConf - Confirmation number provided by the Vendor

  • VendorName - Name of the Vendor who is providing the service

  • ProductName - Name of the product, eg Tour Name, Room name etc

  • ItemKey - A unique identifier for this item

  • InternalComments - Comments issued by Classic Vacations to the Vendor

  • FlightPassengers - Will be populated only when DetailType is AIR. The Passengers travelling in this Flight

  • FlightSeatMapping - Will be populated only when DetailType is AIR. The seats, if chosen, of the passengers

  • FlightStartAirportCity - Will be populated only when DetailType is AIR. The Airport name and city of the departing location

  • FlightEndAirportCity - Will be populated only when DetailType is AIR. The Airport name and city of the arriving location

  • DurationHours - Will be populated only when DetailType is EXCURSION. Duration of the tour

  • TourTime - Will be populated only when DetailType is EXCURSION. Start time of the tour

  • Conditions - Conditions of the Vendors for use of this service

  • HotelPassengers - Will be populated only when DetailType is HOTEL. All the passengers staying at this room.

  • DriverPickUpLoc - Will be populated only when DetailType is CAR. The lead Driver and the pick-up location of the Car Rental

  • DetailType - These are all the detail types.

    1. FLIGHT

    2. HOTEL

    3. Hotel Fee

    4. TRANSFER

    5. CAR

    6. EXCURSION

    7. Agency Fee

    8. Resort Fee

    9. INSURANCE

    10. CANCEL


  • VendorInfo - Vendor Information of the current detail item.

Example result


4. External Payment APIs

4.1 Generate Payment Context

Generate a Payment Context (JSON Web Token) that should be used to generate a JSON Web Encryption (JWE) by the client and used for making the payment.

End point Address -
  • https://connect.classicvacations.com/ResourceServer/v2/payments/context

Sample Request

Headers:
Authorization Bearer <token>
Content-Type application/json

Request Method: POST
Request Payload: No payload

4.2 Make Payment

This API can be used to do the payment for a group booking or FIT booking.

End point Address -
  • https://connect.classicvacations.com/ResourceServer/v2/payments

4.2.1 Input fields

payment_token

The client generated JSON Web Encryption (JWE) data object that has been encrypted using the RsaOaep encryption scheme and the JSON Web Key (JWK) provided in JWT, received by calling the GeneratePaymentContext API request. JWE is a standard that defines how data can be encrypted using JSON-based data structures. For details, see IETF RFC 7516 at RFC 7516

The process of securing the payment information, into a JWE, consists of below steps:

  • Step 1: Construct the payment JSON payload
  • Step 2: Extract the one-time public encryption key(JSON Web Key) from the JWT generated by GeneratePaymentContext API Call
  • Step 3: Use the JSON Web Key(JWK) and the user card data to generate a JWE data object.

    The resulting Encrypted Payment data consists of the following parts :

    • data—Structure that specifies the data to capture and store.
    • context—Structure that specifies the payment context that you obtained from the GeneratePaymentContext API request.
    • index—Component that must be set to 0.

      • The example of a basic structure of the payload:

      Sample payload :

    For values of different card types (data.paymentInformation.card.type) follow the below table as reference :

    Card Type Card Name
    001 Visa
    002 Mastercard
    003 American Express
    004 Discover
    005 Diners Club

    Please Note: Java Developers can refer to nimbusds library(nimbus-jose-jwt) to encrypt the data and generate the JWE.

client_reference_id

A unique identifier, generated by the client, that can be associated for the payment transaction. If the client_reference_id has already been used, then payment will not be processed. MaxLength: 40

booking_id

The unique identifier for the booking

group_id

The unique identifier for the group

amount_details

Details associated with the amount of payment to be done.
  • amount : Amount to be paid for the transaction. This value should be greater than zero(0). You can include a decimal point (.), but no other special characters.
  • currency : Currency used for the order. Use the three-character code for the currency. We support US Dollar i.e. "USD" only.

bill_to

The invoice details required for the payment completion.
  • country : Payment card billing country. Use the two-character codes for the country. Example: For United States - use code "US"
  • last_name : Customer’s last name. MaxLength: 60
  • address2 : Used for additional address information. Optional field. MaxLength: 60
  • address1 : Payment card billing street address as it appears on the credit card issuer’s records. MaxLength: 60
  • postal_code : Postal code for the billing address. The postal code must consist of 5 to 9 digits. When the billing country is the U.S., the 9-digit postal code must follow this format: [5 digits][dash][4 digits]. Example: 12345-6789
  • locality : Payment card billing city. This field must not contain colons (:). MaxLength: 50
  • administrative_area : State or province of the billing address. MaxLength: 20 Example: For Alabama, use code : "AL"; Michigan, use code : "MI"
  • first_name : Customer’s first name. MaxLength: 60
  • email : Customer's email address, including the full domain name. MaxLength: 255

Sample Request

Headers:
Authorization Bearer <token>
Content-Type application/json

Request Method: POST
Request Payload:

a.Group Payment

b.FIT Payment

4.2.2 Output fields

payment_status

The status of the payment transaction.

    Possible values:
  • SUCCESS
  • PENDING
  • FAIL

client_reference_id

The unique identifier that was input by client for the transaction. If the client_reference_id has already been used, then payment will not be processed. MaxLength: 40

error_message

A summarized error message is provided in case of failure of processing the payment.

errors

The specific details, if applicable, of the error pertaining to failure.
  • attribute : The specific attribute with validation issue is mentioned.
  • error_description : Validation failure message is provided.

Sample Response

  • Success

    HTTP Status Code: 201

    Response Body:
  • Pending

    HTTP Status Code: 201

    Response Body:
  • Failure

    HTTP Status Code: 400

    Response Body:

4.3 Get Payment Details

This API is used to get the details of the payment transaction for a group or FIT.

End point Address -
  • https://connect.classicvacations.com/ResourceServer/v2/payments/{client_reference_id}?group_id=&booking_id=

4.3.1 Input fields

client_reference_id

A unique identifier, generated by the client, that is associated with the payment transaction.

booking_id

The booking_id for which the payment has been done.

group_id

The group_id for which the payment has been done.

Example Endpoint URL with details -

  1. When payment done against a booking_id from a specific group_id :

    https://connect.classicvacations.com/ResourceServer/v2/payments/b8d450b8-04f2-11ee-be56-0242ac120002?group_id=282&booking_id=12

  2. When payment done against a booking_id :

    https://connect.classicvacations.com/ResourceServer/v2/payments/b8d450b8-04f2-11ee-be56-0242ac120003?booking_id=12345

  3. When payment done against a group_id :

    https://connect.classicvacations.com/ResourceServer/v2/payments/b8d450b8-04f2-11ee-be56-0242ac120004?group_id=283

4.3.2 Output fields

amount

The amount paid in this transaction.

currency

The currency in which the amount was paid.

created_at

The timestamp at which the transaction was created at the FIT or Groups end.

status

The payment status for the transaction associated with the client_reference_id.

booking_id

The unique identifier for the booking, if applicable, against which the payment was done.

group_id

The unique identifier for the group, if applicable, against which the payment was done.

client_reference_id

A unique identifier, generated by the client, that is associated with the payment transaction.

created_by

The user who initiated the payment.

message

If no transaction is found for the given search: A message as "Transaction not found." is returned.

Sample Request

Headers:

Authorization Bearer <token>
Content-Type application/json

Request Method: GET
Request Payload: No Payload

Sample Response

  • Success

    HTTP Status Code: 200

    Response Body:
  • No Transaction Found

    HTTP Status Code: 404

    Response Body: