3D Secure

Enterprise

3D Secure is an Enterprise feature. Contact support@basistheory.com to request access.

Create a 3DS Session

POST

https://api.basistheory.com/3ds/sessions

Permissions

3ds:session:create

Request

cURL

curl "https://api.basistheory.com/3ds/sessions/" \
  -H "BT-API-KEY: <API_KEY>" \
  -H "Content-Type: application/json" \
  -X "POST" \
  -d '{
    "token_id": "af9f65fd-932f-4b3d-960a-1bd7a1d14d18",
    "type": "merchant"
  }'

Node

await client.threeds.sessions.create({
  tokenId: "af9f65fd-932f-4b3d-960a-1bd7a1d14d18",
  type: "merchant"
});

C#

await client.Threeds.Sessions.CreateAsync(new CreateThreeDsSessionRequest
{
  TokenId = "af9f65fd-932f-4b3d-960a-1bd7a1d14d18",
  Type = "merchant"
});

Python

client.threeds.sessions.create(
    token_id="af9f65fd-932f-4b3d-960a-1bd7a1d14d18",
    type="merchant"
)

Go

createRequest := &threeds.CreateThreeDsSessionRequest{
  TokenId: "af9f65fd-932f-4b3d-960a-1bd7a1d14d18",
  Type:    "merchant",
}

createResponse, createErr := client.Threeds.Sessions.Create(context.Background(), createRequest)

Request Parameters

Attribute	Required	Type	Description
token_id	conditional	string	A card type token id. Required if token_intent_id not present.
token_intent_id	conditional	string	A card type token intent id. Required if token_id not present.
pan	false	string	DEPRECATED A card type token id.
type	false	string	The 3DS session type between customer (CIT) and merchant (MIT). Defaults to customer.
device	conditional	string	The device type for the 3DS session between browser (web) or app (mobile). Required if type is customer.
device_info	conditional	object	Information about the device. See Device Info for details. Required if type is customer.

3DS sessions of type customer (CIT) are only officially supported through our frontend web, react-native and mobile SDKs. Using the API directly is not recommended and may lead to lower success rates. Basis Theory only supports creation of type merchant (MIT) through the API or backend SDKs.

Device Info Object

Attribute	Required	Type	Description
browser_javascript_enabled	conditional	bool	Indicates if JavaScript is enabled in the browser. Required if session device is browser and type is customer.
browser_java_enabled	conditional	bool	Indicates if Java is enabled in the browser. Required if session device is browser and type is customer.
browser_language	conditional	string	The language set in the browser. Required if session device is browser and type is customer.
browser_color_depth	conditional	string	The color depth of the browser. Required if session device is browser and type is customer.
browser_screen_height	conditional	string	The screen height of the browser. Required if session device is browser and type is customer.
browser_screen_width	conditional	string	The screen width of the browser.Required if session device is browser and type is customer.
browser_tz	conditional	string	The timezone of the browser. Required if session device is browser and type is customer.
browser_user_agent	conditional	string	The user agent string of the browser. Required if session device is browser and type is customer.
browser_accept_header	false	string	The HTTP Accept header value from the browser.
browser_ip	false	string	The IP address of the browser.
sdk_transaction_id	conditional	string	The ID of the SDK transaction. Required if session device is app and type is customer.
sdk_application_id	conditional	string	The ID for the application using the SDK. Required if session device is app and type is customer.
sdk_encryption_data	conditional	string	The encryption data used by the SDK. Required if session device is app and type is customer.
sdk_ephemeral_public_key	conditional	string	The ephemeral public key used by the SDK. Required if session device is app and type is customer.
sdk_max_timeout	conditional	string	The maximum timeout for the SDK. Required if session device is app and type is customer.
sdk_reference_number	conditional	string	The reference number used by the SDK. Required if session device is app and type is customer.
sdk_render_options	conditional	object	The render options used by the SDK. See SDK Render Options Required if session device is app and type is customer.

SDK Render Options

Attribute	Required	Type	Description
sdk_interface	conditional	string	The interface types the mobile device supports.. Required if session device is app and type is customer.
sdk_ui_type	conditional	array	The UI types the device supports for displaying challenge UIs. Required if session device is app and type is customer.

Response

Returns relevant information about the created 3DS session in a Create Session Response object. Returns an error if the session cannot be retrieved.

{
  "id": "c0c22fcd-d42c-497e-a9a6-2eacd31770d7",
  "type": "customer",
  "cardBrand": "Visa",
  "method_url": "https://acs.example.com/3ds/acs/browser/method",
  "method_notification_url": "https://api.basistheory.com/3ds/sessions/c0c22fcd-d42c-497e-a9a6-2eacd31770d7/method-notification",
  "directory_server_id": "M000000003",
  "recommended_version": "2.2.0"
}

Create Session Response Object

Attribute	Type	Description
id	string	The ID of the 3DS session.
type	string	The 3DS session type.
card_brand	string	The brand for the card used in the 3DS transaction.
method_url	string	The URL for the Method request, used by the 3DS SDK.
method_notification_url	string	The URL for which to send the method completion notification, used by the 3DS Web SDK.
directory_server_id	string	The 3DS directory server ID, used by the 3DS Mobile SDKs.
recommended_version	string	The 3DS version that was used for the transaction.

Get a Session

Get a 3DS Session by ID in the Tenant.

GET

https://api.basistheory.com/3ds/sessions/{id}

Permissions

3ds:session:read

Request

cURL

curl "https://api.basistheory.com/3ds/sessions/c0c22fcd-d42c-497e-a9a6-2eacd31770d7" \
  -H "BT-API-KEY: <API_KEY>"

Node

await client.threeds.sessions.get("c0c22fcd-d42c-497e-a9a6-2eacd31770d7");

C#

await client.Threeds.Sessions.GetAsync("c0c22fcd-d42c-497e-a9a6-2eacd31770d7");

Python

client.threeds.sessions.get("c0c22fcd-d42c-497e-a9a6-2eacd31770d7")

Go

