Payment Intents

A Payment Intent is used to collect and capture a payment from a customer to top-up your Balance and then pay for an Offer, Order, or Order Change Offer. You're able to include markup here.

amount
string

The amount of the Payment Intent that covers the cost of the flight being sold and any additional markup.

The card payment will be charged this amount.

Example: "300.10"
card_country_code
string
nullable

The ISO 3166-1 alpha-2 code of the country that issued the card used to confirm the Payment Intent.

It will be null until the Payment Intent is confirmed.

Example: "GB"
card_last_four_digits
string
nullable

The last four digits of the card used to confirm the Payment Intent.

It will be null until the Payment Intent is confirmed.

Example: "4242"
card_network
enum
nullable

The card network in which the Payment Intent was processed on.

It will be null until the Payment Intent is confirmed.

Possible values: "amex", "cartes_bancaires", "diners", "discover", "interac", "jcb", "mastercard", "unionpay", "visa", or "unknown"
client_token
string

This value is used when displaying the payment collection form to securely identify and transmit the values to Duffel.

Example: "eyJjbGllbnRfc2VjcmV0IjoicGlfMUl5YTBiQW5rMVRkeXJvRE1iWkJPN0ZSX3NlY3JldF9TbGFrYnJjYnFHZGZha2VrcjdCNE5jZWVyIiwicHVibGlzaGFibGVfa2V5IjoicGtfbGl2ZV81MUl0Q3YwQW5rMUdkeXJvRFlFU3M3RnBTUEdrNG9kbDhneDF3Y1RBNVEzaUcyWEFWVEhxdFlKSVhWMUxoSU5GQUtFMjA1dFdmRGVIcXhwUVdnYkIzTkVFbzAwMmdVY1hzR0YifQ=="
confirmed_at
datetime

The ISO 8601 datetime at which the Payment Intent was confirmed

Example: "2020-04-11T15:48:11.642Z"
created_at
datetime

The ISO 8601 datetime at which the Payment Intent was created

Example: "2020-04-11T15:48:11.642Z"
currency
string

The currency of the amount, as an ISO 4217 currency code.

The card payment will be charged in this currency.

If it's different to your Balance currency, it will be converted to your Balance currency before the Balance is topped up.

Example: "GBP"
fees_amount
string
nullable

The amount of the fees to process the Payment Intent.

It will be null until the Payment Intent is confirmed.

Example: "3.00"
fees_currency
string
nullable

The currency of the fees_amount, as an ISO 4217 currency code.

This currency will match your Balance currency.

It will be null until the Payment Intent is confirmed.

Example: "GBP"
id
string

Duffel's unique identifier for the Payment Intent

Example: "pit_00009hthhsUZ8W4LxQgkjo"
live_mode
boolean

Whether the Payment Intent was created in live mode. This field will be set to true if the Payment Intent was created in live mode, or false if it was created in test mode.

Example: true
net_amount
string
nullable

The amount of the Payment Intent that was added to the Balance.

It'll be amount (in the Balance currency) less the fees_amount.

It will be null until the Payment Intent is confirmed.

Example: "297.10"
net_currency
string
nullable

The currency of the net_amount, as an ISO 4217 currency code.

This currency will match your Balance currency.

It will be null until the Payment Intent is confirmed.

Example: "GBP"
refunds
list

The Refunds for this Payment Intent

status
enum
nullable

The status of this Payment Intent

Possible values: "requires_payment_method", "requires_confirmation", "requires_action", "processing", "requires_capture", "cancelled", or "succeeded"
updated_at
datetime

The ISO 8601 datetime at which the Payment Intent was updated

Example: "2020-04-11T15:48:11.642Z"

You should use this API to get the complete, up-to-date information about a Payment Intent.

URL parameters

id
string
required

Duffel's unique identifier for the Payment Intent

Example: "pit_00009hthhsUZ8W4LxQgkjo"

Endpoint

GET https://api.duffel.com/payments/payment_intents/{id}

Request

