/n software 3-D Secure V2 Python Edition

Questions / Feedback?

Client Class

Properties   Methods   Events   Configuration Settings   Errors  

The Client class is designed for use on mobile devices and facilitates 3-D Secure 2.0 authentication.


class ipworks3ds.Client


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.

See send_auth_request for details on sending the authentication request after transmitting the data to the 3DS Server.

Calling this method also populates sdk_transaction_id which uniquely identifies this transaction and must be used in subsequent calls relating to this transaction, such as send_challenge_request.

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.

It is expected that a secure channel can be established between the app using the Client class and the server where the 3DS Server class resides in order to transfer information freely.

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)
  • 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)
  • browser_language (required)
  • browser_screen_height (required)
  • browser_screen_width (required)
  • browser_time_zone (required)
  • browser_user_agent (required)
  • browser_ip_address
  • browser_java_enabled_val
  • browser_java_script_enabled_val
  • browser_screen_color_depth

Response Handling

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

Transaction Status Description
Y Authenticated successfully
C Cardholder challenge required
N Not authenticated
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:

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.

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.

Challenge Interaction

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.

send_challenge_request begins the challenge flow. send_challenge_request sends the Challenge Request to the ACS when a challenge is required.

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.

First Request

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 following are key points mentioned in the EMVCo 3-D Secure specification:
  • Navigation attempts from within the web view must be captured by the app and handled internally. This includes all requests including images, javascript files, css, etc.
  • The web view element is not utilized as a browser, but as a UI element whose content is provided by the ACS.
Please refer to the EMVCo 3-D Secure specification for more details and guidance on this topic. This information is not meant to replace the text in the EMVCo 3-D Secure specification.

Second Request

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:

When acsui_type is Text (01) or HTML (05), set challenge_data_entry to the data exactly as it was specified by the cardholder. Do not format or otherwise change the data.

When acsui_type is Single-Select (02), set challenge_data_entry to the name of the selected option. For instance the ACS may provide the user with a selection like:

mobile: **** **** 329
email: s******k**@g***.com
The 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.

When acsui_type is OOB (04), set oob_continuation_indicator to True to indicate the cardholder has pressed the button signaling their completing of the OOB process.

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.

If challenge_complete is True, the challenge interaction is complete and transaction_status can be inspected to determine whether the transaction was successful.

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 Notes

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:

  • "Info"
  • "RequestHeaders"
  • "ResponseHeaders"
  • "RequestBody"
  • "ResponseBody"
  • "ProxyRequest"
  • "ProxyResponse"
  • "FirewallRequest"
  • "FirewallResponse"
  • "AReq"
  • "ARes"
  • "CReq"
  • "CRes"
  • "RReq"
  • "RRes"
  • "PReq"
  • "PRes"
  • "Erro"
  • "EphemeralKey"
  • "DeviceParams"
The LogLevel configuration setting can be used to specify the detail of the logs raised through the on_log event. The LogLevel parameter in the event indicates the log level to which the current message belongs.

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.

Property List

The following is the full list of the properties of the class with short descriptions. Click on the links for further details.