getResponse, getErr := client.Threeds.Sessions.Get(context.Background(), sessionId)

URI Parameters

Parameter	Required	Type	Default	Description
id	true	string	null	The ID of the 3DS session.

Response

Returns a 3DS session with the id provided. Returns an error if the session cannot be retrieved.

{
  "id": "c0c22fcd-d42c-497e-a9a6-2eacd31770d7",
  "type": "customer",
  "tenant_id": "2fd20ec9-1255-4286-a0bc-bbb9b70f747f",
  "pan_token_id": "f9e45271-b3de-4729-8c1a-9cdd42417fc5",
  "token_id": "f9e45271-b3de-4729-8c1a-9cdd42417fc5",
  "card_brand": "Visa",
  "created_date": "2025-03-28T11:26:42.3528855+00:00",
  "created_by": "aea3512e-c9fb-4304-b6a8-7e53f8a33075",
  "modified_date": "2025-03-28T11:26:59.3003079+00:00",
  "modified_by": "8fc7beed-ac06-4529-a19f-bde6de591227",
  "device": "browser",
  "device_info": {
    "browser_accept_header": "*/*",
    "browser_javascript_enabled": true,
    "browser_java_enabled": false,
    "browser_language": "en-US",
    "browser_color_depth": "24",
    "browser_screen_height": "1440",
    "browser_screen_width": "2560",
    "browser_tz": "180",
    "browser_user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/134.0.0.0 Safari/537.36"
  },
  "version": {
    "recommended_version": "2.2.0",
    "available_versions": [
      "2.1.0",
      "2.2.0"
    ],
    "earliest_acs_supported_version": "2.1.0",
    "earliest_ds_supported_version": "2.1.0",
    "latest_acs_supported_version": "2.2.0",
    "latest_ds_supported_version": "2.2.0",
    "acs_information": [
      "threeds-auth-available",
      "threeds-attempts-supported",
      "threeds-whitelisting-supported"
    ],
  },
  "method": {
    "method_url": "https://acs.example.com/3ds/acs/browser/method",
    "method_completion_indicator": "Y"
  },
  "authentication": {
    "pan_token_id": "f9e45271-b3de-4729-8c1a-9cdd42417fc5",
    "token_id": "f9e45271-b3de-4729-8c1a-9cdd42417fc5",
    "session_id": "c0c22fcd-d42c-497e-a9a6-2eacd31770d7",
    "threeds_version": "2.2.0",
    "acs_transaction_id": "ec2a5868-ce1b-44c7-9249-bc5b0aa409a3",
    "ds_transaction_id": "22aeb643-1489-46ee-83aa-af1a01b457c9",
    "acs_reference_number": "mock-acs-reference-number",
    "ds_reference_number": "mock-directory-server-a",
    "liability_shifted": false,
    "authentication_value": "LVJhdmVsaW4gVGVzdCBWYWx1ZS0=",
    "authentication_status": "successful",
    "authentication_status_code": "Y",
    "directory_status_code": "C",
    "eci": "05",
    "acs_challenge_mandated": "N",
    "authentication_challenge_type": "static",
    "acs_challenge_url": "https://acs.example.com/3ds/acs/browser/creq",
    "challenge_attempts": "01",
    "message_extensions": []
  }
}

Authenticate Session

Authenticate a 3DS Session.

POST

https://api.basistheory.com/3ds/sessions/{id}/authenticate

Permissions

3ds:session:authenticate

Request

cURL

curl "https://api.basistheory.com/3ds/sessions/c0c22fcd-d42c-497e-a9a6-2eacd31770d7/authenticate" \
  -H "BT-API-KEY: <API_KEY>" \
  -H "Content-Type: application/json" \
  -X "POST" \
  -d '{
    "authentication_category": "payment",
    "authentication_type": "payment-transaction",
    "challenge_preference": "no-challenge",
    "merchant_info": {
      "mid": "9876543210001",
      "acquirer_bin": "000000999",
      "name": "Example 3DS Merchant",
      "category_code": "7922",
      "country_code": "826",
      "url": "https://example.com"
    },
    "requestor_info": {
      "amex_requestor_type": "MER",
      "cb_siret_number": "78467169500087"
    },
    "purchase_info": {
      "amount": "80000",
      "currency": "826",
      "exponent": "2",
      "date": "20240109141010",
      "transaction_type": "purchase"
    },
    "cardholder_info": {
      "name": "John Doe",
      "email": "john@example.com"
    }
  }'

Node

await client.threeds.sessions.authenticate(sessionId, {
  authenticationCategory: "payment",
  authenticationType: "payment-transaction",
  challengePreference: "no-challenge",
  merchantInfo: {
    mid: "9876543210001",
    acquirerBin: "000000999",
    name: "Example 3DS Merchant",
    categoryCode: "7922",
    countryCode: "826",
    url: "https://example.com",
  },
  requestorInfo: {
    amexRequestorType: "MER",
    cbSiretNumber: "78467169500087",
  },
  purchaseInfo: {
    amount: "80000",
    currency: "826",
    exponent: "2",
    date: "20240109141010",
    transactionType: "purchase",
  },
  cardholderInfo: {
    name: "John Doe",
    email: "john@example.com"
  }
});

C#

await client.Threeds.Sessions.AuthenticateAsync(sessionId.ToString(), new AuthenticateThreeDsSessionRequest
{
  AuthenticationCategory = "payment",
  AuthenticationType = "payment-transaction",
  ChallengePreference = "no-challenge",
  MerchantInfo = new ThreeDsMerchantInfo
  {
    Mid = "9876543210001",
    AcquirerBin = "000000999",
    Name = "Example 3DS Merchant",
    CategoryCode = "7922",
    CountryCode = "826",
    Url = "https://example.com"
  },
  RequestorInfo = new ThreeDsRequestorInfo
  {
    AmexRequestorType = "MER",
    CbSiretNumber = "78467169500087"
  },
  PurchaseInfo = new ThreeDsPurchaseInfo
  {
    Amount = "80000",
    Currency = "826",
    Exponent = "2",
    Date = "20240109141010",
    TransactionType = "purchase",
  },
  CardholderInfo = new ThreeDsCardholderInfo
  {
    Name = "John Doe",
    Email = "john@example.com"
  }
});

