# Development quickstart

Learn how to search and book a flight with the CitizenPlane (opens new window) API.

Booking a flight only requires four simple steps. Because CitizenPlane processes credit cards but is not authorised to have credit card information, a payment method generated with the Stripe API (opens new window) will be required to process the booking. CitizenPlane (opens new window) only supports EUR as its currency.

The search-to-booking flow with the CitizenPlane (opens new window) API is as followed:

1. Search for Flights
2. Create a booking request
3. Gather credit card secured details
4. Process the booking
5. (Optional) Retrieve booking and flight information

# Step 1: Search flights

Each time a customer is performing a flight search, you can search CitizenPlane's flight content for flights matching your customer's request.

# Implementation

All the examples below use screenshots from Kiwi.com (opens new window) booking platform.

Because the above search is a roundtrip, it should be split into the two following requests to our API:

curl "https://booking-api.citizenplane.com/v2/flights?origin=CDG&destination=PMI&start=2023-08-06&end=2023-08-07&seats=2"
-H "Accept: application/json" \
-H "Authorization: Bearer {your_api_token}"

curl "https://booking-api.citizenplane.com/v2/flights?origin=PMI&destination=CDG&start=2023-08-13&end=2023-08-14&seats=2"
-H "Accept: application/json" \
-H "Authorization: Bearer {your_api_token}"

Go to the API reference

In case of a one-way search, only one request to our API is needed.

# Step 2: Create a booking request

Use the id returned in the flight object to create a booking request. You can specify up to three ids in the flights array parameter. It will simultaneously create as many requests as there are ids specified.

Creating a booking request guarantees your seats and the flight price for 3 minutes, thus saving you multiple checks to make sure the price hasn't changed or the seats haven't been taken.

# Implementation

Once the customer clicks on book it should generate the following API call

curl -X POST \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: {your_api_token}' \
-d '{
    "flights": [4014831,3795943],
    "customer_code": "kiwicom",
    "passengers": {
      "adults": 2,
      "children": 0,
      "infants": 0
    }
}' 'https://booking-api.citizenplane.com/v2/requests'

Go to the API reference

# Step 3: Gather credit card details

# For Self PSP integrations

# Generate a payment method

Once the customer has entered its payment information and prior to processing the booking, you'll need to send the credit card information to Stripe (opens new window) to generate a payment method we'll use to process the booking. Because of PCI compliance (opens new window) issues, CitizenPlane cannot directly processes credit card information. Therefore, you need to send us a payment_method generated with Stripe along with 3D secure information if needed.

# Implementation

Once the customer clicks on pay it should send the following request to the Stripe API

curl https://api.stripe.com/v1/payment_methods \
-u sk_test_wZGrX11MrIk123a9mpOoL9: \
-d card[number]=4242424242424242 \
-d card[exp_month]=12 \
-d card[exp_year]=2019 \
-d card[cvc]=123 \
-d type=card

Go to the API reference

# Step 4: Process the booking

The payment method returned by Stripe (opens new window) the payment id appended by pm that you need to add in your booking payload in order to allow CitizenPlane (opens new window) to process the payment.

# Regarding Self PSP setting

If your organization is authorized to use self_psp setting, you can omit the payment_method and three_d_secure fields and replace them by just self_psp: true.

# Regarding 3D Secure results

If needed, you can pass 3D Secure results directly at this stage to ensure you won't have failed bookings. 3D Secure results should be formatted as follow:

• three_d_secure.version REQUIRED

  The version of 3D Secure that was performed.

  # Possible enum values

  • 1.0.2
  • 2.1.0
  • 2.2.0

• three_d_secure.electronic_commerce_indicator REQUIRED

  The Electronic Commerce Indicator (ECI) is returned by your 3D Secure provider and indicates what degree of authentication was performed. (If your provider returns an ECI of 07 or 00, please discard it: authentication has failed. If desired, you may make an unauthenticated payment by leaving three_d_secure unset.)

  # Possible enum values

  • 05 Fully authenticated. The customer likely proved their identity to the issuing bank.
  • 06 Attempt acknowledged. The customer, or the entire issuing bank, is not set up for 3D Secure. Or the issuing bank is experiencing an outage. CitizenPlane wil return a payment error in that case.
  • 01 Attempt acknowledged (Mastercard variant). CitizenPlane wil return a payment error in that case.
  • 02 Fully authenticated (Mastercard variant).

• three_d_secure.cryptogram REQUIRED

  The cryptogram, also known as the “authentication value” (AAV, CAVV or AEVV). This value is 20 bytes, base64-encoded into a 28-character string. (Most 3D Secure providers will return the base64-encoded version, which is what you should specify here.)

• three_d_secure.transaction_id REQUIRED

  For 3D Secure 1, the XID. For 3D Secure 2, the Directory Server Transaction ID (dsTransID).

Each booking payload has to be linked with up to three requests with the requests array parameter containing the different ids. Because luggage options can vary between flights, they also have to be linked to their associated flight through the id of each request.

In addition to passenger(s) information, you also have to pass the customer's information either with a customer_code string or a custom customer_data object.

Though optional, it is highly recommended that you add a unique external_id in order to be able to trace back the booking in our system.

curl -X POST \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: {your_api_token}' \
-d '{
  "requests": [244401, 244402],
  "customer_code": "kiwicom",
  "external_id": "ABC123",
  "first_name": "John",
  "last_name": "Doe",
  "gender": "male",
  "email": "john.doe@example.com",
  "phonenumber": "+33600000000",
  "passengers": [
    {
        "first_name": "John",
        "last_name": "Doe",
        "gender": "male",
        "is_infant": false,
        "date_of_birth": "1987-06-21"
    },
    {
        "first_name": "Jane",
        "last_name": "Doe",
        "gender": "female",
        "is_infant": false,
        "date_of_birth": "1995-11-01"
    }
  ],
  "luggage": {
    "244402": [
      {
        "weight": 20,
        "quantity": 2,
        "price": 0
      }
    ],
  },
  "payment_method": "pm_1IxrDoCLoBt04Rh8deU0seLG",
  "three_d_secure": {
    "version": "2.2.0",
    "electronic_commerce_indicator": "05",
    "cryptogram": "4BQwsg4yuKt0S1LI1nDZTcO9vUM=",
    "transaction_id": "f879ea1c-aa2c-4441-806d-e30406466d79"
  }

  "self_psp": true // TO USE ONLY IF YOUR TEAM IS AUTHORIZED TO APPLY THIS SETTING

}' 'https://booking-api.citizenplane.com/v2/bookings'

Go to the API reference

# Step 5: Retrieve booking and flight information

# Implementation

If you wish to retrieve booking information and most importantly, the latest flight information attached to the booking, you can use the below endpoint. This endpoints allows you to check for potential schedule changes and automatically process them.

curl 'https://booking-api.citizenplane.com/v2/bookings?cp_reference=CPKVLF' \
-H 'Accept: application/json' \
-H 'Authorization: {your_api_token}'

Go to the API reference