The Java SDK aims to help implement all API calls coming from the airline backend. It will automatically retrieve and renew authentication tokens required to consume the Hopper Cloud Airlines API.
Gradle:
dependencies {
implementation group: 'com.hopper.cloud', name: 'cloud-airlines-java', version: '1.4.1'
}
Maven:
<!-- https://mvnrepository.com/artifact/com.hopper.cloud/cloud-airlines-java -->
<dependency>
<groupId>com.hopper.cloud</groupId>
<artifactId>cloud-airlines-java</artifactId>
<version>1.4.1</version>
</dependency>
- Endpoint URL: Will be provided by Hopper for each environment
- Client ID: Will be provided by Hopper for each environment
- Client Secret: Will be provided by Hopper for each environment
- Payment Url: Will be provided by Hopper for each environment
- Payment Username: Will be provided by Hopper for each environment
- Payment Password: Will be provided by Hopper for each environment
- Debugging : True to log input and output
HopperClient client = new HopperClient(endpointUrl, clientId, clientSecret, paymentUrl, paymentUsername, paymentPassword, debugging);
It has to be called each time an end-customer begins shopping on the airline website.
The returned sessionId will then be required in all subsequent calls to the API from the backend, but also from the frontend using the SDK, so it has to be returned to the airline frontend.
Parameters
flowType
required |
Enum
Possible values: PURCHASE, EXERCISE The flow type for which the session is opened. |
userInfo |
An object containing information related to the airline's user. Should be included if known, but not if the user is anonymous. |
device |
The end-user's device |
pointOfSale
required |
String
Example: US An ISO 3166-1-alpha-2 country code; the point of sale of the user |
language
required |
string
Example: es An ISO_639-1 country code; the language associated with the user |
Return value
id
required |
String
Example: 9fd3f2f9-e5aa-4128-ace9-3c4ee37b685f A unique identifier for a session |
Example :
CreateAirlineSessionRequest sessionRequest = new CreateAirlineSessionRequest();
sessionRequest.setLanguage("EN");
sessionRequest.setPointOfSale("US");
UserInfo userInfo = new UserInfo();
userInfo.setAirlineUserId("airline-test-1");
userInfo.setCreatedDateTime(LocalDateTime.now().atOffset(ZoneOffset.UTC));
userInfo.setPreviousBookings(1);
Device device = new Device();
device.setId("airlines-test-device-1");
device.setType(DeviceType.DESKTOP);
Platform platform = new Platform();
platform.setType(PlatformType.WEB);
Browser browser = new Browser();
browser.setType(BrowserType.CHROME);
browser.setVersion("103.0.5060.53");
OperatingSystem operatingSystem = new OperatingSystem();
operatingSystem.setType(OperatingSystemType.MAC_OS);
operatingSystem.setVersion("monterey");
platform.setBrowser(browser);
platform.setOperatingSystem(operatingSystem);
device.setPlatform(platform);
sessionRequest.setDevice(device);
sessionRequest.setUserInfo(userInfo);
AirlineSession session = client.createSession(sessionRequest);
Called to retrieve details of a contract in order to update the shopping cart with the right amount
Parameters
sessionId
required |
String
Example: 9fd3f2f9-e5aa-4128-ace9-3c4ee37b685f A unique identifier for a session |
id
required |
String
Example: af585dfd-dddf-4726-9ef7-f1bb8909a79a A unique identifier for a contract |
Return value
contract
required |
CfarContract
The CFAR Contract |
CfarContract getContract = client.getContract(sessionId,contractId);
Parameters
sessionId
required |
String
Example: 9fd3f2f9-e5aa-4128-ace9-3c4ee37b685f A unique identifier for a session |
contractId
required |
String
Example: af585dfd-dddf-4726-9ef7-f1bb8909a79a A unique identifier for a contract |
number
required |
String
The full card number |
verificationValue
required |
String
The verification value (CVV/CVC) of the card |
month
required |
String
The expiration month of the card |
year
required |
String
The expiration year of the card |
firstName
required |
String
The first name of the cardholder |
lastName
required |
String
The last name of the cardholder |
addressLine1 | String
The first line of the billing address |
addressLine2 | String
The second line of the billing address |
city | String
The city of the billing address |
stateOrProvince | String
The state or province of the billing address |
postalCode | String
The postal code of the billing address |
country | String
The country of the billing address |
pnrReference
required |
String
Example: ABC123 Reference of the PNR in the airline system |
emailAddress
required |
String
Example: john@doe.com Contact email of the end customer |
Return value
succeeded
required |
boolean
True if the payment succeeded, false if not |
ProcessCfarPaymentRequest processCfarPaymentRequest = new ProcessCfarPaymentRequest();
processCfarPaymentRequest.setNumber("4111111111111111");
processCfarPaymentRequest.setMonth("09");
processCfarPaymentRequest.setYear("26");
processCfarPaymentRequest.setVerificationValue("123");
processCfarPaymentRequest.setFirstName("John");
processCfarPaymentRequest.setLastName("Smith");
processCfarPaymentRequest.setAddressLine1("123 12th St");
processCfarPaymentRequest.setAddressLine2("Building B");
processCfarPaymentRequest.setCity("Quebec City");
processCfarPaymentRequest.setPostalCode("G1R 4S9");
processCfarPaymentRequest.setStateOrProvince("QC");
processCfarPaymentRequest.setCountry("CA");
processCfarPaymentRequest.setEmailAddress("test@email.com");
processCfarPaymentRequest.setPnrReference("AB1234");
boolean succeeded = client.processCfarPayment(sessionId, contractId, processCfarPaymentRequest);
It has to be called after the payment details have been transferred, to confirm the contract.
Parameters
sessionId
required |
String
Example: 9fd3f2f9-e5aa-4128-ace9-3c4ee37b685f A unique identifier for a session |
contractReference
required |
String
Example: RNNPN5QAFKZ1TBHC The reference of the contract |
status
required |
Enum
Possible values : "created" "confirmed" "failed" "charged_back" "voided" "canceled" The new status of the contract |
pnrReference
required |
String
Example: ABC123 Reference of the PNR in the airline system |
emailAddress
required |
String
Example: john@doe.com Contact email of the end customer |
pnrReference
required |
String
Example: ABC123 Reference of the PNR in the airline system |
phoneNumber | String
Example: 12345678900 Phone number of the customer |
firstName | String
Example: John First name of the cardholder |
lastName | String
Example: Smith Last name of the cardholder |
addressLine1 | String
Example: 123 12th St Address of the cardholder (first line) |
addressLine2 | String
Example: Building B Address of the cardholder (second line) |
city | String
City of the cardholder |
stateOrProvince | String
State or province of the cardholder |
postalCode | String
Postal code of the cardholder |
country | String
Country of the cardholder |
taxesTotal | string >= 0
Example: 35.50 Part of the premium which are taxes |
taxes |
array ( CfarTax ) List of applicable taxes |
Return value
contract
required |
The updated CFAR Contract |
Example :
UpdateCfarContractRequest updateCfarContractRequest = new UpdateCfarContractRequest();
updateCfarContractRequest.setEmailAddress("test@test.com");
updateCfarContractRequest.setStatus(CfarStatus.CONFIRMED);
updateCfarContractRequest.setPnrReference("ABC123");
updateCfarContractRequest.setPhoneNumber("123456789");
updateCfarContractRequest.setFirstName("John");
updateCfarContractRequest.setLastName("Smith");
updateCfarContractRequest.setAddressLine1("123 12th St");
updateCfarContractRequest.setAddressLine2("Building B");
updateCfarContractRequest.setCity("Quebec City");
updateCfarContractRequest.setPostalCode("G1R 4S9");
updateCfarContractRequest.setStateOrProvince("QC");
updateCfarContractRequest.setCountry("CA");
CfarContract contract = client.updateCfarContractStatus(sessionId,contractReference, updateCfarContractRequest);
Parameters
contractId
required |
string
Example: 1ec9ef29-be31-6ed3-beec-9f5ae0d164ee A unique identifier for a CFAR contract |
itinerary
required |
Itinerary of the user when the contract exercise was initiated (only active segments should be provided) |
pnrReference
required |
string
Example:ABC123 Reference of the PNR in the airline system |
emailAddress | string
Example: john@doe.com Contact email address of the booking at exercise time |
airlineRefundPenalty | string >= 0
Example:99.00 The penalty fee applied by the airline when issuing a refund for the booking |
airlineRefundMethod | string
Enum: "cash" "ftc" The refund method used by the airline |
currency | string
Example:CAD The currency of the airline's refund allowance |
extAttributes | object (map_string)
An array of arbitrary key-value pairs for storing airline-specific entity metadata |
Return value
id
required |
string
Example:1ec9ef4b-b3bf-64ae-8a3d-6b084d9f6b3c Unique identifier for a CFAR exercise |
contractId
required |
string
Example:1ec9ef29-be31-6ed3-beec-9f5ae0d164ee Unique identifier for a contract |
exerciseInitiatedDateTime
required |
string <date-time>
Example:2022-03-08T15:20:30Z A UTC RFC3339 datetime; the date and time at which a contract exercise was initiated |
cashRefundAllowance
required |
string
Example:49.32 Refundable amount allowed in cash |
ftcRefundAllowance | string >= 0
Example:123.20 Refundable amount allowed in future travel credit |
currency | string
Example:CAD The currency of the airline's refund allowance |
redirectionToken | string
Token used to authenticate the redirection after filling refund information in claims portal |
redirectionUrl
required |
string
URL on which the customer should be redirected to exercise (if applicable) |
extAttributes
required |
object (map_string)
An array of arbitrary key-value pairs for storing airline-specific entity metadata |
Example :
CreateCfarContractExerciseRequest createCfarContractExerciseRequest = new CreateCfarContractExerciseRequest();
createCfarContractExerciseRequest.setContractId(contractId);
createCfarContractExerciseRequest.setCurrency("CAD");
createCfarContractExerciseRequest.setPnrReference("ABC123");
Map<String, String> params = new HashMap<>();
params.put("property1", "test1");
params.put("property2", "test2");
createCfarContractExerciseRequest.setExtAttributes(params);
createCfarContractExerciseRequest.setAirlineRefundPenalty("146.64");
createCfarContractExerciseRequest.setAirlineRefundMethod(AirlineRefundMethod.CASH);
CfarItinerary itinerary = new CfarItinerary();
itinerary.setCurrency("CAD");
itinerary.setTotalPrice("183.30");
Ancillary ancillary = new Ancillary();
ancillary.setType(AncillaryType.TRAVEL_INSURANCE);
ancillary.setTotalPrice("30.55");
ancillary.setPassengerReference("1");
CfarPassenger pax = new CfarPassenger();
pax.setPassengerReference("1");
pax.setPassengerType(PassengerType.ADULT);
CfarItinerarySlice cfarItinerarySlice = new CfarItinerarySlice();
CfarItinerarySliceSegment cfarItinerarySliceSegment = new CfarItinerarySliceSegment();
cfarItinerarySliceSegment.setArrivalDateTime("2022-09-15T19:12:30");
cfarItinerarySliceSegment.setDepartureDateTime("2022-09-15T18:12:30");
cfarItinerarySliceSegment.setOriginAirport("LGA");
cfarItinerarySliceSegment.setDestinationAirport("BOS");
cfarItinerarySliceSegment.setFlightNumber("JB776");
cfarItinerarySliceSegment.setFareClass(FareClass.BASIC_ECONOMY);
cfarItinerarySliceSegment.setValidatingCarrierCode("B6");
CfarItinerarySliceSegment cfarItinerarySliceSegment2 = new CfarItinerarySliceSegment();
cfarItinerarySliceSegment2.setArrivalDateTime("2022-09-15T19:12:30");
cfarItinerarySliceSegment2.setDepartureDateTime("2022-09-15T18:12:30");
cfarItinerarySliceSegment2.setOriginAirport("LGA");
cfarItinerarySliceSegment2.setDestinationAirport("BOS");
cfarItinerarySliceSegment2.setFlightNumber("JB777");
cfarItinerarySliceSegment2.setFareClass(FareClass.BASIC_ECONOMY);
cfarItinerarySliceSegment2.setValidatingCarrierCode("B6");
List<CfarItinerarySliceSegment> segments = new ArrayList<>();
segments.add(cfarItinerarySliceSegment);
segments.add(cfarItinerarySliceSegment2);
cfarItinerarySlice.setSegments(segments);
cfarItinerarySlice.setFareBrand("economy");
PassengerPricing passengerPricing = new PassengerPricing();
passengerPricing.setIndividualPrice("61.10");
PassengerCount passengerCount = new PassengerCount();
passengerCount.count(3);
passengerCount.setType(PassengerType.ADULT);
passengerPricing.setPassengerCount(passengerCount);
itinerary.setSlices(Collections.singletonList(cfarItinerarySlice));
itinerary.setAncillaries(Collections.singletonList(ancillary));
itinerary.setPassengerPricing(Collections.singletonList(passengerPricing));
itinerary.setPassengers(Collections.singletonList(pax));
createCfarContractExerciseRequest.setItinerary(itinerary);
CfarContractExercise cfarContractExercise = client.createfarContractExercise(sessionId, createCfarContractExerciseRequest);
Parameters
sessionId
required |
string
Example: 9fd3f2f9-e5aa-4128-ace9-3c4ee37b685f The ID of the current session |
exerciseId
required |
string
Example: 35212c04-179b-4a9b-a939-89d99492a96d A unique identifier for a CFAR contract exercise |
refundAmount | string >= 0
Example: The amount refunded to the customer |
refundMethod | string
Enum: "cash" "ftc" The refund method chosen by the customer |
Return value
exercise
required |
CfarContractExercise
The CFAR exercise |
Example :
MarkCfarContractExerciseCompleteRequest markCfarContractExerciseCompleteRequest = new MarkCfarContractExerciseCompleteRequest();
CfarContractExercise exercise = client.completeCfarContractExercise(sessionId, markCfarContractExerciseCompleteRequest, exerciseId);
It allows to send an event to HTS
Parameters
sessionId
required |
string
Example: 9fd3f2f9-e5aa-4128-ace9-3c4ee37b685f The ID of the current session |
occuredDateTime | string <date-time>
Example: 2024-01-08T14:36:56.324Z A UTC RFC3339 datetime; the date and time at which the contract was created |
type
required |
String
Possible values: booking_confirmed, offers_displayed The event type |
Example :
Event event = new Event();
event.setType("booking_confirmed");
client.createEvent(sessionId, event);
id
required |
String
Example: 2bcd6619-ac3e-403b-9982-3e12f2698a54 A unique identifier for the end-user's device, generated by the airline |
platform |
The device’s platform |
type
required |
Enum
Possible values: DESKTOP, MOBILE, TABLET Type of device |
operatingSystem |
The platform’s Operating System |
browser |
The platform’s browser |
type
required |
Enum
Possible values: APP, WEB Type of platform |
version | String
Example: monterey Version of the operating system |
type
required |
Enum
Possible values: MAC_OS, WINDOWS, ANDROID, I_OS, CHROME_OS, LINUX, OTHER_OS Type of operating system |
type
required |
Enum
Possible values: CHROME, SAFARI, INTERNET_EXPLORER, EDGE, FIREFOX, OPERA, OTHER_BROWSER Type of browser |
airlineUserId
required |
String
Example: 2bcd6619-ac3e-403b-9982-3e12f2698a54 The airline's unique identifier for a user. |
createdDateTime | String <date-time>
Example: 2024-01-01T18:34:30Z A UTC RFC3339 datetime; the date and time at which a user's account was created |
previousBookings | Integer >= 0
Example: 3 Number of prior bookings a user has made |
id
required |
String
Example: 1ec9ef29-be31-6ed3-beec-9f5ae0d164ee Unique identifier for a contract |
offers
required |
array ( CfarOffer ) CFAR Offer(s) used to create the contract |
itinerary
required |
An object detailing the itinerary and fare used to create this CFAR contract |
premium
required |
string >= 0
Example: 80.00 Total amount to be paid for CFAR |
coverage
required |
string >= 0
Example: 98.64 Total amount to be refunded upon CFAR exercise |
coverage_percentage
required |
string >= 0
Example: 80.00 Percentage of the amount to be refunded to customer compared to flight tickets price |
taxes_total
required |
string >= 0
Example: 35.50 Part of the premium which are taxes |
taxes |
array ( CfarTax ) List of applicable taxes |
cfar_prices |
array ( CfarPrice ) The prices associated to contract. |
currency
required |
String
Example: USD Currency of contract |
status
required |
Enum: "created" "confirmed" "canceled" "exercised" "expired" |
created_date_time
required |
string <date-time>
Example: 2024-01-08T14:36:56.324Z A UTC RFC3339 datetime; the date and time at which the contract was created |
confirmed_date_time | string <date-time>
Example: 2024-01-09T15:37:57.325Z A UTC RFC3339 datetime; the date and time at which the contract was confirmed |
canceled_date_time | string <date-time>
Example: 2024-01-10T16:38:58.326Z A UTC RFC3339 datetime; the date and time at which the contract was canceled |
expiry_date_time
required |
string <date-time>
Example: 2024-06-01T15:00:00Z A UTC RFC3339 datetime; the date and time at which the CFAR contract will expire once purchased |
ext_attributes
required |
object (map_string)
An array of arbitrary key-value pairs for storing airline-specific entity metadata |
pnr_reference | string
Example: ABC123 Reference of the PNR in the airline system |
id
required |
String
Example: 1ec9eed3-4486-6460-9d6c-2fb8469d35db Unique identifier for an offer |
request_type
required |
string
Enum: "fare" "bundle" "ancillary" "post_booking" Type of CFAR offer |
itinerary
required |
An object detailing the itinerary and fare used to create this CFAR offer |
premium
required |
string >= 0
Example: 40.00 Total amount to be paid for CFAR |
coverage
required |
string >= 0
Example: 400.00 Total amount to be refunded upon CFAR exercise |
coverage_percentage
required |
string >= 0
Example: 80.0 Percentage of the amount to be refunded to customer compared to flight tickets price |
coverage_extension | string >= 0
Example: 40.0 Maximum amount added on top of the coverage to cover ancillaries |
currency
required |
String
Example: CAD Currency of offer |
taxes_total
required |
string >= 0
Example: 35.50 Part of the premium which are taxes |
taxes |
array ( CfarTax ) List of applicable taxes |
to_usd_exchange_rate
required |
string > 0
Example: 0.7796267926543563596106543797484144 USD Exchange rate for currency; amount * toUsdExchangeRate == USD |
contract_expiry_date_time
required |
string <date-time>
Example: 2024-04-01T22:34:30Z A UTC RFC3339 datetime; the date and time at which the CFAR contract will expire once purchased |
created_date_time
required |
string <date-time>
Example: 2024-01-08T14:36:56.324Z A UTC RFC3339 datetime; the date and time at which a CFAR offer was created |
ext_attributes
required |
object (map_string)
An array of arbitrary key-value pairs for storing airline-specific entity metadata |
contents
required |
object (map (CfarContents))
An array of arbitrary key-value pairs for storing airline-specific entity metadata |
terms_conditions_url | string
The terms and conditions URL for this offer |
passenger_pricing
required |
array ( PassengerPricing ) List of passengers type, count and pricing for the itinerary |
total_price
required |
string >=0
Example: 401.10 Total price of the itinerary |
currency
required |
string
Example: CAD Currency of pricing fields |
slices
required |
array ( CfarItinerarySlice ) List of slices of the itinerary; 1 (one way), 2 (round trip) or up to 10 (multi-destination) slices are allowed |
ancillaries |
array ( Ancillary ) Ancillaries attached to the itinerary and their prices |
passengers |
array ( CfarPassenger ) Details of the passengers |
fare_rules |
array ( FareRule ) The fare rules associated to the itinerary. If different fare rules apply to different slices in the itinerary, indicate the most restrictive. |
passenger_reference
required |
string
Unique reference of the passenger |
passenger_type
required |
string
Enum: "adult" "child" "seated_infant" "lap_infant" The type of passenger: * adult - 12+ years of age * child - 2-11 years of age * seated_infant - < 2 years of age, in their own seat * lap_infant - < 2 years of age, not in their own seat |
first_name | string
The first name of the passenger |
last_name | string
The last name of the passenger |
date_of_birth | string
Example: 2000-04-02 The birth date in ISO Local Date format |
gender | string
Enum: "male" "female" "undisclosed" "unspecified" The gender of the passenger |
code
required |
string
Example: RC The code of the tax |
amount
required |
string >= 0
Example: 0.20 The amount of the tax |
currency
required |
string
Example: USD The currency of the tax |
name
required |
string
Example: CAD The name of the tax |
rate
required |
string >= 0
Example: 0.20 The rate of the tax |
amount
required |
string >= 0
Example: 20.20 The amount of the tax |
estimated
required |
boolean
true if the tax amount is estimated. The real amount will be known only at contract confirmation |
registration_number | string
Example: 0123456ABCDEF The registration number of the tax if applicable |
passenger_type | string
Enum: "adult" "child" "seated_infant" "lap_infant" The type of passenger: * adult - 12+ years of age * child - 2-11 years of age * seated_infant - < 2 years of age, in their own seat * lap_infant - < 2 years of age, not in their own seat |
nb_pax | int
The number of passengers associated with the price |
coverage
required |
string >= 0
Example: 98.64 Total amount to be refunded |
premium
required |
string >= 0
Example: 80.00 Total amount to be paid |
ancillary_type | string
Enum: "travel_insurance" "cabin_bag" "checked_bag" "seat" "lounge" "meal" "fast_track" "pet" "other" The type of ancillary |
passenger_reference | string
Unique reference of the passenger |
cfar_price_type | string
Enum: "ticket" "ancillary" The type of price |
passenger_count
required |
array (PassengerCount) Type and number of passengers |
individual_price | string >=0
Example: 200.55 Price per passenger |
taxes |
array (CfarPassengerTax) Taxes applicable to this itinerary |
count
required |
integer
Example: 3 Number of passenger type |
passenger_type
required |
string
Enum: "adult" "child" "seated_infant" "lap_infant" The type of passenger: * adult - 12+ years of age * child - 2-11 years of age * seated_infant - < 2 years of age, in their own seat * lap_infant - < 2 years of age, not in their own seat |
segments
required |
array ( CfarItinerarySliceSegment ) A list of segments which make up the slice |
passenger_pricing |
array ( PassengerPricing ) List of passengers type, count and pricing for the slice |
total_price | string >= 0
Example: 401.10 The price of the slice for all the passengers |
fare_brand | string
Example: flex Code of the fare brand applied to the slice |
fare_basis | string
Example: YBA123US Code of the fare basis applied to the slice |
fare_rules |
array ( FareRule ) The fare rules associated to the slice. |
other_fares |
array ( Fare ) Other available fares in the same cabin. |
origin_airport
required |
string
Example: BOS IATA airport code of origin |
destination_airport
required |
string
Example: LGA IATA airport code of destination |
departure_date_time
required |
string
Example: 2024-04-02T18:34:30 The local date and time of departure in ISO Local Date Time format |
arrival_date_time
required |
string
Example: 2024-04-02T19:12:30 The local date and time of arrival in ISO Local Date Time format |
flight_number
required |
string
Example: JB776 The number of the flight |
validating_carrier_code
required |
string
Example: B6 The IATA airline code of the validating carrier for this segment |
fare_class
required |
string
Enum: "basic_economy" "economy" "premium_economy" "business" "first" Fare class of the segment |
fare_brand | string
Example: flex Name of the fare brand applied to the segment (if applicable) |
bullet_points
required |
Array (string)
An array containing the bullet points to be displayed |
labels
required |
object (map_string)
A map of key-value pairs for storing all labels to be displayed |
total_price
required |
string >= 0
Example: 20.55 Total price of ancillaries of this type |
passenger_reference | string
Unique reference of the passenger |
type
required |
string
Enum: "travel_insurance" "cabin_bag" "checked_bag" "seat" "lounge" "meal" "fast_track" "pet" "other" The type of ancillary |
covered | boolean
Is this ancillary covered by the product. By default true if not specified |
price | string >= 0
Example: 401.10 The price of the slice for all the passengers with this fare |
fare_brand | string
Example: flex Code of the fare brand applied to this fare |
fare_basis | string
Example: YBA123US Code of the fare basis applied to this fare |
fare_rules |
array ( FareRule ) The fare rules associated to the fare. |
modification_type
required |
string
Enum: "cancellation" "change" The type of modification in question in this fare rule |
modification_time
required |
string
Enum: "after_departure" "anytime" "before_departure" The time at which the modification is requested |
allowed
required |
boolean
Determines if that type of modification at this time is allowed |
fee | string >= 0
Example: 20.55 Amount to be paid as penalty fee to perform the modification |
percentage | string >= 0
Example: 10.00 Percentage of the fare to be paid as penalty to perform the modification |
refund_method | string
Enum: "cash" "ftc" Method of refund in question in this fare rule |