Python

client.threeds.sessions.authenticate(
    session_id=sessionId,
    authentication_category="payment",
    authentication_type="payment-transaction",
    challenge_preference="no-challenge",
    merchant_info=ThreeDsMerchantInfo(
        mid="9876543210001",
        acquirer_bin="000000999",
        name="Example 3DS Merchant",
        category_code="7922",
        country_code="826",
        url="https://example.com"
    ),
    requestor_info=ThreeDsRequestorInfo(
        amex_requestor_type="MER",
        cb_siret_number="78467169500087"
    ),
    purchase_info=ThreeDsPurchaseInfo(
        amount="80000",
        currency="826",
        exponent="2",
        date="20240109141010",
        transaction_type="purchase",
    ),
    cardholder_info=ThreeDsCardholderInfo(
        name="John Doe",
        email="john@example.com"
    )
)

Go

authRequest := &threeds.AuthenticateThreeDsSessionRequest{
    AuthenticationCategory: "payment",
    AuthenticationType:     "payment-transaction",
    ChallengePreference:    "no-challenge",
  }

merchantInfo := &basistheory.ThreeDsMerchantInfo{
  Mid:          pointerToString("9876543210001"),
  AcquirerBin:  pointerToString("000000999"),
  Name:         pointerToString("Example 3DS Merchant"),
  CategoryCode: pointerToString("7922"),
  CountryCode:  pointerToString("826"),
  Url:          pointerToString("https://example.com"),
}

requestorInfo := &basistheory.ThreeDsRequestorInfo{
  AmexRequestorType: pointerToString("MER"),
  CbSiretNumber:     pointerToString("78467169500087"),
}

purchaseInfo := &basistheory.ThreeDsPurchaseInfo{
  Amount:   pointerToString("80000"),
  Currency: pointerToString("826"),
  Exponent: pointerToString("2"),
  Date:     pointerToString("20240109141010"),
  TransactionType: pointerToString("purchase"),
}

cardholderInfo := &basistheory.ThreeDsCardholderInfo{
  Name:  pointerToString("John Doe"),
  Email: pointerToString("john@example.com"),
}

authRequest.MerchantInfo = merchantInfo
authRequest.RequestorInfo = requestorInfo
authRequest.PurchaseInfo = purchaseInfo
authRequest.CardholderInfo = cardholderInfo

authenticateResponse, authenticateErr := client.Threeds.Sessions.Authenticate(context.Background(), sessionId, authRequest)

Request Parameters

Attribute	Required	Type	Description
authentication_category	true	string	The category of the 3DS authentication, see Authentication Categories for allowed values.
authentication_type	true	string	The type of 3DS transaction, see Authentication Types for allowed values.
request_decoupled_challenge	false	bool	If a decoupled challenge is required in case of a challenge. Defaults to true for merchant session type.
decoupled_challenge_max_time	conditional	number	The maximum time in minutes for the decoupled challenge. Required if request_decoupled_challenge is true or session type is merchant.
challenge_preference	false	string	The merchant 3DS challenge preference, see Challenge Preferences for allowed values.
merchant_info	conditional	Merchant Info	Information about the merchant. Required if authentication_category is payment.
requestor_info	conditional	Requestor Info	Additional nformation about the 3DS requestor for certain card brands. Required only if authenticating American Express, Discover or Cartes Bancaires transactions.
purchase_info	conditional	Purchase Info	Information about the purchase (If any). Required if authentication_category is payment or if authentication_type is recurring-transaction or installment-transaction.
cardholder_info	true	Cardholder Info	Information about the cardholder.
broadcast_info	false	object	Unstructured information sent to the 3DS Server, Directory Server and Access Control Server.
message_extensions	false	array	Array of Message Extensions - Data necessary to support requirements not defined in the standard 3DS format.

Authentication Categories

Authentication Category	Description
payment	Utilized when a future financial transaction is intended (including $0 authentications).
non-payment	Utilized when the authentication is unrelated to an actual or anticipated charge.

Authentication Types

The authentication type can differ depending on the 3DS session type. See table below for details.

Authentication Type	Allowed Session Type(s)	Description
payment-transaction	customer	Used for a single exchange of goods. (e.g. E-commerce checkout)
cardholder-emv-verification	customer	For verifying cardholder via EMV (chip-based authentication), typically in physical payment scenarios.
recurring-transaction	customer, merchant	Used for ongoing subscriptions where the billed amount is always the same. (e.g. Monthly Subscription)
installment-transaction	customer, merchant	Used for breaking a single purchase into multiple installments. (e.g. Buy Now Pay Later)
add-card	customer, merchant	For adding cards to a customer account—used to verify 3DS capability without an immediate transaction.
maintain-card	customer, merchant	Used to update or maintain existing card details without performing a payment.
account-verification	customer, merchant	For verifying a cardholder's account without charging a payment.
split-or-delayed-shipment	merchant	For transactions where goods or services ship separately or at a delayed time from the initial order.
top-up	merchant	Used for adding funds to existing prepaid accounts or cards.
mail-order	merchant	Transactions initiated by mail without direct cardholder interaction.
telephone-order	merchant	Transactions initiated via telephone by merchant without cardholder physically present.
whitelist-status-check	merchant	Checks if the cardholder or merchant is on an issuer-approved whitelist.
other-payment	merchant	For transactions that do not match any other specific payment authentication type.
billing-agreement	merchant	Establishes an agreement permitting future merchant-initiated transactions without further cardholder input.

Challenge Preferences