curl -X GET --compressed "https://api.duffel.com/payments/payment_intents/{id}" \
-H "Accept-Encoding: gzip" \
-H "Accept: application/json" \
-H "Duffel-Version: beta" \
-H "Authorization: Bearer <YOUR_ACCESS_TOKEN>"

Response

{
"data": {
"updated_at": "2020-04-11T15:48:11.642Z",
"status": "succeeded",
"refunds": [
{
"updated_at": "2020-04-11T15:48:11.642Z",
"status": "succeeded",
"payment_intent_id": "pit_00009hthhsUZ8W4LxQgkjo",
"net_currency": "GBP",
"net_amount": "300.10",
"live_mode": true,
"id": "ref_00009hthhsUZ8W4LxQgkjo",
"destination": "original_form_of_payment",
"currency": "GBP",
"created_at": "2020-04-11T15:48:11.642Z",
"arrival": "Credit approximately 5-10 business days later, depending upon the bank.",
"amount": "300.10"
}
],
"net_currency": "GBP",
"net_amount": "297.10",
"live_mode": true,
"id": "pit_00009hthhsUZ8W4LxQgkjo",
"fees_currency": "GBP",
"fees_amount": "3.00",
"currency": "GBP",
"created_at": "2020-04-11T15:48:11.642Z",
"confirmed_at": "2020-04-11T15:48:11.642Z",
"client_token": "eyJjbGllbnRfc2VjcmV0IjoicGlfMUl5YTBiQW5rMVRkeXJvRE1iWkJPN0ZSX3NlY3JldF9TbGFrYnJjYnFHZGZha2VrcjdCNE5jZWVyIiwicHVibGlzaGFibGVfa2V5IjoicGtfbGl2ZV81MUl0Q3YwQW5rMUdkeXJvRFlFU3M3RnBTUEdrNG9kbDhneDF3Y1RBNVEzaUcyWEFWVEhxdFlKSVhWMUxoSU5GQUtFMjA1dFdmRGVIcXhwUVdnYkIzTkVFbzAwMmdVY1hzR0YifQ==",
"card_network": "visa",
"card_last_four_digits": "4242",
"card_country_code": "GB",
"amount": "300.10"
}
}

Once you've successfully collected the customer's card details, using the client_token from when you first created the Payment Intent, you then need to confirm it using this endpoint.

Once confirmed, the amount charged to your customer's card will be added to your Balance (minus any Duffel Payment fees).

URL parameters

id
string
required

Duffel's unique identifier for the Payment Intent

Example: "pit_00009hthhsUZ8W4LxQgkjo"

Endpoint

POST https://api.duffel.com/payments/payment_intents/{id}/actions/confirm

Request

curl -X POST --compressed "https://api.duffel.com/payments/payment_intents/{id}/actions/confirm" \
-H "Accept-Encoding: gzip" \
-H "Accept: application/json" \
-H "Duffel-Version: beta" \
-H "Authorization: Bearer <YOUR_ACCESS_TOKEN>"

Response

{
"data": {
"updated_at": "2020-04-11T15:48:11.642Z",
"status": "succeeded",
"refunds": [
{
"updated_at": "2020-04-11T15:48:11.642Z",
"status": "succeeded",
"payment_intent_id": "pit_00009hthhsUZ8W4LxQgkjo",
"net_currency": "GBP",
"net_amount": "300.10",
"live_mode": true,
"id": "ref_00009hthhsUZ8W4LxQgkjo",
"destination": "original_form_of_payment",
"currency": "GBP",
"created_at": "2020-04-11T15:48:11.642Z",
"arrival": "Credit approximately 5-10 business days later, depending upon the bank.",
"amount": "300.10"
}
],
"net_currency": "GBP",
"net_amount": "297.10",
"live_mode": true,
"id": "pit_00009hthhsUZ8W4LxQgkjo",
"fees_currency": "GBP",
"fees_amount": "3.00",
"currency": "GBP",
"created_at": "2020-04-11T15:48:11.642Z",
"confirmed_at": "2020-04-11T15:48:11.642Z",
"client_token": "eyJjbGllbnRfc2VjcmV0IjoicGlfMUl5YTBiQW5rMVRkeXJvRE1iWkJPN0ZSX3NlY3JldF9TbGFrYnJjYnFHZGZha2VrcjdCNE5jZWVyIiwicHVibGlzaGFibGVfa2V5IjoicGtfbGl2ZV81MUl0Q3YwQW5rMUdkeXJvRFlFU3M3RnBTUEdrNG9kbDhneDF3Y1RBNVEzaUcyWEFWVEhxdFlKSVhWMUxoSU5GQUtFMjA1dFdmRGVIcXhwUVdnYkIzTkVFbzAwMmdVY1hzR0YifQ==",
"card_network": "visa",
"card_last_four_digits": "4242",
"card_country_code": "GB",
"amount": "300.10"
}
}