acshtmlHTML provided by the ACS.
acshtml_refreshACS HTML refresh.
acs_root_cert_countThe number of records in the ACSRootCert arrays.
acs_root_cert_encodedThe certificate (PEM/base64 encoded).
acs_root_cert_storeThe name of the certificate store for the client certificate.
acs_root_cert_store_passwordIf 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_typeThe type of certificate store for this certificate.
acs_root_cert_subjectThe subject of the certificate used for client authentication.
acsui_typeUI type rendered by the 3DS SDK.
challenge_additional_informationChallenge additional information text.
challenge_cancellation_indicatorChallenge Cancellation Indicator.
challenge_completeWhether or not the challenge cycle is complete.
challenge_data_entryCardholder entered data.
challenge_info_headerChallenge information screen header.
challenge_info_labelChallenge information label.
challenge_info_textChallenge information text.
challenge_info_text_indicatorChallenge information text indicator.
challenge_select_info_countThe number of records in the ChallengeSelectInfo arrays.
challenge_select_info_nameThe name of the selection option.
challenge_select_info_valueThe value of the selection option.
data_packet_outContains the data packet sent to the server.
device_param_countThe number of records in the DeviceParam arrays.
device_param_categoryThe category of the parameter.
device_param_field_nameThe name of the parameter.
device_param_valueThe value of the parameter.
device_param_value_typeThe type of the value.
directory_server_cert_encodedThe certificate (PEM/base64 encoded).
directory_server_cert_storeThe name of the certificate store for the client certificate.
directory_server_cert_store_passwordIf 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_typeThe type of certificate store for this certificate.
directory_server_cert_subjectThe subject of the certificate used for client authentication.
directory_server_idValue of the Registered Application Provider Identifier (RID) unique to the payment system.
error_packetThe error packet.
expandable_information_labelExpandable information label.
expandable_information_textExpandable information text.
extension_countThe number of records in the Extension arrays.
extension_criticalWhether the extension is critical.
extension_dataThe extension data as JSON.
extension_idThe id of the specified extension.
extension_nameThe extension name.
issuer_image_extra_highIssuer image URL (extra high density).
issuer_image_highIssuer image URL (high density).
issuer_image_mediumIssuer image URL (medium density).
oob_continuation_indicatorOOB continuation indicator.
oob_continue_labelOOB continuation label.
payment_system_image_extra_highPayment system image URL (extra high density).
payment_system_image_highPayment system image URL (high density).
payment_system_image_mediumPayment system image URL (medium density).
proxy_auth_schemeThis property is used to tell the class which type of authorization to perform when connecting to the proxy.
proxy_auto_detectThis property tells the class whether or not to automatically detect and use proxy system settings, if available.
proxy_passwordThis property contains a password if authentication is to be used for the proxy.
proxy_portThis property contains the TCP port for the proxy Server (default 80).
proxy_serverIf a proxy Server is given, then the HTTP request is sent to the proxy instead of the server otherwise specified.
proxy_sslThis property determines when to use SSL for the connection to the proxy.
proxy_userThis property contains a user name, if authentication is to be used for the proxy.
resend_information_labelLabel for UI button allowing users to request that authentication information be resent.
sdk_app_idThe unique SDK App Id.
sdk_transaction_idSDK Transaction ID.
ssl_accept_server_cert_encodedThe certificate (PEM/base64 encoded).
ssl_cert_encodedThe certificate (PEM/base64 encoded).
ssl_cert_storeThe name of the certificate store for the client certificate.
ssl_cert_store_passwordIf 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_typeThe type of certificate store for this certificate.
ssl_cert_subjectThe subject of the certificate used for client authentication.
ssl_server_cert_encodedThe certificate (PEM/base64 encoded).
submit_authentication_labelLabel for UI button users select to submit authentication.
timeoutA timeout for the class.
transaction_statusThe transaction status from the last parsed message (ARes, RReq, or CRes).
whitelisting_data_entryWhitelisting Data Entry.
whitelisting_information_textWhitelisting information text.
why_information_labelLabel for why information section.
why_information_textText to explain the authentication task to the user.

Method List

The following is the full list of the methods of the class with short descriptions. Click on the links for further details.

add_device_paramAdds a device parameter to the collection.
add_extensionAdds an extension to the collection.
add_request_fieldAdds a field to the data in the request.
check_auth_responseChecks the received packet.
configSets or retrieves a configuration setting.
get_auth_requestPrepares data to be sent by the 3DS Server.
interruptInterrupts the current action.
resetClears all properties to their default values.
reset_transaction_infoResets transaction specific information.
send_challenge_requestBuilds and sends the Challenge Request in an app-based challenge flow.

Event List

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_inFired when receiving a data packet from the server.
on_data_packet_outFired when sending a data packet to the server.
on_errorInformation about errors during data delivery.
on_logFires once for each log message.
on_ssl_server_authenticationFired after the server presents its certificate to the client.
on_ssl_statusShows the progress of the secure connection.

