7Buy a fare that cannot be held

POST/api/v1/flights/purchases

Reachable with a narrow key: flight_booking

For holdable: false fares: book and ticket in one call with the passengers, the bill_to, the price_token and the payment. Send the same bill_to and company you priced for. A purchase takes money at once, so it needs a customer: with no VKN, TCKN or passport to go on it answers 422 payer_required. A fare that moved since answers 409 price_changed with no figure: price again and send the new token with a new Idempotency-Key.

The token, the customer and the payment are checked at once, and a 4xx there means nothing was queued: refund the card. The purchase then answers through GET /api/v1/flights/operations/{id}, with the same rule for a 4xx there, except 409 idempotency_conflict (send it again with the same key) and 404 operation_not_found (send it again with the same key and body, which replays the first answer, or answers 502 booking_unresolved with the booking its key claimed once the call can no longer be read). 502 booking_unresolved keeps the key: read the booking back with the booking_id in the answer and refund only if it was not ticketed. With no booking_id, no booking was found under the key, so ask the agency before you refund. A repeat with the same key and body never buys twice: it answers the running purchase, then replays the first success or 502 booking_unresolved, and any other refusal frees the key. The same key with another offer or token is 422 idempotency_key_reuse. When the supplier books at another total than you charged, the answer carries amount_mismatch: true and the agency is told: settle the difference with your customer.

Parameters

Headers

Idempotency-Keystringrequired
Your own unique string for this purchase, max 255 characters.

Body

company_iduuid
The agency company that sells. Defaults to the account's default company.
search_idstringrequired
From the search answer.
offer_keystringrequired
The chosen offer's key.
passengersobject[]required
One entry per passenger, as many as the search asked for.
Show fieldsHide fields
- first_namestringrequired
  As on the passport.
- last_namestringrequired
  As on the passport.
- passenger_typeenumrequired
  ADT adult, CHD child, INF infant. The counts must match the search.
  one ofADTCHDINF
- date_of_birthdate
  Required for children and infants, and by some suppliers for every passenger.
- genderenum
  F or M, as on the passport.
  one ofFM
- passport_numberstring
  Written into the booking; never read back.
- passport_countrystring
  Issuing country (ISO 3166 alpha-2).
- passport_expirydate
  Must be valid beyond the travel dates; many countries ask for six months.
- national_idstring
  National identity number, where the route asks for one (e.g. Turkish domestic flights).
- nationalitystring
  ISO 3166 alpha-2.
- frequent_flyerstring
  Loyalty number, credited by the airline.
contactobject
Written into the booking so the airline can reach the traveller about a schedule change.
Show fieldsHide fields
- emailemail
  Where the airline sends schedule changes.
- phonestring
  Where the airline calls or texts about disruptions. International format.
