Card

Once you've chosen which offer or quote you're ready to book, Card provides a way for you to use a customer's card to pay for travel. The travel suppliers will charge the customer's card directly for the booking.

To pay travel suppliers by card you first need to create a card, then authenticate the card transaction using a ThreeDSecureSession.

By default, cards remain in the vault for 25 minutes, after which they are deleted.

If you plan to reuse a card multiple times, you can create a multi-use card record by setting multi_use to true. The created record cannnot be used for payment, as it will not include a CVC. Instead, you can create additional card records for use for future payment, requiring only a CVC value to be supplied on checkout by providing cvc and card_id with the multi-use card id as values.

If you are paying with customer cards, please read our Paying with customer cards integration guide.

Only PCI-compliant customers can use the create API endpoint directly, for more information please read our Paying with cards in corporate booking tools

NOTE To ensure PCI-compliant card data handling, endpoints related to this resource use a different hostname: api.duffel.cards.

Schema

brand
enum

Card brand name. Card brands accepted for each transaction may vary per travel supplier.

Possible values: "visa", "mastercard", "uatp", "american_express", "diners_club", "jcb", or "discover"
id
string

Duffel's unique identifier for the resource

Example: "tcd_00009hthhsUZ8W4LxQgkjb"
last_4_digits
string

Last 4 digits of the card number.

Example: "1234"
live_mode
boolean

Whether the card 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
multi_use
boolean

A true value indicates that the card can be used for future transactions until the expiration or until deleted. A false value indicates that the card will be automatically deleted once used or until the time indicated by unavailable_at, whichever happens first.

Example: false
unavailable_at
datetime

The ISO 8601 datetime at which the card will be automatically deleted.

Example: "2023-04-13T15:48:11.642Z"

Delete a Card

Preview

This is not yet finalised. It may change, or be removed or be not yet accessible.

You can use this endpoint to Delete a Card record by its ID.

The endpoint works for all cards, but it's particularly useful for multi-use cards, as single use cards are automatically deleted after 25 minutes or after they are used, whichever comes first.

NOTE To ensure PCI-compliant card data handling, the URL for this API endpoint is different: https://api.duffel.cards.

URL parameters

id
stringrequired

Duffel's unique identifier for the resource

Example: "tcd_00009hthhsUZ8W4LxQgkjb"

Preview

This is not yet finalised. It may change, or be removed or be not yet accessible.

Endpoint

DELETE https://api.duffel.cards/payments/cards/{id}

Request

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

Response

Create a Card

Preview

This is not yet finalised. It may change, or be removed or be not yet accessible.

A card that can be used to pay for an offer or a quote you wish to book. Once created, the card can be used on other endpoints by supplying the card ID.

By default, cards are automatically deleted after 25 minutes or after they are used, whichever comes first.

If you wish to store a customers card for multiple future transactions, you can create a multi-use card record by setting multi_use to true. The created record cannnot be used for payment, as it will not include a CVC. To pay with a multi-use card, you must request the cardholder supply their CVC on each future checkout. In subsequent transactions, you then provide the CVC and card_id of the multi-use card.

NOTE To ensure PCI-compliant card data handling, the URL for this API endpoint is different: https://api.duffel.cards.

Body parameters

address_city
stringrequired

The city of the billing address associated with the card.

Example: "London"
address_country_code
stringrequired

The ISO 3166-1 alpha-2 code for the country of the billing address associated with the card.

Example: "GB"
address_line_1
stringrequired

The first line of the billing address associated with the card.

Example: "10 Downing St"
address_line_2
string

The second line of the billing address associated with the card.

Example: "Westminster"
address_postal_code
stringrequired

The postal code of the billing address associated with the card.

Example: "SW1A 2AA"
address_region
stringrequired

The region of the billing address associated with the card.

Example: "London"
card_id
string

Duffel's unique identifier for the multi-use card that should be used to create a single-use card record.

Example: "tcd_00009hthhsUZ8W4LxQgkjb"
cvc
stringrequired

The Card Verification Code (CVC). Value not accepted when creating multi-use cards.

Example: "123"
expiry_month
stringrequired

The card expiry month as an integer with two digits, e.g. for February use 02.

Example: "02"
expiry_year
stringrequired

The card expiry year as an integer with two digits, e.g. for 2023 use 23.

Example: "23"
multi_use
boolean

Set to true to indicate that this card can be used multiple times. Should not be provided when creating a card from a multi-use card record.

Example: false
name
stringrequired

The name on the card. The name must match the cardholder's name as it appears on the issued card. This information may be verified during payment authorisation, and any discrepancies could result in the payment being declined.

Example: "Neil Armstrong"
number
stringrequired

The card number.

Example: "4242424242424242"

Preview

This is not yet finalised. It may change, or be removed or be not yet accessible.

Endpoint

POST https://api.duffel.cards/payments/cards

Request

curl -X POST --compressed "https://api.duffel.cards/payments/cards" \
  -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": {
    "number": "4242424242424242",
    "name": "Neil Armstrong",
    "multi_use": false,
    "expiry_year": "23",
    "expiry_month": "02",
    "cvc": "123",
    "card_id": "tcd_00009hthhsUZ8W4LxQgkjb",
    "address_region": "London",
    "address_postal_code": "SW1A 2AA",
    "address_line_2": "Westminster",
    "address_line_1": "10 Downing St",
    "address_country_code": "GB",
    "address_city": "London"
  }
}'

Response

{
  "data": {
    "unavailable_at": "2023-04-13T15:48:11.642Z",
    "multi_use": false,
    "live_mode": true,
    "last_4_digits": "1234",
    "id": "tcd_00009hthhsUZ8W4LxQgkjb",
    "brand": "mastercard"
  }
}