3D Secure
Enterprise

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

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 "https://api.basistheory.com/3ds/sessions/c06d0789-0a38-40be-b7cc-c28a718f76f1" \
  -H "BT-API-KEY: <PRIVATE_API_KEY>"

import { BasisTheory } from "@basis-theory/basis-theory-js";

const bt = await new BasisTheory().init("<PRIVATE_API_KEY>");

const session = await bt.threeds.getSessionById("c06d0789-0a38-40be-b7cc-c28a718f76f1");

using BasisTheory.net.ThreeDS;

var client = new ThreeDSClient("<PRIVATE_API_KEY>");

var session = await client.GetSessionByIdAsync("c06d0789-0a38-40be-b7cc-c28a718f76f1");

import com.basistheory.*;
import com.basistheory.auth.*;

public class Example {
    public static void main(String[] args) throws Exception {
        ApiClient defaultClient = Configuration.getDefaultApiClient();
        defaultClient.setBasePath("https://api.basistheory.com");

        ApiKeyAuth ApiKey = (ApiKeyAuth) defaultClient.getAuthentication("ApiKey");
        ApiKey.setApiKey("<PRIVATE_API_KEY>");

        ThreeDsApi apiInstance = new ThreeDsApi(defaultClient);
        ThreeDSSession result = apiInstance.threeDSGetSessionById("c06d0789-0a38-40be-b7cc-c28a718f76f1");
    }
}

import basistheory
from basistheory.api import three_ds_api

with basistheory.ApiClient(configuration=basistheory.Configuration(api_key="<PRIVATE_API_KEY>")) as api_client:
    three_ds_client = three_ds_api.ThreeDSApi(api_client)

    result = three_ds_client.three_ds_get_session_by_id(id="c06d0789-0a38-40be-b7cc-c28a718f76f1")

package main

import (
  "context"
  "github.com/Basis-Theory/basistheory-go/v5"
)

