Payments

Payments for the various types of orders.

Schema

amount
string

The price of the payment

Example: "30.20"
created_at
datetime

The ISO 8601 datetime at which the payment was created

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

The currency of the amount, as an ISO 4217 currency code. It will match your organisation's billing currency unless you’re using Duffel as an accredited IATA agent, in which case it will be in the currency provided by the airline (which will usually be based on the country where your IATA agency is registered).

Example: "GBP"
id
string

Duffel's unique identifier for the resource

Example: "pay_00009hthhsUZ8W4LxQgkjo"
live_mode
boolean

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

Example: false
type
enum

The type of payment applied to this order. If you are an IATA agent with your own agreements with airlines, in some cases, you can pay using ARC/BSP cash by specifying arc_bsp_cash. Otherwise, you must pay using your Duffel account's balance by specifying balance. In test mode, your balance is unlimited. If you're not sure which of these options applies to you, get in touch with the Duffel support team at help@duffel.com.

Possible values: "arc_bsp_cash", "balance", or "card"

Create a payment

Creates a payment for a hold order. A hold order can be paid for up to the time limit indicated in payment_required_by, after which the space held for the order will be released and you will have to create a new order.

Before paying, you should always get the latest price by retrieving the order to minimise the risk that the price you have is different from the latest price.

If the price for an order has changed from the time of booking and you pass in the old price, then you will get a validation error on the amount field with a price_changed code. The price of an order should only change if the order has no price guarantee or the price guarantee has expired (ie. price_guaranteed_expires_at is null or in the past).

If you receive a 500 Internal Server Error when trying to create a payment for a hold order, it may have still been created on the airline’s side. Please contact Duffel support before trying the request again.

Validation errors

FieldCodeDescription
order_idorder_type_not_eligible_for_paymentThis order can't be paid for because it isn't a hold order.
amountpayment_amount_does_not_match_order_amountThe amount provided in the payment doesn't match the total_amount of the order.
currencypayment_currency_does_not_match_order_currencyThe currency provided in the payment doesn't match the total_currency of the order.

Invalid states

This endpoint can return the following errors with a type of invalid_state, to indicate a reason that the order can't be paid for:

  • already_paid: The order you’re paying for has already been paid for.

  • already_cancelled: The order you’re attempting to pay for has been cancelled.

  • past_payment_required_by_date: The order’s payment_required_by date has elapsed.

  • schedule_changed: You can't pay for this order because it has been changed in some way on the airline's side. You should start again, creating a new order.

Body parameters

order_id
stringrequired

The id of the order you want to pay for.

Example: "ord_00003x8pVDGcS8y2AWCoWv"
payment
objectrequired

The payment details to use to pay for the order

Endpoint

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

Request

curl -X POST --compressed "https://api.duffel.com/air/payments" \
  -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": {
    "payment": {
      "type": "balance",
      "currency": "GBP",
      "amount": "30.20"
    },
    "order_id": "ord_00003x8pVDGcS8y2AWCoWv"
  }
}'

Response

{
  "data": {
    "type": "balance",
    "live_mode": false,
    "id": "pay_00009hthhsUZ8W4LxQgkjo",
    "currency": "GBP",
    "created_at": "2020-04-11T15:48:11.642Z",
    "amount": "30.20"
  }
}