# Create a 3D Secure Session

Create a 3D Secure Session to authenticate a buyer before you charge their card.

Create the session from a payment_instrument_id for the redirect flow or standalone Finix.ThreeDSecure, or from a token_id for the ThreeDSecure payment form option. For redirect flows, pass the session ID after state reaches SUCCEEDED. With Finix.js, pass it when the succeeded callback fires, even if the session resource still reads PENDING.

Endpoint: POST /3d_secure_sessions
Security: BasicAuth

## Header parameters:

  - `Finix-Version` (string)
    Specify the API version of your request. For more details, see Versioning.
    Example: "2022-02-01"

  - `Content-Type` (string)
    The data type being sent in the request body must be application/json.
    Example: "application/json"

## Response 201 fields (application/json):

  - `id` (string)
    The ID of the 3D Secure Session.
    Example: "3d_secure_session_f3fG3Zj8K958MTP5vpXAXX"

  - `created_at` (string)
    Timestamp of when the object was created.

  - `updated_at` (string)
    Timestamp of when the object was last updated.

  - `3d_secure_authentication` (object,null)
    The authentication values the card network returns. Pass this object, or the ID of this 3D Secure Session, when you create the [Transfer](/api/transfers) or [Authorization](/api/authorizations).

This field is null until the authentication process finishes. It stays null when state is FAILED.

  - `3d_secure_authentication.cardholder_authentication` (string)
    Provides evidence that the cardholder authentication occurred or that the [Merchant](/api/merchants) attempted authentication. This is unique for each authentication transaction and is sometimes referred to as the cardholder authentication verification value (CAVV).

  - `3d_secure_authentication.electronic_commerce_indicator` (string)
    The result of the authentication, and the value that determines who carries chargeback liability for fraud.

- AUTHENTICATED: The issuer authenticated the [buyer](/api/identities). Liability for fraud chargebacks shifts to the issuer.
- ATTEMPTED: The issuer could not authenticate the buyer, so the card network authenticated on the issuer's behalf. Liability for fraud chargebacks shifts to the issuer.
- NON_AUTHENTICATED: The buyer was not authenticated. Liability for fraud chargebacks stays with the seller.
    Enum: "AUTHENTICATED", "ATTEMPTED", "NON_AUTHENTICATED"

  - `3d_secure_authentication.transaction_id` (string)
    The ID the issuer assigns to the 3D Secure transaction.

  - `3d_secure_authentication_session_id` (string,null)
    The ID of the authentication session with the 3D Secure vendor. This is not the ID of the 3D Secure Session resource.
    Example: "tds_visa_0367b8b7ebd8"

  - `3d_secure_authentication_url` (string,null)
    The hosted URL where the [buyer](/api/identities) completes authentication. Redirect the buyer to this URL to run the redirect flow. This field is null when you create the session from a token_id and complete the authentication with Finix.js.

  - `3d_secure_version` (string,null)
    The version of the 3D Secure protocol used for the authentication.
    Example: "2.2.0"

  - `amount` (integer)
    The amount that was authenticated, in the smallest unit of the currency (for example, 1000 = $10.00).
    Example: 1000

  - `authentication_type` (string,null)
    How the buyer was authenticated. This field is populated when state is SUCCEEDED.

- FRICTIONLESS: The issuer authenticated the buyer from the data in the request, without presenting a challenge.
- CHALLENGE: The issuer presented the buyer with a challenge, such as a one-time passcode.
- ATTEMPT: The card network authenticated on the issuer's behalf.
    Enum: null, "FRICTIONLESS", "CHALLENGE", "ATTEMPT"

  - `currency` (string)
    ISO 4217 3-letter currency code.
    Enum: "CAD", "USD"

  - `failure_code` (string,null)
    The code for why the authentication process could not finish. This field is populated when state is FAILED.
    Enum: null, "AUTHENTICATION_FAILED", "AUTHENTICATION_TIMED_OUT", "CARD_NOT_ENROLLED", "CHALLENGE_REQUIRED", "DIRECTORY_SERVER_UNAVAILABLE", "ISSUER_SERVER_UNAVAILABLE", "PROTOCOL_ERROR", "SUSPECTED_FRAUD", "TRANSACTION_CANCELLED_BY_CARDHOLDER", "TRANSACTION_NOT_PERMITTED", "TRANSIENT_SYSTEM_FAILURE", "UNSUPPORTED_3D_SECURE_VERSION"

  - `failure_message` (string,null)
    A human-readable description of why the authentication process could not finish.

  - `merchant_id` (string)
    The ID of the [Merchant](/api/merchants) the payment processes under.
    Example: "MUmUNeW5N9Yw8RkLhLcGghy4"

  - `payment_instrument_id` (string,null)
    The ID of the [Payment Instrument](/api/payment-instruments) that was authenticated. This field is null when you create the session from a token_id.
    Example: "PI6iQcTtJNCS8GZAVKYi5Ueb"

  - `redirect_url` (string,null)
    The URL the buyer returns to after they finish authentication. This field is null when you create the session from a token_id.

  - `state` (string)
    The state of the authentication process. A state of SUCCEEDED means the process finished. It does not mean the buyer was authenticated: a session where the issuer declined to authenticate the buyer also ends in SUCCEEDED. Read 3d_secure_authentication.electronic_commerce_indicator for the authentication result.