bill_toobject
Who the booking bills, found by the ticket import's own rules. A company (corporate) is found by its VKN, then by its legal name, and opened when neither is on file. A person (individual) is found by TCKN (this one, else the first passenger's national_id), then by passport (this one, else the first passenger's), and opened from these fields or the first passenger. Never by email, phone or name. A cari that is found only has its blank fields filled; nothing on file is overwritten. Send customer_id instead when you hold it.
Show fieldsHide fields
- typeenum
  individual (a person) or corporate (a company). Defaults to individual; a 10-digit tax_number reads as corporate.
  one ofindividualcorporate
- legal_namestring
  The company's registered name. Corporate: required when tax_number is missing; finds the cari when the VKN does not.
- tax_numberstring
  VKN (10 digits) for a company, TCKN (11 digits) for a person. The first key the cari is found by.
- tax_officestring
  The company's tax office, for the invoice.
- passport_numberstring
  Individual: finds the cari when there is no TCKN.
- first_namestring
  Individual: the payer's first name, when it is not the first passenger.
- last_namestring
  Individual: the payer's last name.
- emailemail
  Written onto the cari for the invoice; never used to find one.
- phonestring
  International format; never used to find a cari.
- address_linestring
  Street and number, for the invoice.
- districtstring
  District (ilçe).
- citystring
  City (il).
- zipstring
  Postal code.
- countrystring
  ISO 3166 alpha-2.
customer_iduuid
Instead of bill_to, when you hold the agency's id for the payer.
remarksstring
A free-text note written into the booking.
price_tokenstringrequired
From price, for the same offer, bill-to and company. Valid 15 minutes.
paymentobjectrequired
The payment your website already took on its own POS. Recorded only if the ticket is issued.
Show fieldsHide fields
- amountstringrequired
  Must equal the booking total.
- currencystring
  Must equal the booking's currency.
- referencestringrequired
  Your POS transaction reference.
- installmentsinteger
  Number of installments taken on the card. Defaults to 1.
- paid_atdate-time
  When the card was charged. Defaults to now.
- merchant_account_iduuid
  Required when the agency has more than one POS.

Response · 201

iduuid
The booking id.
statusenum
held waits for payment, ticketing is paid and waiting for numbers, ticketed is done; cancelled, expired and failed are closed.
one ofpendingheldawaiting_approvalticketingticketedpartially_ticketedcancelledexpiredfailed
record_locatorstring
The airline booking reference (PNR).
ticketing_time_limitdate-time
While held: ticket before this, or the hold lapses.
sale_iduuid
The sale in the agency's books.
totalstring
The sell total of the booking.
currencystring
ISO 4217 code of total.
pendingboolean
Paid, ticket numbers not issued yet. The ticket webhook fires when they are.
ticketsobject[]
One per passenger once issued.
Show fieldsHide fields
- ticket_numberstring
  The e-ticket number.
- passenger_namestring
  As printed on the ticket (SURNAME/GIVEN).
booking_iduuid
The booking id.
payment_recordedboolean
False: the ticket stands, but the payment must be recorded by hand.
amount_mismatchboolean
True: the supplier booked at another total than the one you charged. The agency is told; settle the difference with your customer.
payerobject
The cari this booking bills. customer_id: the id you sent won. matched: a cari on file carried the identity (by says which); filled lists the blank fields your bill-to completed. created: a new cari was opened from your bill-to or the first passenger. none: no cari yet; warning says why (payer_unidentified: no VKN, TCKN or passport to go on). Send bill_to with the ticket call then.
Show fieldsHide fields
- outcomeenum
  How the cari was resolved.
  one ofcustomer_idmatchedcreatednone
- byenum
  On matched: the identity that found it.
  one oftax_numberlegal_namepassport
- customer_iduuid
  The cari's id; keep it and send it as customer_id next time.
- filledstring[]
  On matched: the blank fields your bill-to completed.
- warningenum
  Why there is no cari, or why your bill-to filled nothing.
  one ofpayer_unidentifiedpayer_fill_skipped

Responses

202The call is running. Read poll_url after Retry-After seconds until it answers anything but 202; after 3 minutes the call is lost and the poll says what to do.
401Missing or invalid Bearer token
403The key cannot reach the booking API: the account lacks an add-on (addon_required, with details.missing), the plan has no API access, or the key's scope is narrow.
409The booking cannot go ahead as asked. price_changed: price again and confirm the new total with your customer. approval_required: the agency approves the ticket first, then call ticket again. hold_expired: search again.
410The search or the offer has expired. Search again.
422The request was refused before anything was booked, or the supplier refused it (provider_rejected, with its reason in error).
502The supplier's answer is unknown: the booking may or may not exist, and money may already have moved. It is also what poll_url answers when a hold, a ticket, a release or a purchase did not finish in 3 minutes, and what a hold, a ticket or a purchase sent again with its Idempotency-Key answers once its call can no longer be read. Read the booking (GET /api/v1/flights/bookings/{booking_id}) before you retry or refund anything, and refund the card only if it was not ticketed. A hold, a ticket or a purchase keeps this answer under its Idempotency-Key, so a new attempt takes a new key; a release is sent again. With no booking_id, no booking was found under the key: hold again with a new key, and ask the agency before you refund a purchase.
503The supplier could not be reached, the call could not be queued, or a search, a price or the rules did not finish in 3 minutes (provider_unavailable). Nothing was booked: a search costs nothing, and a hold or a purchase is retried with the same Idempotency-Key.

curl -X POST 'https://YOUR-CELL.lydira.com/api/v1/flights/purchases' \
  -H 'Authorization: Bearer sek_YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 8f14e45f-ea2c-4f33-9a3b-6d0c1b7e5a90' \
  -d '{
  "company_id": "3f1c2b9a-6d4e-4c1a-9b2f-1a2b3c4d5e6f",
  "search_id": "eyJfcmFpbHMiOnsiZGF0YSI6eyJhY2NvdW50X2lkIjoi",
  "offer_key": "sbx_TK_1979_Y",
  "passengers": [
    {
      "first_name": "Deniz",
      "last_name": "Arslan",
      "passenger_type": "ADT",
      "date_of_birth": "1985-06-01",
      "gender": "F",
      "passport_number": "U7654321",
      "passport_country": "TR",
      "passport_expiry": "2031-01-01",
      "nationality": "TR"
    }
  ],
  "contact": {
    "email": "deniz@example.com",
    "phone": "+905551112233"
  },
  "bill_to": {
    "type": "individual",
    "tax_number": "10000000146",
    "email": "deniz@example.com"
  },
  "price_token": "eyJfcmFpbHMiOnsiZGF0YSI6eyJzZWxsX3RvdGFsIjoi",
  "payment": {
    "amount": "412.50",
    "currency": "EUR",
    "reference": "POS-884213",
    "installments": 1
  }
}'