func main() {
  configuration := basistheory.NewConfiguration()
  apiClient := basistheory.NewAPIClient(configuration)
  contextWithAPIKey := context.WithValue(context.Background(), basistheory.ContextAPIKeys, map[string]basistheory.APIKey{
    "ApiKey": {Key: "<PRIVATE_API_KEY>"},
  })

  result, httpResponse, err := apiClient.ThreeDSApi.ThreeDSGetSessionById(contextWithAPIKey, "c06d0789-0a38-40be-b7cc-c28a718f76f1").Execute()
}

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": "be3bec00-a1c3-4ffe-8971-20a30bbee031",
    "tenant_id": "9f328a79-b397-42ac-9b8d-18312157cc6b",
    "pan_token_id": "bfe0060c-a465-41a0-a620-c804952d3468",
    "card_brand": "Visa",
    "expiration_date": "2024-03-23T14:01:26.4544211+00:00",
    "created_date": "2024-03-22T14:01:26.455016+00:00",
    "created_by": "68909d60-3e1d-4b3d-bf68-166c95745c4c",
    "modified_date": "2024-03-22T14:01:45.3094992+00:00",
    "modified_by": "7da53434-d814-4bd7-a455-6a4757c5c888",
    "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": "3440",
        "browser_tz": "180",
        "browser_user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/123.0.0.0 Safari/537.36"
    },
    "version": {
        "recommended_version": "2.2.0",
        "available_version": [
            "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": []
    },
    "method": {
        "method_url": "https://acs.example.com/3ds/acs/browser/method",
        "method_completion_indicator": "Y"
    },
    "authentication": {
        "threeds_version": "2.2.0",
        "acs_transaction_id": "50b9c543-4abc-4fbd-8bed-7e1931ed862c",
        "ds_transaction_id": "497acd8d-4b50-4f55-9e56-c6dcaeff2933",
        "acs_reference_number": "mock-acs-reference-number",
        "ds_reference_number": "mock-directory-server-a",
        "authentication_value": "LVJhdmVsaW4gVGVzdCBWYWx1ZS0=",
        "authentication_status": "successful",
        "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 "https://api.basistheory.com/3ds/sessions/c06d0789-0a38-40be-b7cc-c28a718f76f1/authenticate" \
  -H "BT-API-KEY: <API_KEY>" \
  -H "Content-Type: application/json" \
  -X "POST" \
  -d '{
    "authentication_category": "payment",
    "authentication_type": "payment-transaction",
    "purchase_info": {
        "amount": "80000",
        "currency": "826",
        "exponent": "2",
        "date": "20240109141010"
    },
    "requestor_info":  {
        "id": "example-3ds-merchant",
        "name": "Example 3DS Merchant",
        "url": "https://www.example.com/example-merchant"
    },
    "merchant_info": {
        "mid": "9876543210001",
        "acquirer_bin": "000000999",
        "name": "Example 3DS Merchant",
        "category_code": "7922",
        "country_code": "826"
    },
    "cardholder_info": {
        "name": "John Doe",
        "email": "john@me.com"
    }
  }'

import { BasisTheory } from "@basis-theory/basis-theory-js";

const bt = await new BasisTheory().init("<API_KEY>");

const authentication = await bt.threeds.authenticateSession("c06d0789-0a38-40be-b7cc-c28a718f76f1", {
  authenticationCategory: "payment",
  authenticationType: "payment-transaction",
  purchaseInfo: {
    amount: "80000",
    currency: "826",
    exponent: "2",
    date: "20240109141010"
  },
  requestorInfo: {
    id: "example-3ds-merchant",
    name: "Example 3DS Merchant",
    url: "https://www.example.com/example-merchant"
  },
  merchantInfo: {
    mid: "9876543210001",
    acquirerBin: "000000999",
    name: "Example 3DS Merchant",
    categoryCode: "7922",
    countryCode: "826"
  },
  cardholderInfo: {
    name: "John Doe",
    email: "john@me.com"
  }
});

using BasisTheory.net.ThreeDS;
using BasisTheory.net.ThreeDS.Requests;

var client = new ThreeDSClient("<API_KEY>");

var authentication = await client.AuthenticateThreeDSSessionAsync("c06d0789-0a38-40be-b7cc-c28a718f76f1", new AuthenticateThreeDSSessionRequest {
  AuthenticationCategory = "payment",
  AuthenticationType = "payment-transaction",
  PurchaseInfo = new ThreeDSPurchaseInfo {
    Amount = "80000",
    Currency = "826",
    Exponent = "2",
    Date = "20240109141010"
  },
  RequestorInfo = new ThreeDSRequestorInfo {
    Id = "example-3ds-merchant",
    Name = "Example 3DS Merchant",
    Url = "https://www.example.com/example-merchant"
  },
  MerchantInfo = new ThreeDSMerchantInfo {
    Mid = "9876543210001",
    AcquirerBin = "000000999",
    Name = "Example 3DS Merchant",
    CategoryCode = "7922",
    CountryCode = "826"
  },
  CardholderInfo = new ThreeDSCardholderInfo {
    Name = "John Doe",
    Email = "john@me.com"
  }
});

import com.basistheory.*;
import com.basistheory.auth.*;
import java.util.Arrays;
import java.util.Map;

public class Example {
    public static void main(String[] args) throws Exception {
        ApiClient defaultClient = Configuration.getDefaultApiClient();
        defaultClient.setBasePath("https://api.basistheory.com");

        ApiKeyAuth ApiKey = (ApiKeyAuth) defaultClient.getAuthentication("ApiKey");
        ApiKey.setApiKey("<API_KEY>");

        ThreeDsApi apiInstance = new ThreeDsApi(defaultClient);
        AuthenticateThreeDSSessionRequest authenticateThreeDSSessionRequest = new AuthenticateThreeDSSessionRequest();
        ThreeDSAuthentication result = apiInstance.threeDSAuthenticateSession("c06d0789-0a38-40be-b7cc-c28a718f76f1", authenticateThreeDSSessionRequest
          .authenticationCategory("payment")
          .authenticationType("payment-transaction")
          .purchaseInfo(new ThreeDSPurchaseInfo()
            .amount("80000")
            .currency("826")
            .exponent("2")
            .date("20240109141010"))
          .requestorInfo(new ThreeDSRequestorInfo()
            .id("example-3ds-merchant")
            .name("Example 3DS Merchant")
            .url("https://www.example.com/example-merchant"))
          .merchantInfo(new ThreeDSMerchantInfo()
            .mid("9876543210001")
            .acquirerBin("000000999")
            .name("Example 3DS Merchant")
            .categoryCode("7922")
            .countryCode("826"))
          .cardholderInfo(new ThreeDSCardholderInfo()
            .name("John Doe")
            .email("john@me.com")));
        System.out.println(result);
    }
}

import basistheory
from basistheory.api import three_ds_api
from basistheory.model.authenticate_three_ds_session_request import AuthenticateThreeDSSessionRequest

with basistheory.ApiClient(configuration=basistheory.Configuration(api_key="<API_KEY>")) as api_client:
    three_ds_client = three_ds_api.ThreeDSApi(api_client)

    authentication = three_ds_client.three_ds_authenticate_session("c06d0789-0a38-40be-b7cc-c28a718f76f1", authenticate_three_ds_session_request=AuthenticateThreeDSSessionRequest(
        authentication_category="payment",
        authentication_type="payment-transaction",
        purchase_info=basistheory.ThreeDSPurchaseInfo(
            amount="80000",
            currency="826",
            exponent="2",
            date="20240109141010"
        ),
        requestor_info=basistheory.ThreeDSRequestorInfo(
            id="example-3ds-merchant",
            name="Example 3DS Merchant",
            url="https://www.example.com/example-merchant"
        ),
        merchant_info=basistheory.ThreeDSMerchantInfo(
            mid="9876543210001",
            acquirer_bin="000000999",
            name="Example 3DS Merchant",
            category_code="7922",
            country_code="826"
        ),
        cardholder_info=basistheory.ThreeDSCardholderInfo(
            name="John Doe",
            email="john@me.com"
    )))

package main

import (
  "context"
  "github.com/Basis-Theory/basistheory-go/v5"
)

func main() {
  configuration := basistheory.NewConfiguration()
  apiClient := basistheory.NewAPIClient(configuration)
  contextWithAPIKey := context.WithValue(context.Background(), basistheory.ContextAPIKeys, map[string]basistheory.APIKey{
    "ApiKey": {Key: "<API_KEY>"},
  })

  sessionId := "c06d0789-0a38-40be-b7cc-c28a718f76f1"
  authenticateThreeDSSessionRequest := *basistheory.NewAuthenticateThreeDSSessionRequest()
  authenticateThreeDSSessionRequest.SetAuthenticationCategory("payment")
  authenticateThreeDSSessionRequest.SetAuthenticationType("payment-transaction")

  purchaseInfo := *basistheory.NewThreeDSPurchaseInfo()
  purchaseInfo.SetAmount("80000")
  purchaseInfo.SetCurrency("826")
  purchaseInfo.SetExponent("2")
  purchaseInfo.SetDate("20240109141010")

  requestorInfo := *basistheory.NewThreeDSRequestorInfo()
  requestorInfo.SetId("example-3ds-merchant")
  requestorInfo.SetName("Example 3DS Merchant")
  requestorInfo.SetUrl("https://www.example.com/example-merchant")

  merchantInfo := *basistheory.NewThreeDSMerchantInfo()
  merchantInfo.SetMid("9876543210001")
  merchantInfo.SetAcquirerBin("000000999")
  merchantInfo.SetName("Example 3DS Merchant")
  merchantInfo.SetCategoryCode("7922")
  merchantInfo.SetCountryCode("826")

  cardholderInfo := *basistheory.NewThreeDSCardholderInfo()
  cardholderInfo.SetName("John Doe")
  cardholderInfo.SetEmail("john@me.com")

  authenticateThreeDSSessionRequest.SetPurchaseInfo(purchaseInfo)
  authenticateThreeDSSessionRequest.SetRequestorInfo(requestorInfo)
  authenticateThreeDSSessionRequest.SetMerchantInfo(merchantInfo)
  authenticateThreeDSSessionRequest.SetCardholderInfo(cardholderInfo)

  authenticateResponse, authenticateHttpResponse, authenticateErr := apiClient.ThreeDSApi.ThreeDSAuthenticateSession(contextWithAPIKey, sessionId).AuthenticateThreeDSSessionRequest(authenticateThreeDSSessionRequest).Execute()
}

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
`challenge_preference`	false	string	The merchant 3DS challenge preference, see Challenge Preferences for allowed values
`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`
`merchant_info`	conditional	Merchant Info	Information about the merchant. Required if `authentication_category` is `payment`
`requestor_info`	true	Requestor Info	Information about the 3DS requestor
`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

payment - for any 3DS transaction that ends in a purchase / exchange of money.
non-payment - for just adding cards to accounts.

Authentication Types

payment-transaction
recurring-transaction
installment-transaction
add-card
maintain-card
cardholder-emv-verification
account-verification

Challenge Preferences

no-preference
no-challenge
challenge-requested
challenge-mandated
no-challenge-risk-analysis-performed
no-challenge-data-sharing-only
no-challenge-strong-consumer-auth
no-challenge-whitelist-exemption
challenge-requested-whitelist-prompt
cartes-bancaires

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

purchase
check-acceptance
account-funding
quasi-cash
prepaid-activation-load

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. Required if `authentication_category` is `payment`
`acquirer_bin`	conditional	string	The merchant/acquirer BIN. Required if `authentication_category` is `payment`
`name`	conditional	string	The merchant's name. 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). 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

electronic-delivery
same-day-shipping
overnight-shipping
two-or-more-day-shipping

Merchant Risk Shipping Methods

ship-to-billing-address
ship-to-verified-address
ship-to-different-address
ship-to-store
digital-goods
travel-and-event-tickets
other

Requestor Info Object

This object contains information about the 3DS requestor, some of it overlap w/ the merchant but has specific rules for different card issuers and brands.

See Instructions for Different Card Brands on how to properly fill this information for the best results.

Attribute	Required	Type	Description
`id`	true	string	The 3DS requestor id
`name`	true	string	The 3DS requestor name
`url`	true	string	A business URL for the 3DS requestor

Instructions for Different Card Brands

See below instructions on how to fill the id and name properties of the Requestor Info Object according to different card brands:

Visa:
- id: Use the merchant id
- name: Use the merchant name
Mastercard:
- id: Use the merchant id
- name: Use Ravelin 3DS Server_{MID}
Discover:
- id: Use the Client ID from enrollment with Discover. Also use the ID assigned to the 3DS requestor if any like so: Discover ClientID_Merchant Name or Discover ClientID_ID
- name: Use the 'Merchant DBA' (Doing Business As) name
JCB:
- id: Use the Acquirer BIN + 'MCT' + MID like: {BIN}MCT{MID}
- name: Use the merchant id
American Express:
- id: Use the relevant 3DS requestor type from the table below together with the merchant id:
  Requestor Type Description
  MER General Merchant
  AGG Aggregator
  JCB JCB-Acquired Merchant
  OTA Online Travel Agency
  OPT OptBlue Seller
  WAL Digital Wallet
- name: Use the merchant id
Cartes Bancaires:
- id: If you are using a Carte Bancaire acquirer and it's a wallet transaction, use the merchant SIRET Number+ 'Identifiant Wallet' for payment/enrolment - Or, just the SIRET Number for non-payment/enrolment. For all other scenarios, use merchant name.
- name: Use the merchant name

Requestor Type	Description
MER	General Merchant
AGG	Aggregator
JCB	JCB-Acquired Merchant
OTA	Online Travel Agency
OPT	OptBlue Seller
WAL	Digital Wallet

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
`account_id`	false	string	The cardholder account identifier
`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
`name`	true	string	The cardholder name
`email`	true	string	The cardholder email
`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

debit
credit

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

no-account
created-this-transaction
less-than-30-days
30-to-60-days
more-than-60-days

Cardholder Account Last Changed

changed-this-transaction
less-than-30-days
30-to-60-days
more-than-60-days

Cardholder Account Password Last Changed

no-change
changed-this-transaction
less-than-30-days
30-to-60-days
more-than-60-days

Cardholder Payment Account Created

no-account
created-this-transaction
less-than-30-days
30-to-60-days
more-than-60-days

Cardholder Shipping Address First Used

this-transaction
less-than-30-days
30-to-60-days
more-than-60-days

Cardholder Authentication Info Object

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

Attribute	Required	Type	Description
`method`	false	Authentication Methods	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

no-login
username-password
federated-id
issuer-credentials
third-party
fido
fido-data-signed
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

frictionless
challenged
avs-verified
other

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.

{
  "threeds_version": "2.2.0",
  "acs_transaction_id": "5657c648-6e5e-4472-aac6-5400b9dab678",
  "ds_transaction_id": "6159159e-ad57-43bf-a886-f5328583d5b2",
  "acs_reference_number": "mock-acs-reference-number",
  "ds_reference_number": "mock-directory-server-a",
  "authentication_value": "LVJhdmVsaW4gVGVzdCBWYWx1ZS0=",
  "authentication_status": "successful",
  "eci": "05"
}

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 "https://api.basistheory.com/3ds/sessions/c06d0789-0a38-40be-b7cc-c28a718f76f1/challenge-result" \
  -H "BT-API-KEY: <PRIVATE_API_KEY>"

import { BasisTheory } from "@basis-theory/basis-theory-js";

const bt = await new BasisTheory().init("<PRIVATE_API_KEY>");

const result = await bt.threeds.getChallengeResult("c06d0789-0a38-40be-b7cc-c28a718f76f1");

using BasisTheory.net.ThreeDS;

var client = new ThreeDSClient("<PRIVATE_API_KEY>");

var result = await client.GetChallengeResultAsync("c06d0789-0a38-40be-b7cc-c28a718f76f1");

import com.basistheory.*;
import com.basistheory.auth.*;

public class Example {
    public static void main(String[] args) throws Exception {
        ApiClient defaultClient = Configuration.getDefaultApiClient();
        defaultClient.setBasePath("https://api.basistheory.com");

        ApiKeyAuth ApiKey = (ApiKeyAuth) defaultClient.getAuthentication("ApiKey");
        ApiKey.setApiKey("<PRIVATE_API_KEY>");

        ThreeDsApi apiInstance = new ThreeDsApi(defaultClient);
        ThreeDSAuthentication result = apiInstance.threeDSGetChallengeResult(sessionId);
    }
}

import basistheory
from basistheory.api import three_ds_api

with basistheory.ApiClient(configuration=basistheory.Configuration(api_key="<PRIVATE_API_KEY>")) as api_client:
    three_ds_client = three_ds_api.ThreeDSApi(api_client)

    result = three_ds_client.three_ds_get_challenge_result(session_id="c06d0789-0a38-40be-b7cc-c28a718f76f1")

package main

import (
  "context"
  "github.com/Basis-Theory/basistheory-go/v5"
)

func main() {
  configuration := basistheory.NewConfiguration()
  apiClient := basistheory.NewAPIClient(configuration)
  contextWithAPIKey := context.WithValue(context.Background(), basistheory.ContextAPIKeys, map[string]basistheory.APIKey{
    "ApiKey": {Key: "<PRIVATE_API_KEY>"},
  })

  result, httpResponse, err := apiClient.ThreeDSApi.ThreeDSGetChallengeResult(contextWithAPIKey, "c06d0789-0a38-40be-b7cc-c28a718f76f1").Execute()
}

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.

{
  "threeds_version": "2.2.0",
  "acs_transaction_id": "50b9c543-4abc-4fbd-8bed-7e1931ed862c",
  "ds_transaction_id": "497acd8d-4b50-4f55-9e56-c6dcaeff2933",
  "acs_reference_number": "mock-acs-reference-number",
  "ds_reference_number": "mock-directory-server-a",
  "authentication_value": "LVJhdmVsaW4gVGVzdCBWYWx1ZS0=",
  "authentication_status": "successful",
  "eci": "05",
  "acs_challenge_mandated": "N",
  "authentication_challenge_type": "static",
  "acs_challenge_url": "https://acs.cardissuer.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
`pan_token_id`	string	The ID for the card token 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_accept_header`	string	The HTTP accept headers from the browser (`browser` device only)
`browser_ip_address`	string	The browser's IP address (`browser` device only)
`browser_javascript_enabled`	bool	If javascript is enabled on the browser (`browser` device only)
`browser_java_enabled`	bool	If java is enabled on the browser (`browser` device only)
`browser_color_depth`	string	The bit depth of the browser's color palette for displaying images (`browser` device only)
`browser_screen_height`	string	Total height of the device screen (not browser window) in pixels (`browser` device only)
`browser_screen_width`	string	Total width of the device screen (not browser window) in pixels (`browser` device only)
`browser_tz`	string	Timezone offset in minutes between UTC and the browser local time (`browser` device only)
`browser_user_agent`	string	Exact content of the browser HTTP user-agent header (`browser` device only)
`sdk_transaction_id`	uuid	Unique identifier for a mobile SDK transaction (`mobile` device only)
`sdk_application_id`	uuid	Unique identifier created upon installation of the mobile SDK (`mobile` device only)
`sdk_encryption_data`	uuid	Device data encrypted by the SDK (`mobile` device only)
`sdk_ephemeral_public_key`	object	Uublic key component of the ephemeral key pair generated by the SDK (`mobile` device only)
`sdk_max_timeout`	string	Maximum amount of time (in minutes) for all exchanges (`mobile` device only)
`sdk_reference_number`	string	Identifies the version of the 3DS SDK
`sdk_render_options`	SDK Render Options	The SDK UI types that the device supports (`mobile` 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	The UI types the device supports for displaying challenge UIs

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 is unavailable

Authentication Object

Attribute	Type	Description
`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 EMVCoD
`ds_reference_number`	string	A unique identifier assigned to the ACS by EMVCo
`pan_token_id`	string	The ID for the card token used in the 3DS transaction
`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	Character code for the authentication status
`authentication_status_reason`	string	Additional information about the authentication status if necessary. See Authentication Status Reason
`eci`	string	Electronic Commerce Indicator
`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_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
`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
`N`	Challenge is not mandated

Authentication Status

Value	Description
`successful`	3DS authentication was successful
`attempted`	3DS authentication was attempted but not possible. Successful authentication granted by card brand on issuer's behalf
`failed`	Authentication failed, stop the transaction
`unavailable`	Authentication could not be performed. Try to proceed without the authentication value
`challenge`	A challenge is required, use the SDK to perform the Challenge
`decoupled_challenge`	A challenge will be performed by the issuer. Get the Challenge Result to learn the outcome
`rejected`	The issuer rejected the authentication attempt
`informational`	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
`unsupported-device`	Unsupported device
`too-many-authentication-attempts`	Exceeded authentication frequency limit
`card-expired`	Expired card
`invalid-card-number`	Invalid card number
`invalid-transaction`	Invalid transaction
`no-card-record`	No card record
`security-failure`	Security failure
`stolen-card`	Stolen card
`suspected-fraud`	Suspected fraud
`transaction-not-permitted`	Transaction not permitted to cardholder
`cardholder-not-enrolled`	Cardholder not enrolled in service
`timeout-at-acs`	Transaction timed out at the ACS
`low-confidence`	Low confidence
`medium-confidence`	Medium confidence
`high-confidence`	High confidence
`very-high-confidence`	Very high confindence
`max-challenges-exceeded`	Exceeded ACS maximum challenges limit
`non-payment-transaction-not-supported`	Non-payment transaction is not supported
`3ri-not-supported`	3RI (requestor initiated) transaction not supported
`acs-technical-issue`	ACS technical issue
`decoupled-authentication-required`	Decoupled authentication is required but not requested
`decoupled-authentication-timeout`	Deocupled authentication max expiration time exceeded
`insufficient-decoupled-authentication-time`	Insufficient time provided for decoupled authentication
`authentication-attempted-but-not-performed`	Authentication attempted but not performed by the cardholder

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	Description
`cardholder-canceled`	Cardholder selected 'Cancel' on the challenge
`requestor-canceled`	3DS requestor cancelled authentication
`transaction-abandoned`	Transaction was abandoned
`acs-timeout`	Transaction timed out at ACS
`acs-timeout-request-not-received`	Transaction timed out at ACS - Challenge request not received
`error`	Transaction error
`unknown`	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.

Card Number	3DS Scenario
`4200000000000002`	Successful Frictionless Authentication
`4200000000000003`	Authentication Attempted
`4200000000000005`	Authentication Failed
`4200000000000006`	Authentication Unavailable
`4200000000000007`	Authentication Rejected
`4200000000000004`	Successful Challenge Authentication
`4200000000000014`	Successful Challenge Authentication - Method not Required
`4200000000000015`	Successful Mandated Challenge Authentication
`4200000000000016`	Successful Out-of-Band Challenge Authentication
`4200000000000008`	Attempted Challenge Authentication
`4200000000000009`	Failed Challenge Authentication
`4200000000000017`	Failed Out of Band Challenge Authentication
`4200000000000010`	Unavailable Challenge Authentication
`4200000000000011`	Rejected Challenge Authentication
`4200000000000012`	3DS Directory Server Error
`4200000000000013`	Internal 3DS Server Error

Get a Session​

Permissions​

Request​

URI Parameters​

Response​

Authenticate Session​

Permissions​

Request​

Request Parameters​

Authentication Categories​

Authentication Types​

Challenge Preferences​

Purchase Info Object​

Purchase Transaction Types​

Merchant Info Object​

Merchant Risk Info Object​

Merchant Risk Delivery Time Frames​

Merchant Risk Shipping Methods​

Requestor Info Object​

Instructions for Different Card Brands​

Cardholder Info Object​

Cardholder Account Types​

Cardholder Account Info Object​

Cardholder Account Age​

Cardholder Account Last Changed​

Cardholder Account Password Last Changed​

Cardholder Payment Account Created​

Cardholder Shipping Address First Used​

Cardholder Authentication Info Object​

Cardholder Authentication Methods​

Cardholder Prior Authentication Info Object​

Cardholder Prior Authentication Methods​

Cardholder Phone Number Object​

Cardholder Address Object​

Response​

Get Challenge Result​

Permissions​

Request​

URI Parameters​

Response​

Session Object​

Device Info Object​

SDK Render Options Object​

Version Object​

Method Object​

Method Completion Indicator​

Authentication Object​

ACS Challenge Mandated​

Authentication Status​

Authentication Status Reason​

Authentication Challenge Type​

Challenge Cancel Reason​

Whitelist Status​

Whitelist Status Source​

Message Extension Object​

Test Cards​

Get a Session

Permissions

Request

URI Parameters

Response

Authenticate Session

Permissions

Request

Request Parameters

Authentication Categories

Authentication Types

Challenge Preferences

Purchase Info Object

Purchase Transaction Types

Merchant Info Object

Merchant Risk Info Object

Merchant Risk Delivery Time Frames

Merchant Risk Shipping Methods

Requestor Info Object

Instructions for Different Card Brands

Cardholder Info Object

Cardholder Account Types

Cardholder Account Info Object

Cardholder Account Age

Cardholder Account Last Changed

Cardholder Account Password Last Changed

Cardholder Payment Account Created

Cardholder Shipping Address First Used

Cardholder Authentication Info Object

Cardholder Authentication Methods

Cardholder Prior Authentication Info Object

Cardholder Prior Authentication Methods

Cardholder Phone Number Object

Cardholder Address Object

Response

Get Challenge Result

Permissions

Request

URI Parameters

Response

Session Object

Device Info Object

SDK Render Options Object

Version Object

Method Object

Method Completion Indicator

Authentication Object

ACS Challenge Mandated

Authentication Status

Authentication Status Reason

Authentication Challenge Type

Challenge Cancel Reason

Whitelist Status

Whitelist Status Source

Message Extension Object

Test Cards