FIfinix
3D Secure Sessions

Create a 3D Secure Session

Changed on

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.

post/3d_secure_sessions

Request

Headers

Finix-Versionstring
Example:2022-02-01

Specify the API version of your request. For more details, see Versioning.

Content-Typestring
Example:application/json

The data type being sent in the request body must be application/json.

Request body

OR

Example request

{
  "amount": 92169,
  "merchant_id": "MUmfEGv5bMpSJ9k5TFRUjkmm",
  "payment_instrument_id": "PI6iQcTtJNCS8GZAVKYi5Ueb",
  "redirect_url": "https://example.com/3d-secure/return"
}

Response

A single 3D Secure Session object.

idstring

The ID of the 3D Secure Session.

created_atstring date-time

Timestamp of when the object was created.

updated_atstring date-time

Timestamp of when the object was last updated.

3d_secure_authentication_session_idstring nullable

The ID of the authentication session with the 3D Secure vendor. This is not the ID of the 3D Secure Session resource.

3d_secure_authentication_urlstring nullable

The hosted URL where the buyer 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_versionstring nullable

The version of the 3D Secure protocol used for the authentication.

amountinteger

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

authentication_type'null' | 'FRICTIONLESS' | 'CHALLENGE' | 'ATTEMPT' nullable

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.
currency'CAD' | 'USD'

ISO 4217 3-letter currency code.

failure_code'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' nullable

The code for why the authentication process could not finish. This field is populated when state is FAILED.

failure_messagestring nullable

A human-readable description of why the authentication process could not finish.

merchant_idstring

The ID of the Merchant the payment processes under.

payment_instrument_idstring nullable

The ID of the Payment Instrument that was authenticated. This field is null when you create the session from a token_id.

redirect_urlstring nullable

The URL the buyer returns to after they finish authentication. This field is null when you create the session from a token_id.

state'PENDING' | 'SUCCEEDED' | 'FAILED'

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.
tagsTags nullable

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)

Example response

{
  "id": "3d_secure_session_f3fG3Zj8K958MTP5vpXAXX",
  "3d_secure_authentication_session_id": "tds_visa_0367b8b7ebd8",
  "3d_secure_version": "2.2.0",
  "amount": 1000,
  "merchant_id": "MUmUNeW5N9Yw8RkLhLcGghy4",
  "payment_instrument_id": "PI6iQcTtJNCS8GZAVKYi5Ueb"
}

Changes