Confirming Reservation
Once the reservation is created and is on hold (when supported by the carrier) the user has enough time to enter their personal details and complete the payment. Once this is completed, the reservation can be confirmed using the /reservations/confirm endpoint.
Required Fields for Confirming Reservation
The response from the /connections/vacancy and /reservations/create endpoints outline which passenger fields are required or optional for the /reservations/confirm request. This helps you adapt your booking form and validation to improve user experience, reduce errors, and meet carrier requirements. For more details check our Dynamic Passenger Fields guide.
Recommended Flow
After the selected trip is reserved, the user can finalize the booking by entering the relevant passenger and payment details in the following sequence:
- Capture payment in a held status (handled outside of Distribusion)
- Trigger the booking by using the /reservations/confirm endpoint
- Receive confirmation of the reservation via /reservations/{reservation_id} endpoint
- Execute full capturing of the payment (handled outside of Distribusion)
- Display the booking confirmation page
Best Practices
- Display correct 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.
- Display markups: Service fees or markups 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 fullfil their services and where possible, the collection of passenger information should be minimized. In order to facilitate a dynamic checkout that gathers only necessary information from the customer, please make use of the info from /connections/vacancy and /reservations/create endpoints and check our Dynamic Passenger Fields guide.
- Cancel reservation when checkout process is aborted: In case the user aborts the checkout or payment process, please use the /reservation/cancel endpoint to unblock the reserved seats in the carrier’s system. Do not just let the reservation timeout since other users won’t be able to see those seats until it does. The current status of a reservation can be checked using the /reservations/{reservation_id} endpoint.
- Display 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
termsparameter in the /marketing_carriers/{marketing_carrier_id} endpoint. Note that some carriers might have multiple links or long text in this field. - Process your payments: No live payments flow between your and our systems at this point. Payments are reconciled during regular settlement processes. In the /reservations/confirm request, you must specify
payment_method = demand_noteby default. - Do not call confirm & cancel in same booking flow: You should never call /reservations/confirm & /reservation/cancel in the same flow. Once confirmed we are attempting to create the booking, calling both will respond in an error. In this case, /reservations/create will need to be called to cancel booking after confirmation.
- Do not confirm reservation multiple times: Calling /reservations/confirm multiple times does not change the timing or affect the finality reservation. Instead, it is much more efficient to simply call the /reservations/{reservation_id} endpoint to check on the status of the reservation.
- Define sender of confirmation email: At the time of confirming the reservation you can specify if the user should receive the default confirmation and cancellation emails created by Distribusion or emails created by you. For more details check our Ticket Delivery guide.
Enterprise Features
After ancillaries are added to the /reservations/create step they don't have to be added again to the /reservations/confirm request. For more details, check our guide on Ancillaries.
When discount cards are applied to the /reservations/create step they don't have to be added again to the /reservations/confirm request. For more details, check our guide on Discount Cards.
Next Step
After the reservation is confirmed, the status of the reservation must be checked.
API Examples
Sample Request to /reservations/confirm
JSON
{
"reservation_id": "R7L9P7HT",
"execute_payment": false,
"payment_method": "demand_note",
"terms_accepted": true,
"send_customer_email": true,
"title": "mr",
"first_name": "John",
"last_name": "Smith",
"email": "test@distribusion.com",
"phone": "+4915222088994",
"city": "Berlin",
"zip_code": "13355",
"street_and_number": "Wattstrasse 10",
"passengers": [
{
"type": "PNOS",
"first_name": "John",
"last_name": "Smith"
},
{
"type": "PCIL",
"first_name": "Ana",
"last_name": "Smith"
}
]
}Sample Response from /reservations/confirm
JSON
{
"data": {
"id": "R7L9P7HT",
"type": "reservations",
"attributes": {
"total_price": 5000,
"original_price": 5000,
"state": "processing",
"created_at": "2024-08-23T17:20",
"confirmed_at": null,
"cancelled_at": null,
"failed_at": null,
"processing_started_at": "2024-08-23T17:20",
"processing_deadline": "2024-08-23T17:30",
"expires_at": "2024-08-24T17:20",
"terms_version": null,
"title": null,
"first_name": null,
"last_name": null,
"email": null,
"phone": null,
"city": null,
"zip_code": null,
"country_code": null,
"street_and_number": null,
"gender": null,
"country_of_birth": null,
"government_id_type": null,
"marketing_carrier_reservation_ids": [
"R7L9P7HT"
],
"agent_id": null,
"retailer_booking_number": null
},
"relationships": {
"booking": {
"data": null
},
"errors": {
"data": []
},
"reservation_passengers": {
"data": [
{
"id": "R-PNOS-1-ITAL-ITMILMAN-ITRRONGB-2024-08-29T10:15-2024-08-29T14:53",
"type": "reservation_passengers"
},
{
"id": "R-PCIL-2-ITAL-ITMILMAN-ITRRONGB-2024-08-29T10:15-2024-08-29T14:53",
"type": "reservation_passengers"
}
]
},
"applied_cards": {
"data": []
},
"ancillaries": {
"data": []
}
}
},
"jsonapi": {
"version": "1.0"
},
"meta": {
"locale": "en",
"currency": "EUR"
},
"included": [
{
"id": "R-PNOS-1-ITAL-ITMILMAN-ITRRONGB-2024-08-29T10:15-2024-08-29T14:53",
"type": "reservation_passengers",
"attributes": {
"first_name": null,
"last_name": null,
"serial_code": null,
"government_id_type": null,
"nationality": null,
"gender": null,
"country_of_birth": null,
"birthdate": null,
"type": "PNOS"
},
"relationships": {
"ancillaries": {
"data": []
}
}
},
{
"id": "R-PCIL-2-ITAL-ITMILMAN-ITRRONGB-2024-08-29T10:15-2024-08-29T14:53",
"type": "reservation_passengers",
"attributes": {
"first_name": null,
"last_name": null,
"serial_code": null,
"government_id_type": null,
"nationality": null,
"gender": null,
"country_of_birth": null,
"birthdate": null,
"type": "PCIL"
},
"relationships": {
"ancillaries": {
"data": []
}
}
}
]
}For more samples responses, check the /reservations/confirm endpoint page.
Was this section helpful?
What made this section unhelpful for you?
On this page
- Confirming Reservation