const response = await fetch(
  "https://YOUR-CELL.lydira.com/api/v1/flights/purchases",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer sek_YOUR_API_KEY",
      "Content-Type": "application/json",
      "Idempotency-Key": "8f14e45f-ea2c-4f33-9a3b-6d0c1b7e5a90",
    },
    body: JSON.stringify({
      "company_id": "3f1c2b9a-6d4e-4c1a-9b2f-1a2b3c4d5e6f",
      "search_id": "eyJfcmFpbHMiOnsiZGF0YSI6eyJhY2NvdW50X2lkIjoi",
      "offer_key": "sbx_TK_1979_Y",
      "passengers": [
        {
          "first_name": "Deniz",
          "last_name": "Arslan",
          "passenger_type": "ADT",
          "date_of_birth": "1985-06-01",
          "gender": "F",
          "passport_number": "U7654321",
          "passport_country": "TR",
          "passport_expiry": "2031-01-01",
          "nationality": "TR"
        }
      ],
      "contact": {
        "email": "deniz@example.com",
        "phone": "+905551112233"
      },
      "bill_to": {
        "type": "individual",
        "tax_number": "10000000146",
        "email": "deniz@example.com"
      },
      "price_token": "eyJfcmFpbHMiOnsiZGF0YSI6eyJzZWxsX3RvdGFsIjoi",
      "payment": {
        "amount": "412.50",
        "currency": "EUR",
        "reference": "POS-884213",
        "installments": 1
      }
    }),
  },
);

if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
const data = await response.json();

import requests

response = requests.post(
    "https://YOUR-CELL.lydira.com/api/v1/flights/purchases",
    headers={
        "Authorization": "Bearer sek_YOUR_API_KEY",
        "Content-Type": "application/json",
        "Idempotency-Key": "8f14e45f-ea2c-4f33-9a3b-6d0c1b7e5a90",
    },
    json={
      "company_id": "3f1c2b9a-6d4e-4c1a-9b2f-1a2b3c4d5e6f",
      "search_id": "eyJfcmFpbHMiOnsiZGF0YSI6eyJhY2NvdW50X2lkIjoi",
      "offer_key": "sbx_TK_1979_Y",
      "passengers": [
        {
          "first_name": "Deniz",
          "last_name": "Arslan",
          "passenger_type": "ADT",
          "date_of_birth": "1985-06-01",
          "gender": "F",
          "passport_number": "U7654321",
          "passport_country": "TR",
          "passport_expiry": "2031-01-01",
          "nationality": "TR"
        }
      ],
      "contact": {
        "email": "deniz@example.com",
        "phone": "+905551112233"
      },
      "bill_to": {
        "type": "individual",
        "tax_number": "10000000146",
        "email": "deniz@example.com"
      },
      "price_token": "eyJfcmFpbHMiOnsiZGF0YSI6eyJzZWxsX3RvdGFsIjoi",
      "payment": {
        "amount": "412.50",
        "currency": "EUR",
        "reference": "POS-884213",
        "installments": 1
      }
    },
)
response.raise_for_status()
data = response.json()