To begin the process of collecting a card payment from your customer, you need to create a Payment Intent.

The Payment Intent will contain a client_token that you use to collect the card payment in your application.

If the Payment Intent is created in test mode you should use a test card.

Body parameters

amount
string
required

This is the amount that the card payment being taken will be charged.

It should be enough to cover the service(s) you want to sell (enough to book an Offer for example) and the processing fees.

If the currency is different from your Balance currency you should also account for foreign exchange.

It can be higher than that, in which case the remainder will be considered your markup.

If it's higher than the maximum allowed for you organisation you will get a validation error. By default the maximum is 5,000.00 GBP (or equivalent in the same currency). If you need a maximum higher than the default please get in touch with us via help@duffel.com.

Example: "30.20"
currency
string
required

The currency of the amount, as an ISO 4217 currency code.

This is going to be the currency that the card payment being taken in will be charged in.

Example: "GBP"

Endpoint

POST https://api.duffel.com/payments/payment_intents

Request

curl -X POST --compressed "https://api.duffel.com/payments/payment_intents" \
-H "Accept-Encoding: gzip" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Duffel-Version: beta" \
-H "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
-d '{
"data": {
"currency": "GBP",
"amount": "30.20"
}
}'

Response

{
"data": {
"updated_at": "2020-04-11T15:48:11.642Z",
"status": "succeeded",
"refunds": [
{
"updated_at": "2020-04-11T15:48:11.642Z",
"status": "succeeded",
"payment_intent_id": "pit_00009hthhsUZ8W4LxQgkjo",
"net_currency": "GBP",
"net_amount": "300.10",
"live_mode": true,
"id": "ref_00009hthhsUZ8W4LxQgkjo",
"destination": "original_form_of_payment",
"currency": "GBP",
"created_at": "2020-04-11T15:48:11.642Z",
"arrival": "Credit approximately 5-10 business days later, depending upon the bank.",
"amount": "300.10"
}
],
"net_currency": "GBP",
"net_amount": "297.10",
"live_mode": true,
"id": "pit_00009hthhsUZ8W4LxQgkjo",
"fees_currency": "GBP",
"fees_amount": "3.00",
"currency": "GBP",
"created_at": "2020-04-11T15:48:11.642Z",
"confirmed_at": "2020-04-11T15:48:11.642Z",
"client_token": "eyJjbGllbnRfc2VjcmV0IjoicGlfMUl5YTBiQW5rMVRkeXJvRE1iWkJPN0ZSX3NlY3JldF9TbGFrYnJjYnFHZGZha2VrcjdCNE5jZWVyIiwicHVibGlzaGFibGVfa2V5IjoicGtfbGl2ZV81MUl0Q3YwQW5rMUdkeXJvRFlFU3M3RnBTUEdrNG9kbDhneDF3Y1RBNVEzaUcyWEFWVEhxdFlKSVhWMUxoSU5GQUtFMjA1dFdmRGVIcXhwUVdnYkIzTkVFbzAwMmdVY1hzR0YifQ==",
"card_network": "visa",
"card_last_four_digits": "4242",
"card_country_code": "GB",
"amount": "300.10"
}
}