send_auth_request Method

Sends the authentication request to the directory server.

Syntax

def send_auth_request() -> None: ...

Remarks

send_auth_request begins the 3-D Secure transaction flow by sending an authentication request to the directory_server_url.

After calling this method, check transaction_status to determine if the cardholder is authenticated (frictionless flow) or further cardholder interaction is required to complete the authentication (challenge flow).

Prior to calling send_auth_request, data must to be collected to facilitate fraud checks by the ACS. The following properties are applicable for both app-based and browser-based flows:

• acquirer_bin (required)
• acquirer_merchant_id (required)
• cardholder_name (required)
• card_number (required)
• directory_server_url (required)
• merchant_category_code (required)
• merchant_country_code (required)
• merchant_name (required)
• purchase_amount (required)
• purchase_date (required)
• requestor_id (required)
• requestor_name (required)
• requestor_url (required)
• results_url (required)
• account_type
• authentication_indicator
• BillingAddress*
• cardholder_email
• cardholder_home_phone
• cardholder_mobile_phone
• cardholder_work_phone
• DecoupledMaxTimeout
• DecoupledRequestIndicator
• device_channel
• message_category
• purchase_currency
• purchase_exponent
• ServerOperatorId
• server_transaction_id
• ShippingAddress*
• ThreeRIIndicator

App-Based Flow

In the app-based flow, device specific information is prepared by the 3DS SDK on the customer's device. This is transmitted to the 3DS Server class via a secure channel, the specifics of which are outside the scope of the classs. Set client_auth_request to this data prepared by the 3DS SDK.

Browser-Based Flow

Before calling this method, first check the cached card-range data to determine if a card_range_method_url has been set by the ACS. Card range data may be retrieved by calling request_card_ranges.

If no card_range_method_url is present for the given card, set MethodCompletionIndicator to U.

If a card_range_method_url has been specified by the ACS for the card number, the URL must be loaded in the cardholder's browser to allow the ACS to collect additional browser information for risk-based decision making. See the get_method_data for further details.

Once the method URL invocation is complete, the authentication request may be sent. If the method URL invocation failed, set MethodCompletionIndicator to N before calling send_auth_request.

The following additional properties are applicable in browser-based flow:

• notification_url (required)
• browser_accept_header (required in 2.1.0 and 2.2.0)
• browser_language (required in 2.1.0 and 2.2.0)
• browser_screen_height (required in 2.1.0, required in 2.2.0 if BrowserJavaScriptEnabled is true)
• browser_screen_width (required in 2.1.0, required in 2.2.0 if BrowserJavaScriptEnabled is true)
• browser_time_zone (required in 2.1.0, required in 2.2.0 if BrowserJavaScriptEnabled is true)
• browser_user_agent (required in 2.1.0 and 2.2.0)
• browser_ip_address (conditional in 2.1.0 and 2.2.0)
• browser_java_enabled_val (required in 2.1.0, required in 2.2.0 if BrowserJavaScriptEnabled is true)
• browser_java_script_enabled_val (not valid in 2.1.0, required in 2.2.0)
• browser_screen_color_depth (required in 2.1.0, required in 2.2.0 if BrowserJavaScriptEnabled is true)

Response Handling

After calling this method the transaction_status property holds the result. Possible values are:

If the transaction is authenticated (Y or A), no further steps are required. The flow is considered frictionless and the 3-D Secure processing is complete. If processing a payment, the authentication_value and authentication_eci values can be included as proof of 3-D Secure authentication.

If the transaction requires a cardholder challenge (C or D), further steps are required.

If the transaction is not authenticated, TransactionStatusReason may contain details about the reason.

The following properties are applicable after calling this method:

• authentication_eci
• authentication_value
• transaction_status
• TransactionStatusReason
• CardholderInformation
• acsurl (if challenge required)
• ACSChallengeMandatedIndicator (if challenge required)
• AuthenticationType (if challenge required)
• DecoupledConfirmationIndicator

Response Handling - App-Based Flow

After calling this method, client_auth_response is populated with data to be transmitted back to the 3DS SDK. If a challenge is required, the client_auth_response data is used by the 3DS SDK to start when initiating the challenge process.

The 3DS Server is responsible for indicating to the 3DS SDK the results of the send_auth_request process, and whether or not a challenge is required. Exactly how this is done is outside the scope of the classs themselves. The response to the 3DS SDK over the secure channel should include information on what to do next.

Note: The transaction_status is also populated in the 3DS Server class and may be inspected prior to transmitting client_auth_response back to the 3DS SDK.

Response Handling - Browser-Based Flow

If transaction_status is C, then additional steps are required to complete the authentication. The get_challenge_request method should be called next to obtain data to be sent to the acsurl in an authentication window in the customer's browser. Once authentication is complete, the ACS will post the results to the results_url value that was specified when calling send_auth_request.

See the get_challenge_request method for more details.

If transaction_status is D, then decoupled authentication has been accepted by the ACS. DecoupledConfirmationIndicator will have a value of Y as well. Authentication will happen outside of the 3-D Secure flow and, when complete, the ACS will post the results to the results_url that was specified when calling send_auth_request.

The DecoupledTimeRemaining value, which is calculated based on the DecoupledMaxTimeout value sent in the initial authentication request, can be checked to see the amount of time remaining before decoupled authentication must be completed. If the ACS does not post the results before this value runs out, it can be assumed that decoupled authentication was not successful.