require "net/http"
require "json"

uri = URI("https://YOUR-CELL.lydira.com/api/v1/flights/purchases")
request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer sek_YOUR_API_KEY"
request["Content-Type"] = "application/json"
request["Idempotency-Key"] = "8f14e45f-ea2c-4f33-9a3b-6d0c1b7e5a90"
request.body = JSON.generate({
  company_id: "3f1c2b9a-6d4e-4c1a-9b2f-1a2b3c4d5e6f",
  search_id: "eyJfcmFpbHMiOnsiZGF0YSI6eyJhY2NvdW50X2lkIjoi",
  offer_key: "sbx_TK_1979_Y",
  passengers: [
    {
      first_name: "Deniz",
      last_name: "Arslan",
      passenger_type: "ADT",
      date_of_birth: "1985-06-01",
      gender: "F",
      passport_number: "U7654321",
      passport_country: "TR",
      passport_expiry: "2031-01-01",
      nationality: "TR"
    }
  ],
  contact: {
    email: "deniz@example.com",
    phone: "+905551112233"
  },
  bill_to: {
    type: "individual",
    tax_number: "10000000146",
    email: "deniz@example.com"
  },
  price_token: "eyJfcmFpbHMiOnsiZGF0YSI6eyJzZWxsX3RvdGFsIjoi",
  payment: {
    amount: "412.50",
    currency: "EUR",
    reference: "POS-884213",
    installments: 1
  }
})

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { it.request(request) }
raise response.body unless response.is_a?(Net::HTTPSuccess)
data = JSON.parse(response.body)

<?php
$ch = curl_init("https://YOUR-CELL.lydira.com/api/v1/flights/purchases");
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST  => "POST",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        "Authorization: Bearer sek_YOUR_API_KEY",
        "Content-Type: application/json",
        "Idempotency-Key: 8f14e45f-ea2c-4f33-9a3b-6d0c1b7e5a90",
    ],
    CURLOPT_POSTFIELDS     => json_encode([
        "company_id" => "3f1c2b9a-6d4e-4c1a-9b2f-1a2b3c4d5e6f",
        "search_id" => "eyJfcmFpbHMiOnsiZGF0YSI6eyJhY2NvdW50X2lkIjoi",
        "offer_key" => "sbx_TK_1979_Y",
        "passengers" => [
            [
                "first_name" => "Deniz",
                "last_name" => "Arslan",
                "passenger_type" => "ADT",
                "date_of_birth" => "1985-06-01",
                "gender" => "F",
                "passport_number" => "U7654321",
                "passport_country" => "TR",
                "passport_expiry" => "2031-01-01",
                "nationality" => "TR",
            ],
        ],
        "contact" => [
            "email" => "deniz@example.com",
            "phone" => "+905551112233",
        ],
        "bill_to" => [
            "type" => "individual",
            "tax_number" => "10000000146",
            "email" => "deniz@example.com",
        ],
        "price_token" => "eyJfcmFpbHMiOnsiZGF0YSI6eyJzZWxsX3RvdGFsIjoi",
        "payment" => [
            "amount" => "412.50",
            "currency" => "EUR",
            "reference" => "POS-884213",
            "installments" => 1,
        ],
    ]),
]);

$data = json_decode(curl_exec($ch), true);
curl_close($ch);

Response

201

{
  "id": "2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f",
  "status": "ticketed",
  "record_locator": "ABC123",
  "ticketing_time_limit": "2026-10-08T18:00:00Z",
  "sale_id": "7e6d5c4b-3a2f-4e1d-8c0b-9a8f7e6d5c4b",
  "total": "412.50",
  "currency": "EUR",
  "pending": false,
  "tickets": [
    {
      "ticket_number": "235-1234567890",
      "passenger_name": "ARSLAN/DENIZ"
    }
  ],
  "booking_id": "2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f",
  "payment_recorded": true,
  "amount_mismatch": false,
  "payer": {
    "outcome": "matched",
    "by": "tax_number",
    "customer_id": "5b4a3c2d-1e0f-4a9b-8c7d-6e5f4a3b2c1d",
    "filled": [
      "tax_office",
      "address"
    ],
    "warning": "payer_unidentified"
  }
}