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 client libraries 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 flights as well as add 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 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: v1" \
  -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"
  }
}'

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 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.

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?