Sends the authentication request to the directory server.
def send_auth_request() -> None: ...
on_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 on_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)
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.
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 on_send_auth_request.
The following additional properties are applicable in browser-based flow:
- notification_url (required)
- browser_accept_header (required)
- browser_language (required)
- browser_screen_height (required)
- browser_screen_width (required)
- browser_time_zone (required)
- browser_user_agent (required)
After calling this method the transaction_status property holds the result. Possible values are:
|C||Cardholder challenge required|
|A||Not authenticated, but a proof of authentication attempt was generated in authentication_value|
|U||Not authenticated due to technical or other issue|
|R||Not authenticated because the issuer is rejecting authentication|
|D||Challenge required; decoupled authentication confirmed|
|I||Informational only; 3DS Requestor challenge preference acknowledged|
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:
- acsurl (if challenge required)
- ACSChallengeMandatedIndicator (if challenge required)
- AuthenticationType (if challenge required)
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 on_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.
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 on_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 on_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.