- PENDING: The authentication process has not finished.
- SUCCEEDED: The authentication process finished and returned a result.
- FAILED: The authentication process could not finish. See failure_code and failure_message.
    Enum: "PENDING", "SUCCEEDED", "FAILED"

  - `tags` (object,null)
    Include up to 50 key: value pairs to annotate requests with custom metadata.
- Maximum character length for individual keys is 40.
- Maximum character length for individual values is 500.
(For example, order_number: 25, item_type: produce, department: sales)

## Response 400 fields (application/json):

  - `total` (integer, required)
    Total number of errors returned.

  - `_embedded` (object, required)
    Container for embedded error objects.

  - `_embedded.errors` (array)
    List of individual error objects.

  - `_embedded.errors.code` (string)
    The error code. The UNKNOWN error code is returned for a 401 Unauthorized or 403 Forbidden request.

  - `_embedded.errors.logref` (string)
    A log reference identifier for the error, useful for debugging and support purposes.

  - `_embedded.errors.message` (string)
    A human-friendly error message.

  - `_embedded.errors._links` (object)
    Links related to this error.

  - `_embedded.errors._links.self` (object)
    Link to the resource related to the error.

  - `_embedded.errors._links.self.href` (string)
    URL of the related resource.

## Response 401 fields (application/json):

  - `total` (integer, required)
    Total number of errors returned.

  - `_embedded` (object, required)
    Container for embedded error objects.

  - `_embedded.errors` (array)
    List of individual error objects.

  - `_embedded.errors.code` (string)
    The error code. The UNKNOWN error code is returned for a 401 Unauthorized or 403 Forbidden request.

  - `_embedded.errors.logref` (string)
    A log reference identifier for the error, useful for debugging and support purposes.

  - `_embedded.errors.message` (string)
    A human-friendly error message.

  - `_embedded.errors._links` (object)
    Links related to this error.

  - `_embedded.errors._links.self` (object)
    Link to the resource related to the error.

  - `_embedded.errors._links.self.href` (string)
    URL of the related resource.

## Response 403 fields (application/json):

  - `total` (integer, required)
    Total number of errors returned.

  - `_embedded` (object, required)
    Container for embedded error objects.

  - `_embedded.errors` (array)
    List of individual error objects.

  - `_embedded.errors.code` (string)
    The error code. The UNKNOWN error code is returned for a 401 Unauthorized or 403 Forbidden request.

  - `_embedded.errors.logref` (string)
    A log reference identifier for the error, useful for debugging and support purposes.

  - `_embedded.errors.message` (string)
    A human-friendly error message.

  - `_embedded.errors._links` (object)
    Links related to this error.

  - `_embedded.errors._links.self` (object)
    Link to the resource related to the error.

  - `_embedded.errors._links.self.href` (string)
    URL of the related resource.

## Response 404 fields (application/json):

  - `total` (integer, required)
    Total number of errors returned.

  - `_embedded` (object, required)
    Container for embedded error objects.

  - `_embedded.errors` (array)
    List of individual error objects.

  - `_embedded.errors.code` (string)
    The error code. The UNKNOWN error code is returned for a 401 Unauthorized or 403 Forbidden request.

  - `_embedded.errors.logref` (string)
    A log reference identifier for the error, useful for debugging and support purposes.

  - `_embedded.errors.message` (string)
    A human-friendly error message.

  - `_embedded.errors._links` (object)
    Links related to this error.

  - `_embedded.errors._links.self` (object)
    Link to the resource related to the error.

  - `_embedded.errors._links.self.href` (string)
    URL of the related resource.

## Response 406 fields (application/json):

  - `total` (integer, required)
    Total number of errors returned.

  - `_embedded` (object, required)
    Container for embedded error objects.

  - `_embedded.errors` (array)
    List of individual error objects.

  - `_embedded.errors.code` (string)
    The error code. The UNKNOWN error code is returned for a 401 Unauthorized or 403 Forbidden request.

  - `_embedded.errors.logref` (string)
    A log reference identifier for the error, useful for debugging and support purposes.

  - `_embedded.errors.message` (string)
    A human-friendly error message.

  - `_embedded.errors._links` (object)
    Links related to this error.

  - `_embedded.errors._links.self` (object)
    Link to the resource related to the error.

  - `_embedded.errors._links.self.href` (string)
    URL of the related resource.