Book a Trip

Prerequisites
Authentication & Configuration
Plan a Trip
Get Quotes
Book a Trip
Track a Trip

We are almost there, the user has specified the pickup and dropoff locations, s/he selected the quote which s/he would like to proceed. Now the last step is to book the trip and wait for the driver to pick him/her up. At this stage, the user needs to checkout and pay for the trip using his/her credit card.

The KarhooApi.tripService provides functionality to book and cancel the trips.

Comercial model

In order to be able to book trips successfully, the correct commercial model needs to be agreed, so we can configure your account on our platform. The main objective of the commercial model is to determine who would be the main merchant of records to handle the commercial aspects of the booking.

The following section assumes Karhoo is the merchant of record and is responsible to arrange and collect the payments before making the booking.

Book

The KarhooApi.tripService.book requires a TripBooking which specifies the list of passengers and identifier for the quote which was selected in the previous step.

The TripBooking contains an optional attribute called paymentNonce which would represent a reference to the payment method that is used to charge the passenger's credit card.

If you decide that Karhoo handle the payments, then you need to initialise paymentNonce as demonstrated in the following example. You need to contact Karhoo for further instructions to configure Karhoo as merchant of record in order to handle the payments.

📘
We use the phone number and email address of the primary passenger to send trip notifications in the provided locale

let tripService = Karhoo.getTripService()

let quoteId = "1234" // you can get this ID from the quotes service.
let passengers = Passengers(
                additionalPassengers: 0,
                passengerDetails: [PassengerDetails(
                        firstName: "John",
                        lastName: "Smith",
                        phoneNumber: "+441234567890",
                        email: "[email protected]",
                        locale: "gb"
                )])

let tripBooking = TripBooking(paymentNonce = threeDSNonce,
  														quoteId: quoteId,
                              passengers: passengers,
                              flightNumber: nil)

tripService.book(tripBooking: tripBooking).execute { result in
    switch result {
    case .success(let trip):
        print("Trip: \(trip)")
    case .failure(let error):
        print("error: \(error.code) \(error.message)")
    }
}

val tripService = KarhooApi.tripService

val quoteId = "1234" // you can get this ID from the quotes service.
val passengers = Passengers(
                additionalPassengers = 0,
                passengerDetails = listOf(PassengerDetails(
                        firstName = "John",
                        lastName = "Smith",
                        phoneNumber = "+441234567890",
                        email = "[email protected]",
                        locale = "gb"
                )))
val flightNumber = "BOE747"

val tripBooking = TripBooking(
  			nonce = threeDSNonce,
        quoteId = quoteId,
        passengers = passengers,
        flightNumber = flightNumber))

tripsService.book(tripBooking)
        .execute { result ->
            when (result) {
                is Resource.Success -> print(result.data) //Handle data
                is Resource.Failure -> print(result.error) //Handle error
            }
        }

Cancel

The KarhooApi.tripService.cancel requires a TripCancellation which specifies the identifier for the trip.

The traveller might still be charged for cancellation fee depending on the cancellation policy of the booking.

let tripService = Karhoo.getTripService()
let tripCancellation = TripCancellation(tripId: trip.tripId, cancelReason: .notNeededAnymore)

tripService.cancel(tripCancellation: tripCancellation).execute { result in
    switch result {
    case .success:
        print("Trip cancelled")
    case .failure(let error):
        print("error: \(error.code) \(error.message)")
    }
}

val tripService = KarhooApi.tripService

val tripCancellation = TripCancellation(
                          tripIdentifier = trip.tripId,
                          reason = CancellationReason.OTHER_USER_REASON)

tripsService.cancel(tripCancellation).execute { result ->
    when (result) {
        is Resource.Success -> Log.d(result.data) //Handle data
        is Resource.Failure -> Log.d(result.error) //Handle error
    }
}

📘
If you configured the SDK to use Guest as AuthenticationMethod, you need to use TripInfo.followCode to build the TripCancellation.

let tripService = Karhoo.getTripService()
let tripCancellation = TripCancellation(tripId: trip.followCode, cancelReason: .notNeededAnymore)

tripService.cancel(tripCancellation: tripCancellation).execute { result in
    switch result {
    case .success:
        print("Trip cancelled")
    case .failure(let error):
        print("error: \(error.code) \(error.message)")
    }
}

val tripService = KarhooApi.tripService

val tripCancellation = TripCancellation(
                          tripIdentifier = trip.followCode.orEmpty(),
                          reason = CancellationReason.OTHER_USER_REASON)

tripsService.cancel(tripCancellation).execute { result ->
    when (result) {
        is Resource.Success -> Log.d(result.data) //Handle data
        is Resource.Failure -> Log.d(result.error) //Handle error
    }
}