Value	Code	Description
no-preference	01	No preference.
no-challenge	02	No challenge requested.
challenge-requested	03	Challenge requested.
challenge-mandated	04	Challenge mandated by the issuer.
no-challenge-risk-analysis-performed	05	No challenge, risk analysis already performed.
no-challenge-data-sharing-only	06	No challenge, data sharing only.
no-challenge-strong-consumer-auth	07	No challenge, strong consumer authentication already performed.
no-challenge-whitelist-exemption	08	No challenge, whitelist exemption.
challenge-requested-whitelist-prompt	09	Challenge requested, whitelist prompt if required.
cartes-bancaires	90	Enable Cartes Bancaires Scoring Service.

Purchase Info Object

This object contains information about the purchase itself (if the authentication category is a payment transaction).

Attribute	Required	Type	Description
amount	conditional	string	The purchase amount without any punctuation (i.e. 80000). Required if authentication_category is payment or if authentication_type is recurring-transaction or installment-transaction.
currency	conditional	string	The purchase currency in ISO 4217 currency code. Required if authentication_category is payment or if authentication_type is recurring-transaction or installment-transaction.
exponent	conditional	string	Minor units of currency as specified in ISO 4217. Required if authentication_category is payment or if authentication_type is recurring-transaction or installment-transaction.
date	conditional	string	The purchase date in UTC and YYYYMMDDhhmmss format. Required if authentication_category is payment or if authentication_type is recurring-transaction or installment-transaction.
transaction_type	conditional	string	The type of purchase transaction. See Purchase Transaction Types for values. Required if authentication_category is payment.
installment_count	conditional	string	Maximum number of installments for installment payments. Required if authentication_type is installment-transaction.
recurring_expiration	conditional	string	Final recurring authorization date in YYYYMMDD format. Required if authentication_type is recurring-transaction.
recurring_frequency	conditional	string	Minimum number of days between recurring authorizations. Required if authentication_type is recurring-transaction.

Purchase Transaction Types

Value	Description
purchase	For standard purchase transactions/exchange of goods.
check-acceptance	For transactions involving acceptance of checks as payment.
account-funding	For funding transactions into an existing account or wallet (e.g., digital wallets, prepaid accounts).
quasi-cash	Transactions involving purchasing items directly convertible to cash (e.g., casino chips, money orders).
prepaid-activation-load	Transactions used to activate or load funds onto prepaid cards.

Merchant Info Object

This object contain information about the merchant (who is collecting the money from the purchase).

Attribute	Required	Type	Description
mid	conditional	string	The merchant identifier. This value is provided by your acquirer/payments processor. Required if authentication_category is payment.
acquirer_bin	conditional	string	The merchant Acquirer BIN. This value is provided by your acquirer/payments processor. Required if authentication_category is payment.
name	conditional	string	The merchant's name as defined in the payment system. Required if authentication_category is payment.
url	conditional	string	The merchant's URL. Required if authentication_category is payment.
country_code	conditional	string	ISO 3166-1 numeric three-digit country code of the merchant. Required if authentication_category is payment.
category_code	conditional	string	The merchant's category code (mcc), as defined by the card scheme. Required if authentication_category is payment.
risk_info	false	Merchant Risk Info	Optional information to de-risk the transaction.

Merchant Risk Info Object

Attribute	Required	Type	Description
delivery_email	false	string	The delivery email address for electronic delivery merchandise.
delivery_time_frame	false	string	The merchandise delivery time frame. See Merchant Risk Delivery Time Frames for allowed values.
gift_card_amount	false	string	The purchase amount total of prepaid or gift card(s) as an integer.
gift_card_count	false	string	The total count of individual prepaid or gift cards/codes purchased.
gift_card_currency	false	string	The ISO 4217 three-digit currency code of the gift card.
pre_order_purchase	false	bool	If the merchandise order is a pre-order or not.
pre_order_date	false	string	The date for when the pre-ordered merchandise will be available in YYYYMMDD format.
reordered_purchase	false	bool	If the cardholder is reordering previously purchase merchandise or not.
shipping_method	false	string	The shipping method chosen. See Merchant Risk Shipping Methods for allowed values.

Merchant Risk Delivery Time Frames

Value	Description
electronic-delivery	Merchandise delivered electronically (e.g., email, download).
same-day-shipping	Merchandise shipped on the same day as the transaction date.
overnight-shipping	Merchandise shipped overnight for next-day delivery.
two-or-more-day-shipping	Merchandise shipped with delivery taking two or more days.

Merchant Risk Shipping Methods

Value	Description
ship-to-billing-address	Merchandise shipped directly to the cardholder's billing address.
ship-to-verified-address	Merchandise shipped to an address verified through issuer authentication.
ship-to-different-address	Merchandise shipped to an address different from the billing address.
ship-to-store	Merchandise shipped to a physical store for customer pickup.
digital-goods	Merchandise delivered digitally (e.g., software, online content).
travel-and-event-tickets	Travel arrangements or event tickets delivered electronically or physically.
other	Merchandise delivered via methods not covered by other categories.

Requestor Info Object

The Requestor Info object contains specific details required by certain card networks (American Express, Discover, and Cartes Bancaires).

If you accept transactions from any of these networks, you may include this information with every request. Basis Theory automatically handles the selection of appropriate values per card network.

Attribute	Required	Type	Description
amex_requestor_type	conditional (AMEX only)	string	The merchant type as defined by American Express. See American Express Requestor Types for allowed values.
cb_siret_number	conditional (Cartes Bancaires only)	string	The SIRET number identifying the business establishment in France.
discover_client_id	conditional (Discover only)	string	The unique Client ID assigned by Discover to the merchant/requestor.

American Express Requestor Types

Requestor Type	Description
MER	General Merchant (default for most merchants).
AGG	Aggregator (accepts payments on behalf of third parties).
JCB	JCB-Acquired Merchant (merchants acquired directly by JCB).
OTA	Online Travel Agency (travel or hospitality sectors).
OPT	OptBlue Seller (merchants enrolled in AMEX OptBlue).
WAL	Digital Wallet (e.g., Apple Pay, Google Pay).

Cardholder Info Object

This object has information about who the cardholder is. Take note that most issuers tend to request at least the name and email properties for successful transactions.

