The Client class is designed for use on mobile devices and facilitates 3-D Secure 2.0 authentication.
The Client class is a counterpart to the 3DS Server class. It is designed for use on mobile devices and supports operations that facilitate 3-D Secure 2.0 authentication in both frictionless and challenge flows.
Preparing the Authentication Request
To begin, device specific information must be collected and prepared for transmission to the directory server. This can be done by calling the add_device_param method. Consult the EMVCo 3-D Secure Specifications for more details about applicable device parameters for your particular operating system.
The get_auth_request method is used to obtain the request message to be send to the directory server. get_auth_request encrypts the device info and prepares all the data necessary to be sent by the 3DS Server class in the send_auth_request method.
After calling this method, the returned data must be transmitted via a separate secure channel to the server where 3DS Server is being used.
The following properties are required before calling the method:
|device_params||Contains device information parameters. Add parameters via add_device_param.|
|directory_server_cert||Used to encrypt the device parameters.|
|directory_server_id||Identifies the directory_server_cert within the directory server.|
|sdk_app_id||A UUID for the specific installation.|
|SDKReferenceNumber||An Id assigned by EMVCo to identify the vendor and software version.|
Calling this method returns required information used by 3DS Server to send the authentication request. Transmit the value returned by this method to the system where 3DS Server is used. The method used to transmit this value is outside the scope of the class.
Interaction With the 3DS Server Class
As mentioned above, the request to the Directory Server must be made by the 3DS Server class which resides on a server under control of the merchant. A web server is required even for app-based authentication both to send the authentication request and to be notified of authentication results later in the flow.
Sending the Authentication Request
The act of sending the authentication request takes place with the 3DS Server class.
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)
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.
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 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)
- 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 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 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.
Processing the Authentication Response
After the response to the authentication request is received from the 3DS Server class, call check_auth_response to verify and parse the response. See the 3DS Server's send_auth_request method for details about obtaining the response.
Before calling this method, acs_root_certs must be populated with the root certificates used by the ACS to sign the response. This method will validate the signature of the signed content if present.
After calling this method, inspect transaction_status to determine if the transaction requires a challenge. If transaction_status is C, a challenge is required and send_challenge_request should be called to proceed with the challenge flow. If transaction_status is D, decoupled authentication will take place outside of the 3-D Secure flow and the results will be posted to the 3DS Server.
If transaction_status is Y or A, the transaction is complete.
If transaction_status is C, a challenge is required. The challenge takes place between the cardholder and the ACS. During this interaction the class will communicate directly with the ACS from the app where it is used to exchange information.
When the transaction_status is C after calling check_auth_response, a challenge to the cardholder is required. This method sends the challenge request and parses the response. The ACS may provide multiple challenges to the cardholder during this process. As a result this method may need to be called multiple times throughout the authentication process.
After this method is called, check challenge_complete to determine if the challenge process is complete. If it is complete (True), check transaction_status to determine the outcome. If challenge_complete is False, additional challenge interaction is required.
The first time this method is called, information about the required challenge is obtained from the ACS. The ACS connection information is automatically set when check_auth_response is called; there is no need to specify any ACS connection information.
All required properties for the first call to this method are automatically set after check_auth_response is called. If the transaction has been canceled, set challenge_cancellation_indicator to inform the ACS.
After calling this method, the ACS will respond with details about the challenge to be presented to the cardholder. The acsui_type property indicates the way the ACS will interact with the cardholder. The challenge_complete property will be False after the first call to this method since the challenge interaction is not yet complete.
The following properties are applicable when acsui_type is Text (01), Single-Select (02), or Multi-Select (03):
Use the values in the above properties to populate values in the native UI in the app. The UI must follow the guidelines defined in the EMVCo 3-D Secure specification.
The following properties are applicable when acsui_type is Out-of-Band (04):
Use the values in the above properties to populate values in the native UI in the app. The UI must follow the guidelines defined in the EMVCo 3-D Secure specification.
The following properties are applicable when acsui_type is HTML (05):
In the case of an HTML interaction, the app should create a webview and populate this with the HTML in acshtml.
As per the EMVCo 3-D Secure specification, the HTML UI is presented to the cardholder via a web view which remains in control of the app. The app must intercept any remote URL requests made from within the web view, and instead handle them within the app. Preventing the cardholder from making requests in the web view to another server is critical to the security of the environment. According to the EMVCo specification, intercepting these requests has two effects:
- Prevents malicious HTML from redirecting a user to a phishing site.
- Conceptually puts the web view form under the control of the ACS, rather than the app.
- The web view element is not utilized as a browser, but as a UI element whose content is provided by the ACS.
The second time this method is called, the purpose is to provide a response to the ACS. At this point the customer should have responded to the challenge provided by the ACS in the response to the first call. If the transaction has been canceled, set challenge_cancellation_indicator to inform the ACS. The following properties are applicable when calling this method the second time:
mobile: **** **** 329 email: s******k**@g***.comThe value to provide in challenge_data_entry is the challenge_select_info_name, i.e. mobile.
When acsui_type is Multi-Select (03), set challenge_data_entry to a comma-separated list of names of the selected options. For instance if challenge_select_info contains elements with names like chicago_illinois, st_louis_missouri, and portland_oregon, and the user chose two options, the value specified in challenge_data_entry would be chicago_illinois,portland_oregon.
Completing the Challenge
After calling send_challenge_request a second time with the cardholder's responses, the ACS may require additional challenges. Check the challenge_complete property to determine if the challenge is complete. If False, more challenges are required by the ACS and the same process of displaying the challenge info, collecting the response, and submitting it to the ACS should be performed again.
Note: As part of the challenge completion the ACS also notifies the 3DS Server of the results. This is done by posting the results to the URL defined by the results_url property of the 3DS Server class.
Logging in the component is handled through the on_log event. This will fire anytime a message is built or a response is parsed, including error messages.
When the on_log event is fired, the message in question is made available via the Message event parameter. Properties such as EphemeralKey and DeviceParams are also available when they are gathered by the Client. The other event arguments are LogType and LogLevel:
The LogType parameter indicates the type of the log entry. Possible values are:
It is recommended to output all messages raised in this event to a file for record keeping purposes, or for later debugging issues that may have come up.
The Server and Client components also have on_data_packet_in and on_data_packet_out events that fire anytime a data packet is received or sent, respectively. The entire data packet is then accessible in the DataPacket event parameter. For encrypted packets, this would contain the full encrypted data. This parameter may be inspected for advanced troubleshooting.
The following is the full list of the properties of the class with short descriptions. Click on the links for further details.
|acshtml||HTML provided by the ACS.|
|acshtml_refresh||ACS HTML refresh.|
|acs_root_cert_count||The number of records in the ACSRootCert arrays.|
|acs_root_cert_encoded||The certificate (PEM/base64 encoded).|
|acs_root_cert_store||The name of the certificate store for the client certificate.|
|acs_root_cert_store_password||If the certificate store is of a type that requires a password, this property is used to specify that password in order to open the certificate store.|
|acs_root_cert_store_type||The type of certificate store for this certificate.|
|acs_root_cert_subject||The subject of the certificate used for client authentication.|
|acsui_type||UI type rendered by the 3DS SDK.|
|challenge_additional_information||Challenge additional information text.|
|challenge_cancellation_indicator||Challenge Cancellation Indicator.|
|challenge_complete||Whether or not the challenge cycle is complete.|
|challenge_data_entry||Cardholder entered data.|
|challenge_info_header||Challenge information screen header.|
|challenge_info_label||Challenge information label.|
|challenge_info_text||Challenge information text.|
|challenge_info_text_indicator||Challenge information text indicator.|
|challenge_select_info_count||The number of records in the ChallengeSelectInfo arrays.|
|challenge_select_info_name||The name of the selection option.|
|challenge_select_info_value||The value of the selection option.|
|data_packet_out||Contains the data packet sent to the server.|
|device_param_count||The number of records in the DeviceParam arrays.|
|device_param_category||The category of the parameter.|
|device_param_field_name||The name of the parameter.|
|device_param_value||The value of the parameter.|
|device_param_value_type||The type of the value.|
|directory_server_cert_encoded||The certificate (PEM/base64 encoded).|
|directory_server_cert_store||The name of the certificate store for the client certificate.|
|directory_server_cert_store_password||If the certificate store is of a type that requires a password, this property is used to specify that password in order to open the certificate store.|
|directory_server_cert_store_type||The type of certificate store for this certificate.|
|directory_server_cert_subject||The subject of the certificate used for client authentication.|
|directory_server_id||Value of the Registered Application Provider Identifier (RID) unique to the payment system.|
|error_packet||The error packet.|
|expandable_information_label||Expandable information label.|
|expandable_information_text||Expandable information text.|
|extension_count||The number of records in the Extension arrays.|
|extension_critical||Whether the extension is critical.|
|extension_data||The extension data as JSON.|
|extension_id||The id of the specified extension.|
|extension_name||The extension name.|
|issuer_image_extra_high||Issuer image URL (extra high density).|
|issuer_image_high||Issuer image URL (high density).|
|issuer_image_medium||Issuer image URL (medium density).|
|oob_continuation_indicator||OOB continuation indicator.|
|oob_continue_label||OOB continuation label.|
|payment_system_image_extra_high||Payment system image URL (extra high density).|
|payment_system_image_high||Payment system image URL (high density).|
|payment_system_image_medium||Payment system image URL (medium density).|
|proxy_auth_scheme||This property is used to tell the class which type of authorization to perform when connecting to the proxy.|
|proxy_auto_detect||This property tells the class whether or not to automatically detect and use proxy system settings, if available.|
|proxy_password||This property contains a password if authentication is to be used for the proxy.|
|proxy_port||This property contains the TCP port for the proxy Server (default 80).|
|proxy_server||If a proxy Server is given, then the HTTP request is sent to the proxy instead of the server otherwise specified.|
|proxy_ssl||This property determines when to use SSL for the connection to the proxy.|
|proxy_user||This property contains a user name, if authentication is to be used for the proxy.|
|resend_information_label||Label for UI button allowing users to request that authentication information be resent.|
|sdk_app_id||The unique SDK App Id.|
|sdk_transaction_id||SDK Transaction ID.|
|ssl_accept_server_cert_encoded||The certificate (PEM/base64 encoded).|
|ssl_cert_encoded||The certificate (PEM/base64 encoded).|
|ssl_cert_store||The name of the certificate store for the client certificate.|
|ssl_cert_store_password||If the certificate store is of a type that requires a password, this property is used to specify that password in order to open the certificate store.|
|ssl_cert_store_type||The type of certificate store for this certificate.|
|ssl_cert_subject||The subject of the certificate used for client authentication.|
|ssl_server_cert_encoded||The certificate (PEM/base64 encoded).|
|submit_authentication_label||Label for UI button users select to submit authentication.|
|timeout||A timeout for the class.|
|transaction_status||The transaction status from the last parsed message (ARes, RReq, or CRes).|
|whitelisting_data_entry||Whitelisting Data Entry.|
|whitelisting_information_text||Whitelisting information text.|
|why_information_label||Label for why information section.|
|why_information_text||Text to explain the authentication task to the user.|
The following is the full list of the methods of the class with short descriptions. Click on the links for further details.
|add_device_param||Adds a device parameter to the collection.|
|add_extension||Adds an extension to the collection.|
|add_request_field||Adds a field to the data in the request.|
|check_auth_response||Checks the received packet.|
|config||Sets or retrieves a configuration setting.|
|get_auth_request||Prepares data to be sent by the 3DS Server.|
|interrupt||Interrupts the current action.|
|reset||Clears all properties to their default values.|
|reset_transaction_info||Resets transaction specific information.|
|send_challenge_request||Builds and sends the Challenge Request in an app-based challenge flow.|
The following is the full list of the events fired by the class with short descriptions. Click on the links for further details.
|on_data_packet_in||Fired when receiving a data packet from the server.|
|on_data_packet_out||Fired when sending a data packet to the server.|
|on_error||Information about errors during data delivery.|
|on_log||Fires once for each log message.|
|on_ssl_server_authentication||Fired after the server presents its certificate to the client.|
|on_ssl_status||Shows the progress of the secure connection.|
The following is a list of configuration settings for the class with short descriptions. Click on the links for further details.
|AcceptAnyACSCert||Whether to accept any ACS certificate during signature validation.|
|ACSRenderingInterface||Challenge interface type presented to cardholder.|
|ACSRenderingUITemplate||Challenge type presented to cardholder.|
|ACSSignedContent||String value of the JWS object of the ARes message created by the ACS.|
|ACSTransactionId||Unique transaction identifier assigned by the ACS.|
|ACSURL||ACS URL to which the challenge request is sent.|
|ChallengeResponse||Challenge Response (CRes).|
|ChallengeTimeRemaining||Amount of time left to complete challenge.|
|DeviceRenderingInterface||SDK Interface Device Rendering Types supported.|
|DeviceRenderingUIType||SDK UI Types supported.|
|DSTransactionId||Directory server transaction ID.|
|ErrorCode||Code from the last error message.|
|ErrorDescription||Description from the last error message.|
|ErrorDetail||Additional details from the last error message.|
|IncomingExtensionCount||The number of extensions received from the directory server.|
|IncomingExtensionCritical[Index]||Whether the extension is critical.|
|IncomingExtensionData[Index]||The extension data as JSON.|
|IncomingExtensionId[Index]||The id of the specified extension.|
|IncomingExtensionName[Index]||The extension name.|
|IncomingRawExtensions||The full JSON formatted extension data received from the directory server.|
|LogLevel||Level of logging enabled.|
|MaskSensitive||Whether to mask sensitive data in the Log event.|
|MerchantAppURL||3DS Requestor App URL.|
|MessageType||Type of message that is passed.|
|OOBAppLabel||OOB app label.|
|OOBAppURL||OOB app URL.|
|OutgoingRawExtensions||The full JSON formatted extension data sent to the directory server.|
|ProtocolVersion||Protocol version identifier.|
|ResendChallengeInfo||Resend challenge information code.|
|SDKEphemeralPrivateKey||Private key class of the ephemeral key pair generated by the Client.|
|SDKEphemeralPublicKey||Public key class of the ephemeral key pair generated by the Client.|
|SDKMaxTimeout||SDK Maximum Timeout.|
|SDKReferenceNumber||Assigned SDK reference number.|
|ServerTransactionId||Unique transaction identifier assigned by the 3DS Server.|
|TransactionStatusReason||Reason for value of TransactionStatus.|
|UseAESGCM||Whether or not to use AESGCM as the encryption algorithm.|
|XChildCount||The number of child elements of the current element.|
|XChildName[i]||The name of the child element.|
|XChildXText[i]||The inner text of the child element.|
|XElement||The name of the current element.|
|XParent||The parent of the current element.|
|XPath||Provides a way to point to a specific element in the returned XML or JSON response.|
|XSubTree||A snapshot of the current element in the document.|
|XText||The text of the current element.|
|LogSSLPackets||Controls whether SSL packets are logged when using the internal security API.|
|OpenSSLCADir||The path to a directory containing CA certificates.|
|OpenSSLCAFile||Name of the file containing the list of CA's trusted by your application.|
|OpenSSLCipherList||A string that controls the ciphers to be used by SSL.|
|OpenSSLPrngSeedData||The data to seed the pseudo random number generator (PRNG).|
|ReuseSSLSession||Determines if the SSL session is reused.|
|SSLCACertFilePaths||The paths to CA certificate files on Unix/Linux.|
|SSLCACerts||A newline separated list of CA certificate to use during SSL client authentication.|
|SSLCheckCRL||Whether to check the Certificate Revocation List for the server certificate.|
|SSLCipherStrength||The minimum cipher strength used for bulk encryption.|
|SSLEnabledCipherSuites||The cipher suite to be used in an SSL negotiation.|
|SSLEnabledProtocols||Used to enable/disable the supported security protocols.|
|SSLEnableRenegotiation||Whether the renegotiation_info SSL extension is supported.|
|SSLIncludeCertChain||Whether the entire certificate chain is included in the SSLServerAuthentication event.|
|SSLProvider||The name of the security provider to use.|
|SSLSecurityFlags||Flags that control certificate verification.|
|TLS12SignatureAlgorithms||Defines the allowed TLS 1.2 signature algorithms when UseInternalSecurityAPI is True.|
|TLS12SupportedGroups||The supported groups for ECC.|
|TLS13KeyShareGroups||The groups for which to pregenerate key shares.|
|TLS13SignatureAlgorithms||The allowed certificate signature algorithms.|
|TLS13SupportedGroups||The supported groups for (EC)DHE key exchange.|