Payments

Payments for the various types of orders.

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"

failure_reason

stringnullable

Present on payments with failed status. Indicates the reason for the failure.

Example: "ineligible_airline_credit"

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

order_id

string

Duffel's unique identifier for the resource

Example: "ord_00009hthhsUZ8W4LxQgkjo"

status

enum

The current status of payment. pending payments will transition to failed or succeeded.

Possible values: "succeeded", "failed", "pending", or "cancelled"

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. You can pay using your Duffel account's balance by specifying balance. In test mode, your balance is unlimited. Otherwise, you can pay by card. 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"

List payments

Retrieves a paginated list of payments

after

string

A cursor pointing to the previous page of records. For more information on how to paginate through records, see the Pagination section.

Example: "g2wAAAACbQAAABBBZXJvbWlzdC1LaGFya2l2bQAAAB="

before

string

A cursor pointing to the next page of records. For more information on how to paginate through records, see the Pagination section.

Example: "g2wAAAACbQAAABBBZXJvbWlzdC1LaGFya2l2bQAAAB="

limit

integer

The maximum number of records to return per page. Defaults to 50. May be set to any integer between 1 and 200. For more information on how to paginate through records, see the Pagination section.

Example: 1

Default value: 50

order_id

stringrequired

Filters the returned payments by a specific order's unique identifier.

Example: "ord_00009hthhsUZ8W4LxQgkjo"

Endpoint

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

Request


curl -X GET --compressed "https://api.duffel.com/air/payments?after=g2wAAAACbQAAABBBZXJvbWlzdC1LaGFya2l2bQAAAB=&before=g2wAAAACbQAAABBBZXJvbWlzdC1LaGFya2l2bQAAAB=&limit=1&order_id=ord_00009hthhsUZ8W4LxQgkjo" \
  -H "Accept-Encoding: gzip" \
  -H "Accept: application/json" \
  -H "Duffel-Version: v2" \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>"

{
  "meta": {
    "limit": 50,
    "after": "g2wAAAACbQAAABBBZXJvbWlzdC1LaGFya2l2bQAAAB="
  },
  "data": [
    {
      "type": "balance",
      "status": "failed",
      "order_id": "ord_00009hthhsUZ8W4LxQgkjo",
      "live_mode": false,
      "id": "pay_00009hthhsUZ8W4LxQgkjo",
      "failure_reason": "ineligible_airline_credit",
      "currency": "GBP",
      "created_at": "2020-04-11T15:48:11.642Z",
      "amount": "30.20"
    }
  ]
}

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

Field	Code	Description
`order_id`	`order_type_not_eligible_for_payment`	This order can't be paid for because it isn't a `hold` order.
`amount`	`payment_amount_does_not_match_order_amount`	The `amount` provided in the payment doesn't match the `total_amount` of the order.
`currency`	`payment_currency_does_not_match_order_currency`	The `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.

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: v2" \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
  -d '{
  "data": {
    "payment": {
      "type": "balance",
      "three_d_secure_session_id": "3ds_0000AWr2XsTRIF1Vp34gh5",
      "currency": "GBP",
      "amount": "30.20"
    },
    "order_id": "ord_00003x8pVDGcS8y2AWCoWv"
  }
}'

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

Get a single payment

Retrieves an payment by its ID.

stringrequired

Duffel's unique identifier for the resource

Example: "pay_00009hthhsUZ8W4LxQgkjo"

Endpoint

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

Request


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

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

Payments

Schema

List payments

Query parameters

Create a payment

Validation errors

Invalid states

Body parameters

Get a single payment

URL parameters