BOOKING FLOW

📘
This flow is applicable across all verticals

Api Services

Section	Description
Pre-Book	Ensures that the fare obtained through the search is still valid for booking. Additionally, it provides a token with an expiration time, which is essential to proceed with the booking. This service is only available to active affiliates.
Payments	Quotes the result of the pre-book and presents available payment methods, amounts, and discounts. Users can interact with this service by specifying the points customers wish to redeem, generating a quote that incorporates these redemptions.
Book	Responsible for confirming and issuing the reservation.
Status	Provides updates about the status of the flight reservation.

ℹ️
Credit Card Payment
For partners who do not have their own payment gateway, Despegar provides access to a Koin-powered solution to enable credit card transactions.

Testing (Sandbox)

Sandbox credentials will be provided

Production

PCI certificate is required

Production credentials will be provided

Notes

This service must be requested when applying for API credentials and during account onboarding.

Koin URL: https://api-docs.koin.com.br/reference/tokenizecardpost

Flow

sequenceDiagram
    Actor Partner
    participant Prebook as /Prebook
    participant Payments as /Payments
    participant Book as /Book

    Partner->>Prebook: choice_id
    Prebook-->>Partner: prebook_id, expiration time

    Partner->>Payments: prebook_id
    Payments-->>Partner: plan_id

    Partner->>Book: prebook_id, plan_id, invoice info
    Book-->>Partner: 200 OK / estado de reserva

Book additional flows

Price Jump

This process takes place when a price change is detected during the booking flow. A price jump occurs when the fare available at the time of booking differs from the one quoted during the prebook step.

When the book request is processed, if a price jump is detected, the response returns a PROCESSING status instead of a confirmation. At that point, the GET /recovery endpoint must be called with the reservation_id to retrieve the details of the new price. Once the new price is obtained, there are two possible outcomes:

The new price is accepted via the PATCH endpoint; consequently, the booking is confirmed with the updated price.
The new price is rejected via the PATCH endpoint; therefore, the booking is not completed.

sequenceDiagram
    actor Partner
    participant Prebook as /Prebook
    participant Payments as /Payments
    participant Book as /Book
    participant Recovery as /Recovery 

    Partner->>Prebook: choice_id
    Prebook-->>Partner: prebook_id, expiration time

    Partner->>Payments: prebook_id
    Payments-->>Partner: plan_id

    Partner->>Book: prebook_id, plan_id, invoice info
    Book-->>Partner: status: PROCESSING / estado de reserva

    Partner -->> Recovery: reservation_id
    Recovery -->> Partner: info new price
    Partner -->> Recovery: accept o reject

Commission Update - Expected flow

This process takes place when the partner wants to apply a custom commission to a booking before confirming it. By default, the prebook response includes a default commission, but the partner can modify it before proceeding to payment.

The flow starts with the prebook step, which receives a choice_id and returns a prebook_id, an expiration time, and the default commission. If the partner wants to apply a different commission, they call the /update-commission endpoint with the prebook_id and the desired commission; this returns the updated price reflecting the new commission.

Once the commission is set, the flow continues as a standard book: the partner calls /payments with the prebook_id to obtain a plan_id, and finally calls /book with the prebook_id, plan_id, and invoice information to confirm the reservation.

sequenceDiagram
    actor Partner
    participant Prebook as /Prebook
    participant Commissions as /update-comission 
    participant Payments as /Payments
    participant Book as /Book

    Partner->>Prebook: choice_id
    Prebook-->>Partner: prebook_id, expiration time + commission default 

    Partner->>Commissions: prebook_id + commission desired
    Commissions-->>Partner: new price 

    Partner -->> Payments: prebook_id
    Payments -->> Partner: plan_id

    Partner->>Book: prebook_id, plan_id, invoice info
    Book-->>Partner: 200 OK / estado de reserva