ThreeDSecureSession

Card payments must be authenticated before authorisation of a payment. The ThreeDSecureSession API performs that authentication. To pay for bookings by card using a Card record, you need to use the result of a ThreeDSecureSession.

Using the ThreeDSecureSession endpoints directly is only for scenarios where an authentication challenge requires no action by the cardholder, for example, where their payments meet the criteria as a Secure Corporate Payment.

To determine if this is relevant to you, please read the Requirements section of our Paying with cards in corporate booking tools implementation guide.

Schema

card_id
string

The card ID used to initiate the 3DS session.

Example: "tcd_0000AWr2XsTRIF1Vp34gh5"
client_id
string

Used to initialise the UI component when status is challenge_required

Example: "tds_visa_5a9a7b0a574c"
id
string

The ID of the ThreeDSecureSession.

Example: "3ds_0000AWr2XsTRIF1Vp34gh5"
live_mode
boolean

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

Example: true
resource_id
string

The offer, order ID or booking ID that the 3DS session is for.

Example: "off_0000AKTurT99qsmGTujhis"
status
enum

The status of the 3DS session.

  • challenge_required - The 3DS session requires the UI Component to be initialised. This is the initial state when the payment requires a 3DS challenge.

  • ready_for_payment - The 3DS session is ready to be used on a payment object as part of a order creation/payment request. This is the initial state if the card or the supplier does not support 3DS.

  • failed - The 3DS session was not authenticated to proceed with the payment. Payment should not be attempted. Cardholder should try again, possibly with a different card. Additionally, this is the initial state if the cardholder details are invalid.

  • expired - The 3DS session has expired. A new session should be created if needed.

Possible values: "challenge_required", "ready_for_payment", "failed", or "expired"

Create a 3DS Session

Creates a 3DS session for a given card, with the resource (i.e. offer, hold order,...) and optional services (i.e. bags, seats) you wish to pay for.

Once created, the 3DS session will either be ready for payment or require a challenge.

For 3DS sessions using individual cards where the cardholder is present, the cardholder may need to complete a challenge provided by the card issuer. You will need to use the UI component to render the challenge.

To learn how to integrate 3DS into your checkout, please read our Paying with customer cards integration guide.

Body parameters

card_id
stringrequired

The card ID. This should be the card ID that's going to be submitted for payment.

Example: "tcd_00009hthhsUZ8W4LxQgkjb"
exception
enum

The name of the exception to opt out of authenticating the payment with the card issuer.

Possible values: "secure_corporate_payment"
resource_id
stringrequired

The resource that is going to be submitted for payment after a 3DS session status is ready for payment. This is used together with services to calculate the payment amount in the currency to be paid.

Example: "off_0000AKTurT99qsmGTujhis"
services
list

Endpoint

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

Request

curl -X POST --compressed "https://api.duffel.com/payments/three_d_secure_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": {
    "services": [
      {
        "quantity": 1,
        "id": "ser_00009UhD4ongolulWd9123"
      }
    ],
    "resource_id": "off_0000AKTurT99qsmGTujhis",
    "exception": "secure_corporate_payment",
    "card_id": "tcd_00009hthhsUZ8W4LxQgkjb"
  }
}'

Response

{
  "data": {
    "status": "ready_for_payment",
    "resource_id": "off_0000AKTurT99qsmGTujhis",
    "live_mode": true,
    "id": "3ds_0000AWr2XsTRIF1Vp34gh5",
    "client_id": "tds_visa_5a9a7b0a574c",
    "card_id": "tcd_0000AWr2XsTRIF1Vp34gh5"
  }
}