Attribute	Required	Type	Description
name	true	string	The cardholder name.
email	true	string	The cardholder email.
account_id	false	string	The cardholder account identifier - used to reference the cardholder in the merchant's system.
account_type	false	string	The type of cardholder account. See Cardholder Account Types for allowed values.
account_info	false	Cardholder Account Info	Information about the cardholder's account.
authentication_info	false	Cardholder Authentication Info	Information on how the cardholder was authenticated in the merchant platform.
prior_authentication_info	false	Cardholder Prior Authentication Info	Information about the cardholder's previous 3DS authentication.
phone_number	false	Cardholder Phone Number	The cardholder main phone number.
mobile_phone_number	false	Cardholder Phone Number	The cardholder mobile phone number.
work_phone_number	false	Cardholder Phone Number	The cardholder work phone number.
billing_shipping_address_match	false	string	If the billing and shipping address match or not. Use Y for yes and N for no.
billing_address	false	Cardholder Address	The cardholder billing address.
shipping_address	false	Cardholder Address	The cardholder shipping address.

Cardholder Account Types

Value	Description
debit	The card used for the transaction is a debit card.
credit	The card used for the transaction is a credit card.

Cardholder Account Info Object

This object has information about the cardholder's account with the merchant platform.

Attribute	Required	Type	Description
account_age	false	string	Length of time that the cardholder has had the account. See Cardholder Account Age for allowed values.
account_last_changed	false	string	Time since the account was last changed. See Cardholder Account Last Changed for allowed values.
account_change_date	false	string	Date the account was last changed in YYYYMMDD format.
account_created_date	false	string	Date the account was created in YYYYMMDDD format.
account_pwd_last_changed	false	string	Time since the account password was last changed. See Cardholder Account Password Last Changed for allowed values.
account_pwd_change_date	false	string	The password change date in YYYYMMDD format.
purchase_count_half_year	false	string	Number of purchases by the cardholder in the last six months.
transaction_count_day	false	string	Number of transactions by this cardholder in the last 24 hours.
payment_account_age	false	string	Date the payment method was added to the account in YYYYMMDD format.
transaction_count_year	false	string	Number of transactions by this cardholder in the last year.
payment_account_created	false	string	Time since the payment method was added to the account. See Cardholder Payment Account Created for allowed values.
shipping_address_first_used	false	string	Time since the shipping address was first used. See Cardholder Shipping Address First Used for allowed values.
shipping_address_usage_date	false	string	Date when the shipping address was first used in YYYYMMDD format.
shipping_account_name_match	false	bool	If the cardholder name matches with the shipping name for the transaction.
suspicious_activity_observed	false	bool	If any suspicious activity was ever observed in the cardholder account or not.

Cardholder Account Age

Value	Description
no-account	The cardholder does not have an account with the merchant.
created-this-transaction	The cardholder account was created during this transaction.
less-than-30-days	The cardholder account was created less than 30 days ago.
30-to-60-days	The cardholder account was created between 30 and 60 days ago.
more-than-60-days	The cardholder account was created more than 60 days ago.

Cardholder Account Last Changed

Value	Description
no-change	The cardholder account has not been changed.
changed-this-transaction	The cardholder account was changed during this transaction.
less-than-30-days	The cardholder account was changed less than 30 days ago.
30-to-60-days	The cardholder account was changed between 30 and 60 days ago.
more-than-60-days	The cardholder account was changed more than 60 days ago.

Cardholder Account Password Last Changed

Value	Description
no-change	The cardholder account password has not been changed.
changed-this-transaction	The cardholder account password was changed during this transaction.
less-than-30-days	The cardholder account password was changed less than 30 days ago.
30-to-60-days	The cardholder account password was changed between 30 and 60 days ago.
more-than-60-days	The cardholder account password was changed more than 60 days ago.

Cardholder Payment Account Created

Value	Description
no-account	The cardholder does not have a payment account with the merchant.
created-this-transaction	The cardholder payment account was created during this transaction.
less-than-30-days	The cardholder payment account was created less than 30 days ago.
30-to-60-days	The cardholder payment account was created between 30 and 60 days ago.
more-than-60-days	The cardholder payment account was created more than 60 days ago.

Cardholder Shipping Address First Used

Value	Description
no-address	The cardholder does not have a shipping address with the merchant.
address-first-used	The cardholder shipping address was first used during this transaction.
less-than-30-days	The cardholder shipping address was first used less than 30 days ago.
30-to-60-days	The cardholder shipping address was first used between 30 and 60 days ago.
more-than-60-days	The cardholder shipping address was first used more than 60 days ago.

Cardholder Authentication Info Object

This object has information on how the cardholder authenticated with the merchant platform.

Attribute	Required	Type	Description
method	false	string	The cardholder method of authentication. See Cardholder Authentication Methods for allowed values.
timestamp	false	string	The UTC authentication timestamp in YYYYMMDDhhmm format.
data	false	string	Additional data for a specific authentication process.

Cardholder Authentication Methods

Value	Description
no-login	The cardholder did not log in to the merchant platform.
username-password	The cardholder logged in using a username and password.
federated-id	The cardholder logged in using a federated identity (e.g., Google, Facebook).
issuer-credentials	The cardholder logged in using issuer credentials.
third-party	The cardholder logged in using a third-party authentication method.
fido	The cardholder logged in using FIDO authentication.
fido-data-signed	The cardholder logged in using FIDO authentication with signed data.
src-assurance-data	SRC assurance data.

Cardholder Prior Authentication Info Object

This object has information about the cardholder prior 3DS transaction authentication.

Attribute	Required	Type	Description
method	false	string	The cardholder prior 3DS authentication method. See Cardholder Prior Authentication Methods for allowed values.
timestamp	false	string	The UTC prior authentication timestamp in YYYYMMDDhhmm format.
reference_id	false	string	An ACS Transaction ID for a prior authenticated transaction.
data	false	string	Additional data for a specific authentication process.

Cardholder Prior Authentication Methods

