Duffel Links

What do you need to start?

Before you can get started with this guide, you'll need to:

To make it easy to build your Duffel integration, we offer a JavaScript client library in JavaScript, Python, Ruby, C#, Java, Custom element loaded with script tag, Custom element installed with npm and React Component.

In order to access Duffel Links, your Duffel organisation must be set up with a country that is supported by Duffel Payments.

Tip

If you want to see this in action, you can log in to the dashboard and start creating test links from the Duffel Links page.

Tip

We've put together a Postman Collection that contains all of the requests you'll need to follow along with this guide.

Overview

This guide will walk you through how to use Duffel Links to offer a Duffel-powered search and book user interface to your customers so they can find and book their ideal accommodation, flights as well as add flight ancillaries.

Creating Links

First, using our sessions endpoint, you will need to create a link for your user. At creation, you will need to specify the brand customisation you want to use and the URLs you would like us to direct your user to on completion. You will also have the option at this point to specify a checkout currency and a markup you would like to be applied to the flights.

Note

A new session should be created every time a user comes to book flights or accommodation with Duffel Links. Unused sessions will expire after 24 hours, rendering the link invalid, and once a link has been used by one user, it will not be useable for another.

Shell
curl -X POST --compressed "https://api.duffel.com/links/sessions" \
  -H "Accept-Encoding: gzip" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Duffel-Version: v2" \
  -H "Authorization: Bearer $YOUR_ACCESS_TOKEN" \
  -d '{
  "data": {
    "reference": "USER_1",
    "success_url": "https://www.starkindustries.com/success",
    "failure_url": "https://www.starkindustries.com/failure",
    "abandonment_url": "https://www.starkindustries.com/abandon",
    "logo_url":"https://assets.starkindustries.com/logos/logo.svg",
    "primary_color":"#000000",
    "traveller_currency": "USD",
    "markup_amount": "1.00",
    "markup_currency": "USD",
    "markup_rate": "0.01",
    "flights": {
      "enabled": "true"
    },
    "stays": {
      "enabled": "false"
    }
  }
}'

The link that is returned will take them to a Duffel-hosted search and book experience which is customised to match your brand. Your users should navigate to this address where they will be able to purchase their accommodation or flights as well as any ancillary products.

A screenshot of the search page on Duffel Links

Depending on the outcome of the session, the user will be directed to one of three urls specified at the time of link creation.

Success - Once an order has been successfully created, the user will be provided with details of the booking (itinerary and booking reference) and then prompted to return to the link provided as success_url in the link creation request. This will include order_id and reference query params where the order_id is the Duffel ID that corresponds to the order and reference is the reference value provided in the link creation request. For example: https://www.starkindustries.com/success/?order_id=ord_0000ASPa29O14a2RheVaZE&reference=USER_1
Abandonment - If the user decides to abandon the checkout process by pressing the ‘Return’ button, the user will be redirected to the abandonment_url provided in the link creation request.
Failure - If there is a failure that the Duffel Links session cannot mitigate, the user will be redirected to the failure_url provided in the link creation request.

A screenshot of the order confirmation page on Duffel Links

If completed successfully, your user will have been provided with a confirmation page containing all the information they need in order to fly. All the orders that are created will also be accessible to you in the dashboard and our APIs where you can see and manage all of your customers' orders.

Sending a Travel Booking Confirmation

The final step in a travel booking journey is the receipt of a travel booking confirmation. You need to send this travel booking confirmation. It gives the traveller all the information they need on the day of travel to board a plane or check-in to an accommodation.

You can detect a booking by listening for a Flights order.created or a Stays stays.booking.created webhook event. Alternatively, all bookings are also available via the agent dashboard and the API.

Learn more about Receiving Webhooks.

It is important you include all the key information for the traveller. More information can be found in our Duffel Flight booking confirmation and Duffel Stays booking confirmation guides.

Keep Learning

You're ready to start selling flights! You will now have an order you can retrieve and make changes to the order through the API or dashboard if needed.

Where to go from here?