save_booking

POST/api/v0.1/save_booking{?v}

The response is the same as for check_flights with a few additional attributes. Booking is confirmed when save_booking returns a 200 http code.

save_booking requests and responses are slightly different according to the used payment method (Zooz or credits).

• for Zooz payment, you need to add parameter payment_gateway with value payu to the request body - "payment_gateway": "payu"

Please always send booked_at and affily in save_booking.

• affily is a unique affiliate id that is assigned to each partner and cannot be changed, it coresponds to the parameter partner on search. It will stay with you for the whole time you deal with Kiwi.com. If you do not have an affiliate ID yet, get one at Tequila.

• booked_at is the page where the booking was made, ussually same as affily .

Please note: There are occasionally cases where there are more bags sent to save_booking than is allowed.

The maximum number of bags that can be ordered is the number of prices in bags_price * (multiplied by) the number of passengers.

E.g.:

• bags_price = {} => no bag can be ordered

• bags_price = {1: 30}, length(passengers) = 2 => 2 bags may be ordered

• bags_price = {1: 30, 2: 60}, length(passengers) = 2 => 4 bags may be ordered

A number of bags has to equal the number of hold_bags in passengers dict.

Example:

"bags": 1

Has to equal the:

"passengers": [
    {
        "title": "Mr",
        "name": "test",
        "surname": "test",
        ...
        "hold_bags": {
            "00ed01af47020000af2500b4_0": {
                "1": 1
            },
            "01af22f5470200009cdfdb11_0": {
                "1": 1
            }
        }
    },{
        "title": "Mr",
        "name": "testing",
        "surname": "tester",
        ...
        "hold_bags": {
            "00ed01af47020000af2500b4_0": {
                "1": 0
            },
            "01af22f5470200009cdfdb11_0": {
                "1": 0
            }
        }
    }
]

Post method body parameters: ¶

lang (string) - language, used en as default. For this string use format ISO 639-1 in which en has to be lowercase.

health_declaration_checked (bool)

• Optional parameter

• You can confirm health declaration of customer on your page.

• Applicable for flights departing in less than 26 hours and specific airlines.

• Partner is responsible to know which airlines require health declaration.

bags (integer) - number of bags in the booking, even if bags_price states that the first (or even second) checked baggage is free, it is necessary to request it in both check_flights and save_booking

passengers (array[string]) - list of passengers with their details

• name (string) - first name (and middle name of a passenger), if you need to add middle name please send it in this parameter in format: “first_name|middle_name”

• surname (string) - last name, please send it in the following format: “last_name”

• contact details - have to be provided at least for one passenger from a whole booking. This passenger must be an adult.

  • email (string) - users always have to use the email address which is used for their deposit account, or else they are not able to use their credit funds for ancillaries in MMB.
  • phone (string)
    • users have to use their company or dummy number (not passenger’s) to make sure no communication can get to the end passenger from kiwi.com side.
    • phone number is validated as per following regexp: ^+[1-9][0-9]{7,14}$

• cardno (string)

  • it is an alphanumeric string with maximum length of twenty characters. E.g. D54169411x
  • number of a travel document (ID or passport), you can check if it is required in response from check_flights in parameter document_need
  • note that most countries require at least 6 months until the document expires (from the time of departure of last flight)

• birthday (int) - date in UTC (Unix time format)

• nationality - has to be in ISO 3166-1 alpha-2 format (nationality of the passenger, not the country where the travel document was issued)

• title - Mr and Ms only

• expiration (int) - Unix timestamp, expiration of travel document

• category - adult, child, infant

  • The correct category needs to be chosen according to the the parameter age_category_thresholds from the check_flights response.

• hold_bags

  • baggage for passenger specified over each flight (316953800 in the example is flight id)
  • 1 0/1 number of first hold bags for given passenger
  • 2 0/1 number of second hold bags for given passenger (1 needs to have value 1 before you try to order second baggage for passenger)
  • 3 0/1 number of third hold bags for given passenger (1 and 2 need to have value 1 before you try to order third baggage for passenger)
  • ID can be found in the check_flights response. Example: 3916461095415522_0. Each flight has its own hold_bags ID

locale (string) - optional parameter. Use en-US as default. For this string use two formats ISO 639-1 and ISO 3166-1. Use two lowercase characters (indicating language as in lang parameter), dash, and two uppercase characters (indicating country).

currency (string) - partner can choose their own currency and conversion is done by us (see conversion parameter in check_flights). The total is always in EUR.

booking_token (string) - the hash received in the search results. This hash contains all the data about flights needed to finish the booking. Booking token expires after 30 days.

billing_details - optional parameter for adding details to invoice - different billing details than the passenger details for the booking

"billing_details": {
    "company_name": "",
    "vat_number": "",
    "company_id": "",
    "name": "",
    "street_address": "",
    "postal_code": "",
    "country": "",
    "city": "",
}

price_change - if the customer accepts the price change, you neither call check_flights nor save_booking again. The parameter “total” changes and you can continue with your booking.

Payment with credits requires these additional params: ¶

user_id (string)

• in combination with secret_token allows access to your deposit

• if you are not sure about your unique value, please contact our Business Development Manager

• for sandbox bookings, you can use value "test"

secret_token (string)

• in combination with user_id allows access to your deposit

• if you are not sure about your unique value, please contact our Business Development Manager

• keep this value secret to protect money in your Kiwi.com deposit

• for sandbox bookings, you can use value "test"

immediate_confirmation (boolean)

• Use immediate_confirmation=false. Otherwise, it is automatically set True. Consequently, we deduct funds and book the flights. This parameter is always required.

custom_markup

• optional parameter

• can be used in save_booking body to enable custom markup in case of additional charges at the partner’s side

• it should be used only for partners connected via Zooz

• partner should inform their account manager about the usage of this parameter as the custom_markup is not paid automatically unless we know about it

• {"custom_markup": {"amount": x.y}}

• amount - amount that is charged, always in EUR regardless of booking currency

Success response contains the following important data: ¶

• transaction_id - when paying with credits, this is used in confirm_payment call

• payu_token - when paying via Zooz, this is used in confirm_payment call as paymentToken parameter

• payu_public_key - when paying via Zooz, this is used in payment tokenization as public key parameter

NOTE: You need to add to the request parameter payment_gateway with value payu in order to get payu_token and payu_public_key in the response.

Not relevant for deposit partners: To increase the accuracy of fraud check service, you can forward user’s IP address by adding the following parameter to the save_booking request:
"forwarded_data": {"ip_address":"123.123.123.123"}

ERRORS ¶

The booking processing can fail for various reasons, therefore there are also error codes. For example, if you try to book a flight which is about to depart shortly, you’ll get: {"status": "error", "msg": "can't order anymore"}

Other examples:

{‘status’: ‘error’, ‘msg’: “can’t order, young passengers”}

{‘status’: ‘failed’}

{“status”: “error”, “msg”: “Payment error”}

{‘status’: ‘error’, ‘msg’: ‘server error’}

Validation error:

{
    "status": "error",
    "msg": "invalid request data",
    "errors": {
        "general": "Can't book - less infants than adults"
    }
}

• ValidationError(‘Currency is blocked’)

• ValidationError(“Can’t book - less infants than adults”)

• ValidationError(‘Partner is not enabled for production’)

• ValidationError(‘Invalid booking_token’)

• ValidationError(‘Invalid ip address for affil_id’)

• ValidationError(‘Requested too many bags’)

confirm_payment

POST/api/v0.1/confirm_payment{?v}