Value	Description
frictionless	The cardholder authenticated a 3DS transaction frictionless.
challenged	The cardholder authenticated a 3DS transaction after a challenge.
avs-verified	The cardholder authenticated a 3DS transaction using AVS verification.
other	The cardholder authenticated a 3DS transaction using other methods.

Cardholder Phone Number Object

Attribute	Required	Type	Description
country_code	false	string	Phone country code.
number	false	string	Phone subscriber number.

Cardholder Address Object

Attribute	Required	Type	Description
line1	false	string	The first line of the address.
line2	false	string	The second line of the address.
line3	false	string	The third line of the address.
postal_code	false	string	Address postal code.
city	false	string	Address city.
state_code	false	string	ISO 3166-2 country subdivision code for the state or province of the address.
country_code	false	string	ISO 3166-1 numeric three-digit country code of the address.

Response

Returns a 3DS authentication. Returns an error if there were validation errors, or the session failed to authenticate.

{
  "pan_token_id": "f9e45271-b3de-4729-8c1a-9cdd42417fc5",
  "token_id": "f9e45271-b3de-4729-8c1a-9cdd42417fc5",
  "session_id": "c0c22fcd-d42c-497e-a9a6-2eacd31770d7",
  "threeds_version": "2.2.0",
  "acs_transaction_id": "ec2a5868-ce1b-44c7-9249-bc5b0aa409a3",
  "ds_transaction_id": "22aeb643-1489-46ee-83aa-af1a01b457c9",
  "acs_reference_number": "mock-acs-reference-number",
  "ds_reference_number": "mock-directory-server-a",
  "liability_shifted": false,
  "authentication_status": "challenge",
  "authentication_status_code": "C",
  "directory_status_code": "C",
  "acs_challenge_mandated": "N",
  "authentication_challenge_type": "static",
  "acs_challenge_url": "https://acs.example.com/3ds/acs/browser/creq",
  "challenge_preference": "no-challenge",
  "challenge_preference_code": "02"
}

Get Challenge Result

Get the result of a 3DS Challenge for the given session id.

GET

https://api.basistheory.com/3ds/sessions/{id}/challenge-result

Permissions

3ds:session:authenticate

Request

cURL

curl "https://api.basistheory.com/3ds/sessions/c0c22fcd-d42c-497e-a9a6-2eacd31770d7/challenge-result" \
  -H "BT-API-KEY: <API_KEY>"

Node

await client.threeds.sessions.getChallengeResult("c0c22fcd-d42c-497e-a9a6-2eacd31770d7");

C#

await client.Threeds.Sessions.GetChallengeResultAsync("c0c22fcd-d42c-497e-a9a6-2eacd31770d7");

Python

await client.threeds.sessions.get_challenge_result("c0c22fcd-d42c-497e-a9a6-2eacd31770d7")

Go

result, err := client.Threeds.Sessions.GetChallengeResult("c0c22fcd-d42c-497e-a9a6-2eacd31770d7")

URI Parameters

Parameter	Required	Type	Default	Description
id	true	string	null	The ID of the 3DS session.

Response

Returns a 3DS authentication. Returns an error if the session was not found or if challenge result cannot be retrieved.

{
  "pan_token_id": "f9e45271-b3de-4729-8c1a-9cdd42417fc5",
  "token_id": "f9e45271-b3de-4729-8c1a-9cdd42417fc5",
  "session_id": "c0c22fcd-d42c-497e-a9a6-2eacd31770d7",
  "threeds_version": "2.2.0",
  "acs_transaction_id": "ec2a5868-ce1b-44c7-9249-bc5b0aa409a3",
  "ds_transaction_id": "22aeb643-1489-46ee-83aa-af1a01b457c9",
  "acs_reference_number": "mock-acs-reference-number",
  "ds_reference_number": "mock-directory-server-a",
  "liability_shifted": false,
  "authentication_value": "LVJhdmVsaW4gVGVzdCBWYWx1ZS0=",
  "authentication_status": "successful",
  "authentication_status_code": "Y",
  "directory_status_code": "C",
  "eci": "05",
  "acs_challenge_mandated": "N",
  "authentication_challenge_type": "static",
  "acs_challenge_url": "https://acs.example.com/3ds/acs/browser/creq",
  "challenge_attempts": "01",
  "message_extensions": []
}

Session Object

Attribute	Type	Description
id	uuid	Unique identifier of the session.
tenant_id	uuid	The Tenant ID which owns the session.
type	string	The type of 3DS session - customer or merchant.
pan_token_id	string	DEPRECATED The ID of the card token used in the 3DS transaction.
token_id	string	The ID of the card token used in the 3DS transaction.
token_intent_id	string	The ID of the card token intent used in the 3DS transaction.
card_brand	string	The brand for the card used in the 3DS transaction.
expiration_date	string	Date for when the 3DS session will expire.
created_date	string	Created date of the session in ISO 8601 format.
created_by	uuid	The Application ID which created the session.
modified_date	string	(Optional) Last modified date of the session in ISO 8601 format.
modified_by	uuid	(Optional) The Application ID which last modified the session.
device	string	The type of device used to create the 3DS session - browser or mobile.
device_info	Device Info	Information about the device (collected by the SDKs) used to create the 3DS session.
version	Version	Information about the supported 3DS version.
method	Method	Information about the 3DS method invocation (device fingerprinting).
authentication	Authentication	The 3DS session authentication outcome.

Device Info Object

Attribute	Type	Description
browser_javascript_enabled	bool	Indicates if JavaScript is enabled in the browser. (browser device only)
browser_java_enabled	bool	Indicates if Java is enabled in the browser. (browser device only)
browser_language	string	The language set in the browser. (browser device only)
browser_color_depth	string	The color depth of the browser. (browser device only)
browser_screen_height	string	The screen height of the browser. (browser device only)
browser_screen_width	string	The screen width of the browser. (browser device only)
browser_tz	string	The timezone of the browser. (browser device only)
browser_user_agent	string	The user agent string of the browser. (browser device only)
browser_accept_header	string	The HTTP Accept header value from the browser. (browser device only)
browser_ip	string	The IP address of the browser. (browser device only)
sdk_transaction_id	string	The ID of the SDK transaction. (app device only)
sdk_application_id	string	The ID for the application using the SDK. (app device only)
sdk_encryption_data	string	The encryption data used by the SDK. (app device only)
sdk_ephemeral_public_key	string	The ephemeral public key used by the SDK. (app device only)
sdk_max_timeout	string	The maximum timeout for the SDK. (app device only)
sdk_reference_number	string	The reference number used by the SDK. (app device only)
sdk_render_options	object	The render options used by the SDK. See SDK Render Options. (app device only)