Configuration Settings

The following is a list of configuration settings for the class with short descriptions. Click on the links for further details.

AcceptAnyACSCertWhether to accept any ACS certificate during signature validation.
ACSRenderingInterfaceChallenge interface type presented to cardholder.
ACSRenderingUITemplateChallenge type presented to cardholder.
ACSSignedContentString value of the JWS object of the ARes message created by the ACS.
ACSTransactionIdUnique transaction identifier assigned by the ACS.
ACSURLACS URL to which the challenge request is sent.
ChallengeResponseChallenge Response (CRes).
ChallengeTimeRemainingAmount of time left to complete challenge.
DeviceRenderingInterfaceSDK Interface Device Rendering Types supported.
DeviceRenderingUITypeSDK UI Types supported.
DSTransactionIdDirectory server transaction ID.
ErrorCodeCode from the last error message.
ErrorDescriptionDescription from the last error message.
ErrorDetailAdditional details from the last error message.
IncomingExtensionCountThe 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.
IncomingRawExtensionsThe full JSON formatted extension data received from the directory server.
LogLevelLevel of logging enabled.
MaskSensitiveWhether to mask sensitive data in the Log event.
MerchantAppURL3DS Requestor App URL.
MessageTypeType of message that is passed.
OOBAppLabelOOB app label.
OutgoingRawExtensionsThe full JSON formatted extension data sent to the directory server.
ProtocolVersionProtocol version identifier.
ResendChallengeInfoResend challenge information code.
SDKEphemeralPrivateKeyPrivate key class of the ephemeral key pair generated by the Client.
SDKEphemeralPublicKeyPublic key class of the ephemeral key pair generated by the Client.
SDKMaxTimeoutSDK Maximum Timeout.
SDKReferenceNumberAssigned SDK reference number.
ServerTransactionIdUnique transaction identifier assigned by the 3DS Server.
TransactionStatusReasonReason for value of TransactionStatus.
UseAESGCMWhether or not to use AESGCM as the encryption algorithm.
XChildCountThe 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.
XElementThe name of the current element.
XParentThe parent of the current element.
XPathProvides a way to point to a specific element in the returned XML or JSON response.
XSubTreeA snapshot of the current element in the document.
XTextThe text of the current element.
LogSSLPacketsControls whether SSL packets are logged when using the internal security API.
OpenSSLCADirThe path to a directory containing CA certificates.
OpenSSLCAFileName of the file containing the list of CA's trusted by your application.
OpenSSLCipherListA string that controls the ciphers to be used by SSL.
OpenSSLPrngSeedDataThe data to seed the pseudo random number generator (PRNG).
ReuseSSLSessionDetermines if the SSL session is reused.
SSLCACertFilePathsThe paths to CA certificate files on Unix/Linux.
SSLCACertsA newline separated list of CA certificate to use during SSL client authentication.
SSLCheckCRLWhether to check the Certificate Revocation List for the server certificate.
SSLCipherStrengthThe minimum cipher strength used for bulk encryption.
SSLEnabledCipherSuitesThe cipher suite to be used in an SSL negotiation.
SSLEnabledProtocolsUsed to enable/disable the supported security protocols.
SSLEnableRenegotiationWhether the renegotiation_info SSL extension is supported.
SSLIncludeCertChainWhether the entire certificate chain is included in the SSLServerAuthentication event.
SSLProviderThe name of the security provider to use.
SSLSecurityFlagsFlags that control certificate verification.
TLS12SignatureAlgorithmsDefines the allowed TLS 1.2 signature algorithms when UseInternalSecurityAPI is True.
TLS12SupportedGroupsThe supported groups for ECC.
TLS13KeyShareGroupsThe groups for which to pregenerate key shares.
TLS13SignatureAlgorithmsThe allowed certificate signature algorithms.
TLS13SupportedGroupsThe supported groups for (EC)DHE key exchange.

Copyright (c) 2021 /n software inc. - All rights reserved.
/n software 3-D Secure V2 Python Edition - Version 2.0 [Build 7722]