Description

This endpoint can be used to place a reservation in carrier system. Reservation is a temporary block of a place on the ride that ensures seat availability at the moment of purchase (confirmation). Reservations hold for 10 minutes by default, and, if not confirmed, will be automatically cancelled.

In order to lock in the seats and prices upon sending the user to the checkout page, trigger a /reservations/create request for the specified trip and passenger details.

Reservations overview

Reservations is a helpful tool to ensure that the customer retains their booking and seat throughout the checkout process. Without reservations, it is possible that while the user is buying their ticket their bus or seat could be booked out, resulting in the user losing their trip.

It is important to note that even if you have implemented reservations, your integration will still work with carriers who do not support reservations yet. The flow will work as it normally does and the reservation will be simulated.

Understanding reservations flow

Once the user has selected a specific trip (and optionally seats) and proceeds to the checkout page, the next step is to call the /reservations/create endpoint, which reserves the seat and price to be guaranteed for a certain period of time.

When /reservations/create is initially called, it will return attributes that give more information on the reservation.

Next step

If the reservation is created successfully, users can proceed to the checkout page and the reservation can be confirmed using the /reservations/confirm endpoint. Learn more about it here.

If the reservation flow is aborted by the user, the reservation must be cancelled using the /reservation/cancel endpoint.

More Info

• Full API integration
  • Trip selection and reservation
• Key Concepts
  • Reservations
    • Reservations overview
    • Understanding reservations flow
    • Common pitfalls and errors to avoid
  • Ancillaries
    • Supported ancillaries
    • API workflow
  • Discount cards
    • Types of supported discounts
    • Parameters characterising discounts
    • API workflow
  • Currencies and locales
  • Virtual interlining
• Rail Requirements
  • Fare Classes & Selection
• Endpoints
  • POST /retailers/v4/reservations/create

Description

This endpoint can be used to confirm a reservation in carrier system. Reservation then is moved to processing state and status can be later retrieved via /reservations/{reservation_id} endpoint.

Workflow

Assuming the selected trip is available, the user can now finalise the booking by entering the relevant passenger and payment details in the following sequence:

• Capture payment in a held status
• Trigger the booking by using the /reservations/confirm endpoint
• Receive confirmation of the reservation via the API
• Execute full capturing of the payment
• Display the booking confirmation page

Displaying prices

The price displayed on the checkout page and used for the further booking flow must be the price returned by the /reservations/create endpoint.

Service fees added by the booking platform must be separately and transparently displayed to the user.

Collect only required customer information

Different carriers require varying information during the booking process in order to fulfil their services and where possible, the collection of passenger information should be minimised. In order to facilitate a dynamic checkout that gathers only necessary information from the customer, please make use of /marketing_carriers/{marketing_carrier_id}/booking/schema endpoint, which shows the mandatory and optional parameters per carrier.

Carrier terms and conditions

It is mandatory to display the terms and conditions of the respective carrier on the checkout page. You can find the terms and conditions of the carrier from the terms parameter in the /marketing_carriers/{marketing_carrier_id} endpoint.

Check reservation status

To continually check to see if the reservation is confirmed, you must use the /reservations/{reservation_id} endpoint.

Succesful bookings

The booking_id returned through this endpoint after a successful booking can be used for all further post-booking interaction with the Distribusion API.

Payments

Please note that no live payments flow between your and our systems at this point. Payments are reconciled during regular settlement processes. In the booking request, you must specify payment method: demand_note.

Aborting the checkout process

In case the user aborts the checkout process, please use the /reservations/cancel endpoint to unblock the reserved seats in the carrier’s system.

Next step

After the reservation is confirmed, the status of the reservation must be checked using the /reservations/{reservation_id} endpoint.

If the reservation is successfull, check the full booking details using the /bookings/{booking_id} endpoint. The ticket can be accessed from the /bookings/{booking_id}/tickets endpoint.

More Info

• Full API integration
  • Checkout and trip confirmation
• Key Concepts
  • Reservations
    • Reservations overview
    • Understanding reservations flow
    • Common pitfalls and errors to avoid
  • Currencies and locales
• Rail Requirements
  • Checkout
• Endpoints
  • PUT /retailers/v4/reservations/confirm

Description

This endpoint can be used to retrieve all details regarding a specific reservation.

How it works

The current status of a reservation can be checked using the /reservations/{reservation_id} endpoint.

In the response, the value state shows the current state of the reservation. Values can be:

• created: The default value, appears right after the reservation is created.
• processing: Shown after /reservations/confirm is initially called.
• confirmed: Shown once the reservation is confirmed with the carrier.
• cancelled: Shows after the user leaves the page and /reservations/cancelled is called.
• failed: Shown if something went wrong in the booking.

Processing deadline

In the response, the processing_deadline value will present the date and time that the retailer should request /reservations/{reservation_id} to see if a booking was successfully created. Hence if you stop listening to it before that time frame, a discrepancy can happen.

The reservation status must be continually checked every 10 seconds until one of the following occurs:

• The reservation is confirmed and you can proceed with the post-booking actions.
• The reservation times out, in which case it will be automatically tagged as failed.
• The reservation fails, in which case the user must be notified that their booking was unsuccessful.

Important

The typical processing deadline is 10 mins and it is essential to continue listening (calling /reservations/{reservation_id) until the deadline expires. If you stop listening before processing_deadline reaches 0 and then the booking is created, there will be a discrepancy in status of the booking between you and the carrier. If this occurs, you will still be charged and incur the transaction costs.

More Info

• Full API integration

  • Checkout and trip confirmation

• Key Concepts

  • Reservations
    • Reservations overview
    • Understanding reservations flow
    • Common pitfalls and errors to avoid

• Endpoints

  • GET /retailers/v4/reservations/{reservation_id}

Description

This endpoint can be used to cancel a previously placed reservation.

How it works

In case the user aborts the checkout process, please use the /reservations/cancel endpoint to unblock the reserved seats in the carrier’s system.

Next step

If needed in your flow, a new reservation can be created using the /reservations/create endpoint.

More Info

• Full API integration

  • Checkout and trip confirmation

• Key Concepts

  • Reservations
    • Reservations overview
    • Understanding reservations flow
    • Common pitfalls and errors to avoid

• Endpoints

  • PUT /retailers/v4/reservations/cancel