SDK Render Options Object

Attribute	Type	Description
sdk_interface	string	The interface types the mobile device supports.
sdk_ui_type	array	The UI types the device supports for displaying challenge UIs.

Version Object

Attribute	Type	Description
recommended_version	string	The 3DS version that was used for the transaction.
available_version	array	All 3DS versions the card supports.
earliest_acs_supported_version	string	The earliest 3DS version supported by the Access Control Server (ACS).
latest_acs_supported_version	string	The latest 3DS version supported by the Access Control Server (ACS).
earliest_ds_supported_version	string	The earliest 3DS version supported by the Directory Server (DS).
latest_ds_supported_version	string	The latest 3DS version supported by the Directory Server (DS).
acs_information	array	Additional information provided by the Access Control Server (ACS).

Method Object

Attribute	Type	Description
method_url	string	The URL for the Method request, used by the 3DS SDK.
method_completion_indicator	string	Indicates whether the method request completed successfully or not.

Method Completion Indicator

Value	Description
Y	Method request completed successfully.
N	Method request did not complete successfully.
U	Method request result was unavailable.

Authentication Object

Attribute	Type	Description
pan_token_id	string	DEPRECATED The ID of the card token used in the 3DS transaction.
token_id	string	The ID of the card token used in the 3DS transaction.
token_intent_id	string	The ID of the card token intent used in the 3DS transaction.
session_id	string	The ID of the 3DS session.
threeds_version	string	The 3DS version used in the transaction.
acs_transaction_id	string	The transaction ID from the 3DS Access Control Server (ACS).
ds_transaction_id	string	The transaction ID from the 3DS Directory Server (DS).
acs_reference_number	string	A unique identifier assigned to the DS by EMVCo.
ds_reference_number	string	A unique identifier assigned to the ACS by EMVCo.
liability_shifted	_boolean	Indicates whether liability for the transaction was shifted to the issuer or not.
authentication_value	string	The token value used to authorize the transaction. Also know as CAVV, AAV, AEVV, etc.
authentication_status	string	The outcome of the 3DS authentication. See Authentication Status.
authentication_status_code	string	EMV character code for the authentication status.
authentication_status_reason	string	Additional information about the authentication status if necessary. See Authentication Status Reason.
directory_status_code	string	EMV character code for the directory authentication status.
eci	string	Electronic Commerce Indicator (ECI).
acs_challenge_mandated	string	Indicates whether regional mandates (e.g., PSD2) required a challenge to be performed. See ACS Challenge Mandated.
authentication_challenge_type	string	The type of challenge authentication used (if challenge). See Authentication Challenge Type.
acs_challenge_url	string	The URL to be used for the challenge.
challenge_preference	string	The selected Challenge Preference during authentication.
challenge_preference_code	string	EMV numeric code for the selected challenge preference.
challenge_attempts	string	The number of challenges attempted by the cardholder.
challenge_cancel_reason	string	The reason why a challenge was cancelled. See Challenge Cancel Reason.
challenge_cancel_reason_code	string	EMV numeric code for the challenge cancel reason.
cardholder_info	string	Information from the issuer to be displayed to the cardholder.
whitelist_status	string	Indicates if the cardholder whitelisted the merchant. See Whitelist Status.
whitelist_status_source	string	Identifies the system that set the whitelist value. See Whitelist Status Source.
message_extensions	array	Array of Message Extensions - Data necessary to support requirements not defined in the standard 3DS format.

ACS Challenge Mandated

Value	Description
Y	Challenge is mandated by the ACS.
N	Challenge is not mandated by the ACS.

Authentication Status

Value	Code	Description
successful	Y	3DS authentication was successful.
attempted	A	3DS authentication was attempted but not possible. Successful authentication granted by card brand on issuer's behalf.
failed	N	Authentication failed, stop the transaction.
unavailable	U	Authentication could not be performed. Try to proceed without the authentication value.
challenge	C	A challenge is required, use the SDK to perform the Challenge.
decoupled_challenge	D	A challenge will be performed by the issuer. Get the Challenge Result to learn the outcome.
rejected	R	The issuer rejected the authentication attempt.
informational	I	Authentication not requested, data sent to the ACS for informational purposes.

Authentication Status Reason

Value	Description
card-authentication-failed	Card authentication failed.
unknown-device	Unknown device detected.
unsupported-device	Device not supported for authentication.
too-many-authentication-attempts	Too many failed authentication attempts.
card-expired	Card is expired.
invalid-card-number	Card number is invalid.
invalid-transaction	Transaction is invalid - authentication not allowed.
no-card-record	No record found for the card.
security-failure	Security validation failed.
stolen-card	Card is reported stolen.
suspected-fraud	Transaction flagged as fraudulent.
transaction-not-permitted	Transaction not allowed for this card.
cardholder-not-enrolled	Cardholder not enrolled in 3DS - 3DS not required for card.
timeout-at-acs	ACS (Access Control Server) timeout.
low-confidence	Low confidence authentication, Frictionless Scenario Authentication successful - authentication results available for payment.
medium-confidence	Medium confidence authentication, Frictionless Scenario Authentication successful - authentication results available for payment.
high-confidence	High confidence authentication, Frictionless Scenario Authentication successful - authentication results available for payment.
very-high-confidence	Very high confidence authentication, Frictionless Scenario Authentication successful - authentication results available for payment.
max-challenges-exceeded	Too many authentication challenges.
non-payment-transaction-not-support	3DS not supported for non-payment transactions.
3ri-not-supported	Merchant initiated 3DS transaction not supported (merchant session type).
acs-technical-issue	ACS encountered a technical issue.
decoupled-authentication-required	Decoupled authentication is required.
decoupled-authentication-timeout	Decoupled authentication timed out.
insufficient-decoupled-authentication-time	Not enough time for decoupled authentication.
authentication-attempted-but-not-performed	Authentication attempted but not completed, Frictionless Scenario Authentication successful - authentication results available for payment.
identity-check-insights	Additional identity verification insights provided, Frictionless Scenario Authentication successful - authentication results available for payment.
error-connecting-to-acs	Error connecting to ACS.
acs-timed-out	Request timed out at ACS.
invalid-response-from-acs	ACS sent an invalid response.
system-error-response-from-acs	System error occurred at ACS.
internal-error-while-generating-cavv	Internal error while generating authentication value.
vmid-not-eligible-for-requested-program	Merchant ID is not eligible for 3DS program, reach out to Basis Theory.
protocol-version-not-supported-by-acs	ACS does not support this protocol version, reach out to Basis Theory.
device-3ri-not-routed-to-smart-authentication-stand-in	Device merchant initiated transaction routing issue.
transaction-excluded-from-attempts-processing	Transaction was excluded from attempts processing.

Authentication Challenge Type

Value	Description
static	Static challenge, for example, a password or passcode.
dynamic	Dynamic challenge, for example, a one time password (OTP).
out-of-band	Out-of-Band challenge, for example, using the issuing bank's mobile app.
decoupled	Decoupled challenge.

Challenge Cancel Reason

Value	Code	Description
cardholder-canceled	01	Cardholder selected 'Cancel' on the challenge.
requestor-canceled	02	3DS requestor cancelled authentication.
transaction-abandoned	03	Transaction was abandoned.
acs-timeout	04	Transaction timed out at ACS.
acs-timeout-request-not-received	05	Transaction timed out at ACS - Challenge request not received.
error	06	Transaction error.
unknown	07	Unknown reason.

Whitelist Status

Value	Description
merchant-trusted	Merchant is trusted by the cardholder.
merchant-not-trusted	Merchant has not yet been trusted by the cardholder.
not-eligible	Not eligible to whitelist as determined by the issuer.
pending-confirmation	Pending confirmation by the cardholder.
request-to-trust-rejected	Cardholder rejected the request to trust the merchant.
unknown	Trusted status unknown.

Whitelist Status Source

Value	Description
3ds-server	3DS Server.
directory-server	Directory Server (DS).
acs	Access Control Server (ACS).

Message Extension Object

Attribute	Type	Description
id	string	The id for the extensions.
name	string	The name for the extension.
critical	bool	If the extension is critical or not.
data	string	Data carried in the extension.

Test Cards

Please contact support@basistheory.com before testing the 3DS feature.

See below a pre-defined list of cards that can be used to test different 3DS scenarios.

The "Card Brand" column is meant for usage when testing Bin Details and is not reflected in 3DS responses.

Card Number	Card Brand	3DS Scenario	Is Luhn Valid
5204247750001471	MASTERCARD	Successful Frictionless Authentication	Yes
6011601160116011	DISCOVER	Successful Frictionless Authentication	Yes
340000000004001	AMEX	Successful Frictionless Authentication	Yes
4000020000000000	VISA	Successful Challenge Authentication	Yes
370000000000002	AMEX	Successful Challenge Authentication	Yes
3566002020360505	JCB	Successful Challenge Authentication	Yes
3566006663297692	JCB	Successful Challenge Authentication	Yes
4005562231212123	VISA	Successful Challenge Authentication - Method not Required	Yes
4761369980320253	VISA	Successful Mandated Challenge Authentication	Yes
5200000000001104	MASTERCARD	Successful Mandated Challenge Authentication	Yes
4000000000000341	VISA	Successful Out-of-Band Challenge Authentication	Yes
4005571701111111	VISA	Attempted Challenge Authentication	Yes
4111111111111111	VISA	Authentication Attempted	Yes
5424180011113336	MASTERCARD	Authentication Attempted	Yes
4264281511112228	VISA	Authentication Failed	Yes
5424180000000171	MASTERCARD	Authentication Failed	Yes
5405001111111165	MASTERCARD	Authentication Unavailable	Yes
5405001111111116	MASTERCARD	Authentication Rejected	Yes
4055011111111111	VISA	Failed Challenge Authentication	Yes
5427660064241339	MASTERCARD	Failed Challenge Authentication	Yes
6011361011110004	DISCOVER	Failed Out of Band Challenge Authentication	Yes
6011361000008888	DISCOVER	Unavailable Challenge Authentication	Yes
6011361000001115	DISCOVER	Rejected Challenge Authentication	Yes
4264281500003339	VISA	3DS Directory Server Error	Yes
5424180011110001	MASTERCARD	3DS Directory Server Error	Yes
4264281500001119	VISA	Internal 3DS Server Error	Yes
4200000000000002	VISA	Successful Frictionless Authentication	No
4200000000000004	VISA	Successful Challenge Authentication	No
4200000000000014	VISA	Successful Challenge Authentication - Method not Required	No
4200000000000015	VISA	Successful Mandated Challenge Authentication	No
4200000000000016	VISA	Successful Out-of-Band Challenge Authentication	No
4200000000000008	VISA	Attempted Challenge Authentication	No
4200000000000003	VISA	Authentication Attempted	No
4200000000000005	VISA	Authentication Failed	No
4200000000000006	VISA	Authentication Unavailable	No
4200000000000007	VISA	Authentication Rejected	No
4200000000000009	VISA	Failed Challenge Authentication	No
4200000000000017	VISA	Failed Out of Band Challenge Authentication	No
4200000000000010	VISA	Unavailable Challenge Authentication	No
4200000000000011	VISA	Rejected Challenge Authentication	No
4200000000000012	VISA	3DS Directory Server Error	No
4200000000000013	VISA	Internal 3DS Server Error	No