Server Class

Properties   Methods   Events   Config Settings   Errors  

The Server class provides support for the 3DS Server role as defined in the EMV® 3-D Secure (EMV 3DS) specification.

Syntax

class ipworks3ds.Server

Remarks

This class is designed to be used in a web server, or in a process used by a web server to facilitate EMV® 3-D Secure (EMV 3DS) functionality. The class is used primarily for the browser-based flow, but also for some operations in the app-based flow as detailed in other parts of the documentation.

Connecting with SSL Client Authentication

Many directory servers require client authentication via a client certificate. The SSLCert* properties are used to load the SSL client certificate. In order to properly authenticate to the directory server the entire certificate chain must be presented to the directory server during the initial SSL handshake. The sections below describe options for making sure the CA chain is included.

Option 1: PFX With CA Certs

The first option is to specify a PFX file which includes both the client certificate, and CA certificates. In this case the class will read the CA certificates from the PFX file and include them in the request.

Option 2: SSLCACerts Configuration Setting

Another option is to specify the CA certificates separately from the client certificate. To do this the SSLCACerts configuration setting may be set to a CrLf separated list of CA certificates. For instance:

PHP Example

$ca_int = <<<EOT -----BEGIN CERTIFICATE----- MIIEKzCCAxOgAwIBAgIRANTET4LIkxdH6P+CFIiHvTowDQYJKoZIhvcNAQELBQAw ... eWHV5OW1K53o/atv59sOiW5K3crjFhsBOd5Q+cJJnU+SWinPKtANXMht+EDvYY2w F0I1XhM+pKj7FjDr+XNj -----END CERTIFICATE----- EOT; $ca_root = <<<EOT -----BEGIN CERTIFICATE----- MIIEFjCCAv6gAwIBAgIQetu1SMxpnENAnnOz1P+PtTANBgkqhkiG9w0BAQUFADBp ... 8ECs48NRSON+/Pqm9Hxw1H3/yz2qLG4zTI7xJVDESZGEXadLwCJXD6OReX2F/BtU d8q23djXZbVYiIfE9ebr4g3152BlVCHZ2GyPdjhIuLeH21VbT/dyEHHA -----END CERTIFICATE----- EOT; $server->doConfig('SSLCACerts=' . $ca_int . '\n' . $ca_root);

Option 3: CA Certs in Windows Store

When running on Windows the CA certificates will also be included in the request if they are present in the Personal store of the user under which the application is running.

Card Ranges

The application using the 3DS Server class should maintain a cache of card range information that can be queried when a transaction is initiated. The request_card_ranges method will retrieve card range information to be cached.

request_card_ranges requests card ranges and additional information from the directory server.

When a transaction is initiated, the first step that should be taken is to find information about the card range to which the card number belongs. This includes the protocol version(s) supported by the ACS and DS, and if one exists, any corresponding Method URL (used in the browser flow).

Results of this method should be cached in order to quickly look up information when processing transactions. It is recommended to call this method once every 24 hours at a minimum, and once per hour as a maximum to refresh the cache. The class will not cache the returned values; it is up to the user to cache these values in an appropriate location.

The first time this method is called, serial_number will be empty, indicating that all results should be returned. This is an offset the server will use to return only new updates to the card ranges (if any) since the last request. The serial_number will be populated after this method returns, and this value should be saved to be used in subsequent calls.

When a response is received, the card ranges will be made available via the component events and properties.

When message_version is set to 2.3.1, the on_card_range_data event will fire for each card range data object received, and the ranges and acs_protocol_infos properties will be populated to be accessed within the event handler. Optionally, the DS may return a list of URLs that the 3DS Server can use for communication with the DS. If present, these will be available via both the on_dsurl event and the dsur_ls property.

When message_version is set to 2.2.0 or 2.1.0, the on_card_range event will fire for each card range that is returned, and the results will also be held in the card_ranges property.

The following properties are applicable when calling this method:

• directory_server_url (required)
• serial_number
• server_transaction_id
• ServerOperatorId
• EnableDownloadCardRangeDataFile (2.3.1 only)

The following properties are populated after calling this method:

• card_ranges
• DSStartProtocolVersion
• DSEndProtocolVersion
• serial_number
• DSTransactionId
• ResendRequestCardRanges

Note that when message_version 2.3.1, the card range data is only available using the on_card_range_data event.

When using message_version 2.2.0 or 2.3.1, the returned ranges may include ACS Information Indicators. These are used to indicate additional functionality supported by the ACS for the card range(s). For 2.2.0, a ACSInformationIndicator field is exposed in both card_ranges collection and on_card_range event. In version 2.3.1, this information is availalbe in the acs_protocol_infos collection via the Indicator field. Possible values are:

• 01 - Authentication Available at ACS
• 02 - Attempts Supported by ACS or DS
• 03 - Decoupled Authentication Supported
• 04 - Whitelisting Supported
• 05 - Device Binding Supported (2.3.1 only)
• 06 - WebAuthn Authentication Supported (2.3.1 only)
• 07 - SPC Authentication Supported (2.3.1 only)
• 08 - Transaction Risk Analysis Exemption Supported (2.3.1 only)
• 09 - Trust List Exemption Supported (2.3.1 only)
• 10 - Low Value Exemption Supported (2.3.1 only)
• 11 - Secure Corporate Payments Exemption Supported (2.3.1 only)
• 80-99 - Reserved for DS Use

If an error is identified with the card range data received from the directory server when calling the request_card_ranges method, the ResendRequestCardRanges configuration setting will be true, indicating that the request should be resent. When resending, if serial_number was specified for the initial request, it should be set to an empty string before calling request_card_ranges again. Otherwise, the request can be sent without the serial number again, but the server may respond with an error due to multiple requests within an hour.

Note that retrieving card ranges can consume a lot of memory, especially when retrieving the initial set of ranges. The StoreCardRangeData and UseJsonDOM configuration settings can be set to help minimize the amount of memory used. A CardRangeTempPath setting can also be used to specify a temporary path to which the PRes packet will be temporarily written prior to parsing.

When using message_version 2.3.1, if UseJsonDOM is false, the card ranges will need to be cached and processed after the request_card_ranges method returns. The card ranges would then need to be processed in the order indicated by the CardRangeRecordsReadOrder configuration setting. A check will also need to be made for overlap of ranges. If issue(s) are found, the ReportCardRangeError configuration setting should be used to report the error to the directory server.

Method Invocation

The get_method_data method prepares data to be transmitted to the ACS via the cardholder's browser.

When a transaction begins, the card range cache should be queried to find details about the card range to which the card number belongs. If a card_range_method_url is defined for the card range, this method should be used to prepare data to be sent via the cardholder's browser to the card_range_method_url.

If the card_range_method_url is not set for the specified card range, set MethodCompletionIndicator to U before calling send_auth_request.

The following properties are applicable when calling this method:

• method_notification_url (required)

This method returns a string which contains encoded data to be sent to the ACS. This includes server_transaction_id and method_notification_url. After calling this method, the returned string can be transmitted to the ACS via the cardholder's browser.

As per the EMVCo specification, create a hidden iframe in the browser and send a form with the field name threeDSMethodData containing the return value from this method and post the form to the card_range_method_url.

The ACS will record information about the customer's environment and then POST back to the method_notification_url. The page at this URL should expect a form variable with the name threeDSMethodData which will contain the original server_transaction_id value in order to match the response with the request. The form variable value will be base64url encoded and may be passed directly to the check_response method. The class will decode and parse the received value and populate server_transaction_id with the value from the received data.

If the response from the ACS is not received within 10 seconds, set MethodCompletionIndicator to N before calling send_auth_request.

Sending the Authentication Request

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)
• message_version (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 in 2.1.0, required in 2.2.0 and 2.3.1 if BrowserJavaScriptEnabled is true)
• browser_screen_width (required in 2.1.0, required in 2.2.0 and 2.3.1 if BrowserJavaScriptEnabled is true)
• browser_time_zone (required in 2.1.0, required in 2.2.0 and 2.3.1 if BrowserJavaScriptEnabled is true)
• browser_user_agent (required)
• browser_ip_address (conditional)
• browser_java_enabled_val (required in 2.1.0, required in 2.2.0 and 2.3.1 if BrowserJavaScriptEnabled is true)
• browser_java_script_enabled_val (not valid in 2.1.0, required in 2.2.0 and 2.3.1)
• browser_screen_color_depth (required in 2.1.0, required in 2.2.0 and 2.3.1 if BrowserJavaScriptEnabled is true)
• accept_language (2.3.1 only)
• acquirer_country_code (2.3.1 only)

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, D or S), 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.

SPC-Based Authentication

SPC (Secure Payment Confirmation) provides a method to perform a challenge using preestablished FIDO credentials when using a Browser. The SPC authentication can be initiated by the 3DS Requestor via an extra AReq/ARes message pair or by the ACS via a standard Browser Challenge Flow.

For an SPC authentication to execute correctly, the following prerequisites apply:

1. The ACS has an enrolled FIDO authenticator on the device for this Cardholder.
2. The 3DS Requestor and/or the ACS have detected that the Cardholder Browser supports the related SPC APIs (allow="payment *; publickey-credentialsget *"). For the ACS, this information can be obtained via the Browser User Agent data element or via data obtained via the 3DS Method.

SPC-based authentication can be enabled with the following additions:

Prior to sending the initial authentication request packet (AReq) using the send_auth_request method, the ThreeDSRequestorSpcSupport configuration setting should be set to True to indicate that SPC is supported by the 3DS Requestor.

If SPC is accepted by the ACS, the resulting transaction_status should be S. The response will also contain a list of enrolled FIDO (WebAuthn) credentials associated with the cardholder, and SPC transaction data. This data is available in the following configuration settings:

• WebAuthnCredentialListCount
• WebAuthnCredentialListWebAuthnCredential
• WebAuthnCredentialListRelyingPartyId
• SPCTransactionAdditionalData
• SPCTransactionChallenge
• SPCTransactionChallengeInfoText
• SPCTransactionCurrency
• SPCTransactionDisplayName
• SPCTransactionIcon
• SPCTransactionIssuerImage
• SPCTransactionIssuerImageDark
• SPCTransactionIssuerImageMonochrome
• SPCTransactionPayeeName
• SPCTransactionPayeeOrigin
• SPCTransactionPSImage
• SPCTransactionPSImageDark
• SPCTransactionPSImageMonochrome
• SPCTransactionTimeout
• SPCTransactionValue

If a new instance of the Server component will be used after authentication to send the second AReq, the AuthenticationInformation value should be saved to be used later.

This information is relayed to the 3DS Requestor implementation, and the 3DS Requestor invokes the SPC authentication (SPC API) against the WebAuthn Credential list. The cardholder authenticates using the FIDO authenticator on their device, and the 3DS Requestor retrieves the Assertion Data from the SPC API call.

The 3DS Server is then configured to includes this FIDO Assertion Data is then included in a new authentication request by setting the ReqAuthData[Index] and a ReqAuthMethod[Index] of 09. If the AuthenticationInformation value was saved earlier, it can be set via the same configuration setting. If the 3DS Requestor encounters an error during SPC API invokation, this can be indicated using the SPCIncompletionIndicator.

The send_auth_request method should then be called again to transmit this data to the ACS (by way of the DS) in a second AReq.

When send_auth_request returns, the 3DS Server proceed the same as the regular browser-based flow when the ARes is returned.

When SPC authentication is to be performed, the authenticaton must be completed within 9 minutes. The component will automatically start an internal timer that can be checked using the CheckSPCTimeout configuration setting. This will return the number of seconds left for SPC authentication to complete. If the time has expired before receiving the Assertion Data from the 3DS Requestor, checking this configuration setting will cause the component to automatically send the second AReq message with an SPCIncompletionIndicator value of 03, indicating that SPC authentication timed out.

Note that SPC-based authentication is only available when a message_version of 2.3.1 is used.

Challenge Interaction

If the transaction_status is C, a challenge is required.

The get_challenge_request method is used to build the Challenge Request (CReq) which will be sent in a form post to the acsurl property via the cardholder browser.

An iframe should be created in the cardholder's browser, which will be used to send the challenge request and allow the cardholder and ACS to interact directly.

The size of the challenge window (iframe) may be any of the sizes listed in challenge_window_size. Before calling this method set challenge_window_size to the appropriate value to let the ACS know the size of the window on the cardholder's browser.

Calling this method will return a string which should be placed in a creq form variable.

The SessionData setting may also be set with any data that may be helpful to continue processing the transaction after the final challenge response is received at the notification_url. To prepare the session data for submission, query EncodedSessionData. The encoded string may then be placed in the threeDSSessionData form variable.

Note: The maximum length of the threeDSSessionData form variable, after being encoded, is 1024 bytes.

Example Form

Response Handling

Once the challenge has been completed by the cardholder, the directory server will post a Results Request (RReq) to the results_url specified when calling send_auth_request. See check_response and get_results_response for more details.

The ACS will also post the Challenge Response to the notification_url specified when calling send_auth_request. This post contains data which may be parsed to verify the challenge results. See check_response for more details.

Response Handling

After a challenge is complete, the Directory Server and ACS will POST data back to the web server for additional processing. check_response parses a variety of messages that are sent to the Server as part of the authentication process.

The following messages can be parsed using this method:

• The threeDSMethodData form variables received at the method_notification_url
• The Results Request (RReq) message received at the results_url
• The cres form variables received at the notification_url
• The Operation Request Message (OReq) sent from a DS.

When calling the method, pass the message to be parsed as the Response parameter. The properties which are populated after calling this method vary depending on the type of message being parsed. See below for additional information.

Method Data from method_notification_url

After calling get_method_data, a request is made to the card_range_method_url. After this, the ACS will make a POST to method_notification_url to inform the requestor of completion. Retrieve the threeDSMethodData form variable value that was POSTed and pass it to this method. After calling this method, the following properties are populated:

• server_transaction_id

The server_transaction_id may be used to match the response with the request.

Results Request message from results_url

When a challenge is completed for both app-based and browser-based flows, a POST is made to the results_url with a Results Request message.

Prior to checking this RReq message, the ServerTransactionId can be extracted using the ExtractRReqServerTransactionId configuration setting. This value can then be used to look up details on the transaction that were saved prior to starting the challenge process, including the messageVersion which must be set via the message_version property prior to passing the RReq message to the check_response method.

Pass the body of the HTTP request received at results_url to this method. This contains information about the results, and asks for a Results Response to be sent back containing the results_status.

After calling this method, the following properties are populated:

• authentication_eci
• transaction_status
• TransactionStatusReason
• ChallengeCancellationIndicator
• AuthenticationType
• authentication_value

To respond to the POST, set results_status to the appropriate value and call get_results_response to build a response message to be sent back to the directory server. Use the value from get_results_response in the application as the body of the HTTP response. Set the Content-Type header to application/JSON; charset=utf-8

If transaction_status is D and TransactionStatusReason is 29 or 30, this indicates that decoupled authentication should now be performed. When building the Results Response, a results_status value of 04 should be used. Then, within 60 seconds, a new 3RI authentication must be started with the following field requirements:

• ThreeRIIndicator set to 19, indicating Decoupled Authentication Fallback
• DecoupledRequestIndicator set to Y
• AuthenticationInformation set with threeDSReqPriorRef set to the ACS Transaction ID and threeDSReqPriorAuthMethod set to 02 (Cardholder challenge occurred by ACS).

Final Challenge Response from notification_url

In a browser-based flow, the challenge takes place directly between the cardholder and the ACS in a separate iframe or window. The ACS will POST the final challenge response to the notification_url after the challenge is complete. Retrieve the cres form variable value from the POST data and pass it to check_response. After calling this method the following properties are populated:

• server_transaction_id
• transaction_status

In addition to the cres variable, a threeDSSessionData variable will be present if SessionData was set before calling get_challenge_request. The threeDSSessionData value POSTed to notification_url may be passed to EncodedSessionData. Query SessionData to get the decoded session data.

Operation Request Message (OReq)

OReq messages are used to communicate operational information from a DS to the 3DS Server. This message is not part of the 3-D Secure authentication flow.

When an OReq message is received, check_response should be called to validate the message. There may be more than one OReq message sent in a sequence, and check_response should be called for each. The current instance of the Server object can be cached for the duration of the OReq sequence until the final OReq is received. The Operation.SequenceNumber should also be set prior to calling check_response. The component will verify the sequence number of the received OReq to ensure it's not out of sequence.

After calling this method, details are made available in operation.

If any OReq data element fails validation, Operation.MessageStatus will be set to "02". If the OReq is valid, Operation.MessageStatus will be empty.

If the OReq is valid, determine if the final OReq has been received (Operation.SequenceNumber equals Operation.SequenceTotal). If these values match, the final OReq in the sequence has been received, and get_operation_response can be used to generate the ORes message.

For valid OReq messages that are not the final OReq in the sequence, the response should be HTTP Status 200 (OK) with an empty HTTP body.

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.

Method List

---

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

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.

Config Settings

---

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

accept_language Property

HTTP accept language header value sent from the cardholder's browser.

Syntax

def get_accept_language() -> str: ...
def set_accept_language(value: str) -> None: ...

accept_language = property(get_accept_language, set_accept_language)

Default Value

""

Remarks

Value representing the browser language preference present in the HTTP header, as defined in IETF BCP 47.

This property accepts a comma separated list of language tags. For example: en,fr-FR

Valid for message_version 2.3.1 only.

account_type Property

Indicates the type of account.

Syntax

def get_account_type() -> str: ...
def set_account_type(value: str) -> None: ...

account_type = property(get_account_type, set_account_type)

Default Value

""

Remarks

This is included in the Authentication Request Message (AReq) sent to the directory server. Required if the 3-D Secure Requestor is asking the cardholder which account type they are using before making the purchase. Required in some markets (for example, for merchants in Brazil). Otherwise, this is optional.

Valid values are as follows:

acquirer_bin Property

Acquiring institution identification code.

Syntax

def get_acquirer_bin() -> str: ...
def set_acquirer_bin(value: str) -> None: ...

acquirer_bin = property(get_acquirer_bin, set_acquirer_bin)

Default Value

""

Remarks

This value correlates to the Acquirer BIN as defined by each payment system or directory server. This field is required to be set for payment authentication.

acquirer_country_code Property

Acquirer Country Code.

Syntax

def get_acquirer_country_code() -> str: ...
def set_acquirer_country_code(value: str) -> None: ...

acquirer_country_code = property(get_acquirer_country_code, set_acquirer_country_code)

Default Value

""

Remarks

The code of the country where the acquiring institution is located (in accordance with ISO 3166).

This value should be formatted as a ISO 3166-1 numeric three-digit country code.

Valid for message_version 2.3.1 only.

acquirer_merchant_id Property

Acquirer-assigned merchant identifier.

Syntax

def get_acquirer_merchant_id() -> str: ...
def set_acquirer_merchant_id(value: str) -> None: ...

acquirer_merchant_id = property(get_acquirer_merchant_id, set_acquirer_merchant_id)

Default Value

""

Remarks

This field contains the merchant identifier assigned by the acquirer. The merchant id is required to be set for payment authentication.

acs_protocol_info_count Property

The number of records in the ACSProtocolInfo arrays.

Syntax

def get_acs_protocol_info_count() -> int: ...

acs_protocol_info_count = property(get_acs_protocol_info_count, None)

Default Value

0

Remarks

This property controls the size of the following arrays:

• acs_protocol_info_indicator
• acs_protocol_info_protocol_version
• acs_protocol_info_supported_msg_ext
• acs_protocol_info_three_ds_method_url

The array indices start at 0 and end at acs_protocol_info_count - 1.

This property is read-only.

acs_protocol_info_indicator Property

Additional information on the card range as supplied by the ACS.

Syntax

def get_acs_protocol_info_indicator(acs_protocol_info_index: int) -> str: ...

Default Value

""

Remarks

Additional information on the card range as supplied by the ACS. This field is a comma separated list of values returned from the server; possible values are:

The acs_protocol_info_index parameter specifies the index of the item in the array. The size of the array is controlled by the acs_protocol_info_count property.

This property is read-only.

acs_protocol_info_protocol_version Property

The Protocol Version supported by the ACS for the card range.

Syntax

def get_acs_protocol_info_protocol_version(acs_protocol_info_index: int) -> str: ...

Default Value

""

Remarks

The Protocol Version supported by the ACS for the card range.

The acs_protocol_info_index parameter specifies the index of the item in the array. The size of the array is controlled by the acs_protocol_info_count property.

This property is read-only.

acs_protocol_info_supported_msg_ext Property

A list of message extensions supported by the ACS that contains the Assigned Extension Group Identifier and the Extension Version Number.

Syntax

def get_acs_protocol_info_supported_msg_ext(acs_protocol_info_index: int) -> str: ...

Default Value

""

Remarks

A list of message extensions supported by the ACS that contains the Assigned Extension Group Identifier and the Extension Version Number.

This field is a comma separate list of values returned from the server in the following format:

id,version;id2,version2;...

The acs_protocol_info_index parameter specifies the index of the item in the array. The size of the array is controlled by the acs_protocol_info_count property.

This property is read-only.

acs_protocol_info_three_ds_method_url Property

The ACS URL that will be used by the 3DS Method for a particular protocol version.

Syntax

def get_acs_protocol_info_three_ds_method_url(acs_protocol_info_index: int) -> str: ...

Default Value

""

Remarks

The ACS URL that will be used by the 3DS Method for a particular protocol version.

The acs_protocol_info_index parameter specifies the index of the item in the array. The size of the array is controlled by the acs_protocol_info_count property.

This property is read-only.

acsurl Property

URL of the ACS to be used for the challenge.

Syntax

def get_acsurl() -> str: ...
def set_acsurl(value: str) -> None: ...

acsurl = property(get_acsurl, set_acsurl)

Default Value

""

Remarks

This field contains the fully qualified URL of the ACS to be used for the challenge. This will be populated after the call to send_auth_request method if the Authentication Response Message (ARes) indicates that a challenge is required.

authentication_eci Property

Value to be passed in the authorization message.

Syntax

def get_authentication_eci() -> str: ...

authentication_eci = property(get_authentication_eci, None)

Default Value

""

Remarks

This property is determined by the Access Control Server (ACS), and is filled after the call to send_auth_request (for a frictionless flow), or when the Results Request Message (RReq) is parsed using check_response (for a challenge flow).

This property contains the two digit Electronic Commerce Indicator (ECI) value, which is to be submitted in a credit card authorization message. This value indicates to the processor that the customer data in the authorization message has been authenticated. The data contained within this property is only valid if the transaction_status is "Y" or "A".

This property is read-only.

authentication_indicator Property

3DS Requestor Authentication Indicator.

Syntax

def get_authentication_indicator() -> str: ...
def set_authentication_indicator(value: str) -> None: ...

authentication_indicator = property(get_authentication_indicator, set_authentication_indicator)

Default Value

"01"

Remarks

Indicates the type of Authentication request. This data element provides additional information to the ACS to determine the best approach for handing an authentication request. Included in the Authorization Request Message (ARes) sent by the send_auth_request method. Possible values are:

authentication_value Property

Used to provide proof of authentication.

Syntax

def get_authentication_value() -> str: ...

authentication_value = property(get_authentication_value, None)

Default Value

""

Remarks

This property is determined by the Access Control Server (ACS), and is filled after the call to send_auth_request (for a frictionless flow), or when the Results Request Message (RReq) is parsed using check_response (for a challenge flow).

This property will be valid if the transaction_status is "Y" or "A". The value may be used to provide proof of authentication.

This property is read-only.

billing_address_city Property

The city of the address.

Syntax

def get_billing_address_city() -> str: ...
def set_billing_address_city(value: str) -> None: ...

billing_address_city = property(get_billing_address_city, set_billing_address_city)

Default Value

""

Remarks

The city of the address. The maximum length is 50 characters.

billing_address_country Property

The country of the address.

Syntax

def get_billing_address_country() -> str: ...
def set_billing_address_country(value: str) -> None: ...

billing_address_country = property(get_billing_address_country, set_billing_address_country)

Default Value

""

Remarks

The country of the address. The format is a 3 digit country code as defined in ISO 3166-1.

billing_address_line1 Property

The first line of the street address or equivalent local portion of the address.

Syntax

def get_billing_address_line1() -> str: ...
def set_billing_address_line1(value: str) -> None: ...

billing_address_line1 = property(get_billing_address_line1, set_billing_address_line1)

Default Value

""

Remarks

The first line of the street address or equivalent local portion of the address. The maximum length is 50 characters.

billing_address_line2 Property

The second line of the street address or equivalent local portion of the address.

Syntax

def get_billing_address_line2() -> str: ...
def set_billing_address_line2(value: str) -> None: ...

billing_address_line2 = property(get_billing_address_line2, set_billing_address_line2)

Default Value

""

Remarks

The second line of the street address or equivalent local portion of the address. The maximum length is 50 characters.

billing_address_line3 Property

The third line of the street address or equivalent local portion of the address.

Syntax

def get_billing_address_line3() -> str: ...
def set_billing_address_line3(value: str) -> None: ...

billing_address_line3 = property(get_billing_address_line3, set_billing_address_line3)

Default Value

""

Remarks

The third line of the street address or equivalent local portion of the address. The maximum length is 50 characters.

billing_address_postal_code Property

The ZIP or other postal code of the address.

Syntax

def get_billing_address_postal_code() -> str: ...
def set_billing_address_postal_code(value: str) -> None: ...

billing_address_postal_code = property(get_billing_address_postal_code, set_billing_address_postal_code)

Default Value

""

Remarks

The ZIP or other postal code of the address. The maximum length is 16 characters.

billing_address_state Property

The state or province of the address.

Syntax

def get_billing_address_state() -> str: ...
def set_billing_address_state(value: str) -> None: ...

billing_address_state = property(get_billing_address_state, set_billing_address_state)

Default Value

""

Remarks

The state or province of the address. The maximum length is 3 characters and should be the country subdivision code defined in ISO 3166-2.

browser_accept_header Property

HTTP accept header sent from the cardholder's browser.

Syntax

def get_browser_accept_header() -> str: ...
def set_browser_accept_header(value: str) -> None: ...

browser_accept_header = property(get_browser_accept_header, set_browser_accept_header)

Default Value

""

Remarks

This field contains the exact content of the HTTP accept header as sent to the merchant from the cardholder's user agent. This field is required only if the cardholder's user agent supplied a value.

browser_ip_address Property

IP address of the cardholder's browser.

Syntax

def get_browser_ip_address() -> str: ...
def set_browser_ip_address(value: str) -> None: ...

browser_ip_address = property(get_browser_ip_address, set_browser_ip_address)

Default Value

""

Remarks

This field contains the IP address of the cardholder's browser as returned by the HTTP headers.

browser_java_enabled_val Property

Ability of the cardholder's browser to execute Java.

Syntax

def get_browser_java_enabled_val() -> int: ...
def set_browser_java_enabled_val(value: int) -> None: ...

browser_java_enabled_val = property(get_browser_java_enabled_val, set_browser_java_enabled_val)

Default Value

0

Remarks

This field contains a value representing the ability of the cardholder's browser to execute Java.

Possible values are as follows:

browser_java_script_enabled_val Property

Ability of the cardholder's browser to execute JavaScript.

Syntax

def get_browser_java_script_enabled_val() -> int: ...
def set_browser_java_script_enabled_val(value: int) -> None: ...

browser_java_script_enabled_val = property(get_browser_java_script_enabled_val, set_browser_java_script_enabled_val)

Default Value

0

Remarks

This field contains a value representing the ability of the cardholder's browser to execute JavaScript.

Possible values are as follows:

browser_language Property

The cardholder's browser language.

Syntax

def get_browser_language() -> str: ...
def set_browser_language(value: str) -> None: ...

browser_language = property(get_browser_language, set_browser_language)

Default Value

""

Remarks

This field contains the cardholder's browser language as defined in IETF BCP 47.

browser_screen_color_depth Property

The screen color depth of the cardholder's browser.

Syntax

def get_browser_screen_color_depth() -> str: ...
def set_browser_screen_color_depth(value: str) -> None: ...

browser_screen_color_depth = property(get_browser_screen_color_depth, set_browser_screen_color_depth)

Default Value

""

Remarks

This field contains a value representing the bit depth of the color palette, in bits per pixel, for displaying images.

For message_version 2.1.0, this field is required. If browser_java_enabled_val is False, a value of 1 can be used. When using message_version of 2.2.0 or 2.3.1 and both browser_java_enabled_val and browser_java_script_enabled_val are False, no value is required.

browser_screen_height Property

The screen height of the cardholder's browser.

Syntax

def get_browser_screen_height() -> str: ...
def set_browser_screen_height(value: str) -> None: ...

browser_screen_height = property(get_browser_screen_height, set_browser_screen_height)

Default Value

""

Remarks

This field contains the total height of the cardholder's screen in pixels.

For message_version 2.1.0, this field is required. If browser_java_enabled_val is False, a value of 0 can be used. When using message_version of 2.2.0 or 2.3.1 and both browser_java_enabled_val and browser_java_script_enabled_val are False, no value is required.

browser_screen_width Property

The screen width of the cardholder's browser.

Syntax

def get_browser_screen_width() -> str: ...
def set_browser_screen_width(value: str) -> None: ...

browser_screen_width = property(get_browser_screen_width, set_browser_screen_width)

Default Value

""

Remarks

This field contains the total width of the cardholder's screen in pixels.

For message_version 2.1.0, this field is required. If browser_java_enabled_val is False, a value of 0 can be used. When using message_version of 2.2.0 or 2.3.1 and both browser_java_enabled_val and browser_java_script_enabled_val are False, no value is required.

browser_time_zone Property

The timezone offset of the cardholder's browser.

Syntax

def get_browser_time_zone() -> str: ...
def set_browser_time_zone(value: str) -> None: ...

browser_time_zone = property(get_browser_time_zone, set_browser_time_zone)

Default Value

""

Remarks

This field contains the difference between UTC time and the cardholder's browser local time in minutes.

For message_version 2.1.0, this field is required. If browser_java_enabled_val is False, a value of 0 can be used. When using message_version of 2.2.0 or 2.3.1 and both browser_java_enabled_val and browser_java_script_enabled_val are False, no value is required.

browser_user_agent Property

The User-Agent provided by the cardholder's browser.

Syntax

def get_browser_user_agent() -> str: ...
def set_browser_user_agent(value: str) -> None: ...

browser_user_agent = property(get_browser_user_agent, set_browser_user_agent)

Default Value

""

Remarks

This field contains the exact content of the HTTP User-Agent header.

card_exp_date Property

Expiration date of the PAN or Token.

Syntax

def get_card_exp_date() -> str: ...
def set_card_exp_date(value: str) -> None: ...

card_exp_date = property(get_card_exp_date, set_card_exp_date)

Default Value

""

Remarks

This field contains the expiration date of the PAN or Token supplied in the card_number property. The format for this field is YYMM.

cardholder_email Property

The cardholder email address.

Syntax

def get_cardholder_email() -> str: ...
def set_cardholder_email(value: str) -> None: ...

cardholder_email = property(get_cardholder_email, set_cardholder_email)

Default Value

""

Remarks

This field contains the cardholder email address to be sent to the directory server when calling send_auth_request.

cardholder_home_phone Property

The cardholder home phone number.

Syntax

def get_cardholder_home_phone() -> str: ...
def set_cardholder_home_phone(value: str) -> None: ...

cardholder_home_phone = property(get_cardholder_home_phone, set_cardholder_home_phone)

Default Value

""

Remarks

This field contains the home phone number provided by the card holder.

Phone numbers must be specified in the following format: CountryCode-Subscriber (e.g. 1-1234567899)

The "-" is used to separate the "Country Code" and "Subscriber" sections. The values are then formatted according to the EMVCo specification (a JSON object) in the request like so:

  "homePhone": {
    "cc": "1",
    "subscriber": "1234567899"
  }

cardholder_mobile_phone Property

The cardholder mobile phone number.

Syntax

def get_cardholder_mobile_phone() -> str: ...
def set_cardholder_mobile_phone(value: str) -> None: ...

cardholder_mobile_phone = property(get_cardholder_mobile_phone, set_cardholder_mobile_phone)

Default Value

""

Remarks

This field contains the mobile phone number provided by the cardholder.

Phone numbers must be specified in the following format: CountryCode-Subscriber (e.g. 1-1234567899)

The "-" is used to separate the "Country Code" and "Subscriber" sections. The values are then formatted according to the EMVCo specification (a JSON object) in the request like so:

  "homePhone": {
    "cc": "1",
    "subscriber": "1234567899"
  }

cardholder_name Property

Name of the cardholder.

Syntax

def get_cardholder_name() -> str: ...
def set_cardholder_name(value: str) -> None: ...

cardholder_name = property(get_cardholder_name, set_cardholder_name)

Default Value

""

Remarks

This property contains the name of the cardholder. Limited to the alphanumeric characters listed in EMV Book 4, Annex B. Required to be set unless market or regional mandates restricts sending this information.

cardholder_work_phone Property

The cardholder work phone number.

Syntax

def get_cardholder_work_phone() -> str: ...
def set_cardholder_work_phone(value: str) -> None: ...

cardholder_work_phone = property(get_cardholder_work_phone, set_cardholder_work_phone)

Default Value

""

Remarks

This field contains the work phone number provided by the cardholder.

Phone numbers must be specified in the following format: CountryCode-Subscriber (e.g. 1-1234567899)

The "-" is used to separate the "Country Code" and "Subscriber" sections. The values are then formatted according to the EMVCo specification (a JSON object) in the request like so:

  "homePhone": {
    "cc": "1",
    "subscriber": "1234567899"
  }

card_number Property

Customer's account number that will be authenticated.

Syntax

def get_card_number() -> str: ...
def set_card_number(value: str) -> None: ...

card_number = property(get_card_number, set_card_number)

Default Value

""

Remarks

This property contains the customer's credit card number (PAN) or token that will be used in the authorization request for payment transactions. This property is 13-19 characters long.

card_range_count Property

The number of records in the CardRange arrays.

Syntax

def get_card_range_count() -> int: ...

card_range_count = property(get_card_range_count, None)

Default Value

0

Remarks

This property controls the size of the following arrays:

• card_range_acs_end_protocol_version
• card_range_acs_information_indicator
• card_range_acs_start_protocol_version
• card_range_action
• card_range_ds_end_protocol_version
• card_range_ds_start_protocol_version
• card_range_end
• card_range_method_url
• card_range_start

The array indices start at 0 and end at card_range_count - 1.

This property is read-only.

card_range_acs_end_protocol_version Property

The most recent active protocol version that is supported by the ACS.

Syntax

def get_card_range_acs_end_protocol_version(card_range_index: int) -> str: ...

Default Value

""

Remarks

The most recent active protocol version that is supported by the ACS.

The card_range_index parameter specifies the index of the item in the array. The size of the array is controlled by the card_range_count property.

This property is read-only.

card_range_acs_information_indicator Property

Additional information on the card range as supplied by the ACS.

Syntax

def get_card_range_acs_information_indicator(card_range_index: int) -> str: ...

Default Value

"0"

Remarks

Additional information on the card range as supplied by the ACS. This property is a comma separate list of values returned from the server; possible values are:

• 01 - Authentication Available at ACS
• 02 - Attempts Supported by ACS or DS
• 03 - Decoupled Authentication Supported
• 04 - Whitelisting Supported
• 05 - Device Binding Supported (2.3.1 only)
• 06 - WebAuthn Authentication Supported (2.3.1 only)
• 07 - SPC Authentication Supported (2.3.1 only)
• 08 - Transaction Risk Analysis Exemption Supported (2.3.1 only)
• 09 - Trust List Exemption Supported (2.3.1 only)
• 10 - Low Value Exemption Supported (2.3.1 only)
• 11 - Secure Corporate Payments Exemption Supported (2.3.1 only)
• 80-99 - Reserved for DS Use

The card_range_index parameter specifies the index of the item in the array. The size of the array is controlled by the card_range_count property.

This property is read-only.

card_range_acs_start_protocol_version Property

The earliest (i.

Syntax

def get_card_range_acs_start_protocol_version(card_range_index: int) -> str: ...

Default Value

""

Remarks

The earliest (i.e. oldest) active protocol version that is supported by the ACS.

The card_range_index parameter specifies the index of the item in the array. The size of the array is controlled by the card_range_count property.

This property is read-only.

card_range_action Property

The action to be taken with the card range specified by the Start and End properties.

Syntax

def get_card_range_action(card_range_index: int) -> str: ...

Default Value

""

Remarks

The action to be taken with the card range specified by the card_range_start and card_range_end fields. Possible values are:

• A - Add the card range to the cache (default value)
• D - Delete the card range from the cache
• M - Modify the card range data

If the serial_number was not included in the Card Range Request, the Action will be A (add) for all ranges returned. If no action is returned for the card range (empty value), it can be assumed that the action for the range is A.

The card_range_index parameter specifies the index of the item in the array. The size of the array is controlled by the card_range_count property.

This property is read-only.

card_range_ds_end_protocol_version Property

The most recent active protocol version that is supported by the DS.

Syntax

def get_card_range_ds_end_protocol_version(card_range_index: int) -> str: ...

Default Value

""

Remarks

The most recent active protocol version that is supported by the DS.

The card_range_index parameter specifies the index of the item in the array. The size of the array is controlled by the card_range_count property.

This property is read-only.

card_range_ds_start_protocol_version Property

The earliest (i.

Syntax

def get_card_range_ds_start_protocol_version(card_range_index: int) -> str: ...

Default Value

""

Remarks

The earliest (i.e. oldest) active protocol version that is supported by the DS.

The card_range_index parameter specifies the index of the item in the array. The size of the array is controlled by the card_range_count property.

This property is read-only.

card_range_end Property

Last number in a range of credit card numbers returned by the Directory Server.

Syntax

def get_card_range_end(card_range_index: int) -> str: ...

Default Value

""

Remarks

Last number in a range of credit card numbers returned by the Directory Server.

This property contains the final card number in the current range. The first number in the current range is contained in card_range_start, and the action (add or delete) to take on this range is contained in card_range_action. Note that the card ranges must be processed in the order returned.

Card ranges returned by a Card Range Request are for credit cards that support 3-D Secure. If the customer's credit card number is not within one of these ranges, you cannot use 3-D Secure for that card. Examples of card numbers that may not be eligible for 3-D Secure are check cards, corporate cards, and gift cards.

The card_range_index parameter specifies the index of the item in the array. The size of the array is controlled by the card_range_count property.

This property is read-only.

card_range_method_url Property

The ACS URL that will be used by the 3DS method.

Syntax

def get_card_range_method_url(card_range_index: int) -> str: ...

Default Value

""

Remarks

The ACS URL that will be used by the 3DS method.

The card_range_index parameter specifies the index of the item in the array. The size of the array is controlled by the card_range_count property.

This property is read-only.

card_range_start Property

First number in a range of credit card numbers returned by the Directory Server.

Syntax

def get_card_range_start(card_range_index: int) -> str: ...

Default Value

""

Remarks

First number in a range of credit card numbers returned by the Directory Server.

This property contains the first card number in the current range. The final number in the current range is contained in card_range_end, and the action (add or delete) to take on this range is contained in card_range_action. Note that the card ranges must be processed in the order returned.

Card ranges returned by a Card Range Request are for credit cards that support 3-D Secure. If the customer's credit card number is not within one of these ranges, you cannot use 3-D Secure for that card. Examples of card numbers that may not be eligible for 3-D Secure are check cards, corporate cards, and gift cards.

The card_range_index parameter specifies the index of the item in the array. The size of the array is controlled by the card_range_count property.

This property is read-only.

challenge_window_size Property

Challenge window size.

Syntax

def get_challenge_window_size() -> int: ...
def set_challenge_window_size(value: int) -> None: ...

challenge_window_size = property(get_challenge_window_size, set_challenge_window_size)

Default Value

1

Remarks

This field indicates the dimensions of the challenge window that has been displayed to the cardholder. The ACS shall reply with content that is formatted to appropriately render in this window to provide the best possible user experience.

Preconfigured sizes are width x height in pixels of the window displayed in the cardholder browser. Possible values are:

This value is included in the Challenge Request Message (CReq) generated by the component when the get_challenge_request methods are called.

client_auth_request Property

The data received by the class to be sent in the authentication request.

Syntax

def get_client_auth_request() -> str: ...
def set_client_auth_request(value: str) -> None: ...

client_auth_request = property(get_client_auth_request, set_client_auth_request)

Default Value

""

Remarks

The 3DS SDK should prepare data to be sent by the 3DS Server class. Set client_auth_request to the data received from the 3DS SDK before calling send_auth_request.

See the 3DS SDK documentation for details on preparing this data.

client_auth_response Property

The authentication response for an app-based flow.

Syntax

def get_client_auth_response() -> str: ...

client_auth_response = property(get_client_auth_response, None)

Default Value

""

Remarks

This property is populated after calling send_auth_request, and is only applicable for the app-based flow. If a challenge is required, this data should be sent back to the 3DS SDK over the secure channel.

See send_auth_request for more details about handling the response.

This property is read-only.

data_packet_out Property

Contains the data packet sent to the server.

Syntax

def get_data_packet_out() -> str: ...

data_packet_out = property(get_data_packet_out, None)

Default Value

""

Remarks

After calling either the request_card_ranges, or send_auth_request methods, this property will contain the entire data packet that was sent. Also, after calling the get_challenge_request or get_results_response method, this property will contain the constructed messages. The contents of this property should be logged for each transaction.

This property is read-only.

device_channel Property

Device channel.

Syntax

def get_device_channel() -> str: ...
def set_device_channel(value: str) -> None: ...

device_channel = property(get_device_channel, set_device_channel)

Default Value

"02"

Remarks

This field indicates the type of channel interface being used to initiate the transaction.

Possible values include:

directory_server_url Property

The address of the Directory Server.

Syntax

def get_directory_server_url() -> str: ...
def set_directory_server_url(value: str) -> None: ...

directory_server_url = property(get_directory_server_url, set_directory_server_url)

Default Value

""

Remarks

This is the URL to which the request_card_ranges and send_auth_request methods post.

ds_supported_protocols Property

Protocol Versions supported by the DS.

Syntax

def get_ds_supported_protocols() -> int: ...
def set_ds_supported_protocols(value: int) -> None: ...

ds_supported_protocols = property(get_ds_supported_protocols, set_ds_supported_protocols)

Default Value

0

Remarks

The active protocol versions supported by the Directory Server. A bitwise OR of the following values:

dsurl_count Property

The number of records in the DSURL arrays.

Syntax

def get_dsurl_count() -> int: ...

dsurl_count = property(get_dsurl_count, None)

Default Value

0

Remarks

This property controls the size of the following arrays:

• dsurl_country_code
• dsurl_three_ds_server_to_ds_url

The array indices start at 0 and end at dsurl_count - 1.

This property is read-only.

dsurl_country_code Property

The country for which the 3DS Server to DS URL can be used.

Syntax

def get_dsurl_country_code(dsurl_index: int) -> str: ...

Default Value

""

Remarks

The country for which the 3DS Server to DS URL can be used.

The dsurl_index parameter specifies the index of the item in the array. The size of the array is controlled by the dsurl_count property.

This property is read-only.

dsurl_three_ds_server_to_ds_url Property

URL that the 3DS Server uses to communicate with a DS for a particular card range.

Syntax

def get_dsurl_three_ds_server_to_ds_url(dsurl_index: int) -> str: ...

Default Value

""

Remarks

URL that the 3DS Server uses to communicate with a DS for a particular card range. If the DS Country Code is absent, the 3DS Server can use this URL for all card ranges.

The dsurl_index parameter specifies the index of the item in the array. The size of the array is controlled by the dsurl_count property.

This property is read-only.

error_packet Property

The error packet.

Syntax

def get_error_packet() -> str: ...

error_packet = property(get_error_packet, None)

Default Value

""

Remarks

If an error is encountered while parsing a received packet using the check_response method, this field will be populated with an error packet to be sent back to the server.

If the message being parsed is an error, this field will be populated with the received error packet itself.

This property is read-only.

extension_count Property

The number of records in the Extension arrays.

Syntax

def get_extension_count() -> int: ...
def set_extension_count(value: int) -> None: ...

extension_count = property(get_extension_count, set_extension_count)

Default Value

0

Remarks

This property controls the size of the following arrays:

• extension_critical
• extension_data
• extension_id
• extension_name

The array indices start at 0 and end at extension_count - 1.

extension_critical Property

Whether the extension is critical.

Syntax

def get_extension_critical(extension_index: int) -> bool: ...
def set_extension_critical(extension_index: int, value: bool) -> None: ...

Default Value

FALSE

Remarks

Whether the extension is critical.

This setting specifies whether the recipient must understand the contents of the extension to interpret the entire message.

The extension_index parameter specifies the index of the item in the array. The size of the array is controlled by the extension_count property.

extension_data Property

The extension data as JSON.

Syntax

def get_extension_data(extension_index: int) -> str: ...
def set_extension_data(extension_index: int, value: str) -> None: ...

Default Value

""

Remarks

The extension data as JSON.

This setting specifies the JSON formatted extension data.

The extension_index parameter specifies the index of the item in the array. The size of the array is controlled by the extension_count property.

extension_id Property

The id of the specified extension.

Syntax

def get_extension_id(extension_index: int) -> str: ...
def set_extension_id(extension_index: int, value: str) -> None: ...

Default Value

""

Remarks

The id of the specified extension.

This setting specifies a unique identifier for the extension.

The extension_index parameter specifies the index of the item in the array. The size of the array is controlled by the extension_count property.

extension_name Property

The extension name.

Syntax

def get_extension_name(extension_index: int) -> str: ...
def set_extension_name(extension_index: int, value: str) -> None: ...

Default Value

""

Remarks

The extension name.

This setting specifies the name of the extension as defined by the extension owner.

The extension_index parameter specifies the index of the item in the array. The size of the array is controlled by the extension_count property.

merchant_category_code Property

Merchant category code.

Syntax

def get_merchant_category_code() -> str: ...
def set_merchant_category_code(value: str) -> None: ...

merchant_category_code = property(get_merchant_category_code, set_merchant_category_code)

Default Value

""

Remarks

DS-specific code describing the Merchant's type of business, product, or service. Required to be set prior to calling send_auth_request.

merchant_country_code Property

Country code of the merchant.

Syntax

def get_merchant_country_code() -> str: ...
def set_merchant_country_code(value: str) -> None: ...

merchant_country_code = property(get_merchant_country_code, set_merchant_country_code)

Default Value

""

Remarks

This field contains the country code of the merchant. This value correlates to the Merchant Country Code as defined by each Payment System or DS. Required to be set prior to calling send_auth_request.

merchant_name Property

Merchant name.

Syntax

def get_merchant_name() -> str: ...
def set_merchant_name(value: str) -> None: ...

merchant_name = property(get_merchant_name, set_merchant_name)

Default Value

""

Remarks

The name of the merchant as assigned by the acquirer or payment system. Required to be set prior to calling send_auth_request.

message_category Property

The category of the message.

Syntax

def get_message_category() -> str: ...
def set_message_category(value: str) -> None: ...

message_category = property(get_message_category, set_message_category)

Default Value

""

Remarks

This field identifies the category of the message (Payment Authentication or Non-Payment Authentication). This will be sent in the Authentication Request Message (AReq) sent by the component when send_auth_request is called, and in the Results Request Message (RReq) received from the directory server (populated after calling check_response.

Possible values include:

message_version Property

Protocol version identifier.

Syntax

def get_message_version() -> str: ...
def set_message_version(value: str) -> None: ...

message_version = property(get_message_version, set_message_version)

Default Value

"2.1.0"

Remarks

The protocol version number of the specification used by the system creating this message.

Possible values are:

The message version number is set by the 3DS Server which originates the protocol with the AReq message (when send_auth_request is called). The message version number does not change during a 3DS transaction.

method_notification_url Property

The URL to which the method notification will be posted.

Syntax

def get_method_notification_url() -> str: ...
def set_method_notification_url(value: str) -> None: ...

method_notification_url = property(get_method_notification_url, set_method_notification_url)

Default Value

""

Remarks

This property specifies the URL to which the ACS will post when the method execution has completed. This must be set before calling get_method_data. See get_method_data for more details.

notification_url Property

The notification URL to which the challenge response is sent.

Syntax

def get_notification_url() -> str: ...
def set_notification_url(value: str) -> None: ...

notification_url = property(get_notification_url, set_notification_url)

Default Value

""

Remarks

This property specifies the URL to which the final challenge response is POSTed in a browser-based flow. This must be set before calling send_auth_request.

After the challenge interaction is complete the ACS will post data to the URL specified in this property to notify the application that the challenge is complete. The data received at this URL can be processed by calling check_response. See get_challenge_request and check_response for more details.

operation_info_category Property

Indicates the category/type of information.

Syntax

def get_operation_info_category() -> str: ...

operation_info_category = property(get_operation_info_category, None)

Default Value

""

Remarks

Indicates the category/type of information.

This property is read-only.

operation_info_description Property

Describes the reason for the operational communication or the response to an action taken by the recipient.

Syntax

def get_operation_info_description() -> str: ...

operation_info_description = property(get_operation_info_description, None)

Default Value

""

Remarks

Describes the reason for the operational communication or the response to an action taken by the recipient.

This property is read-only.

operation_info_expiration_date Property

The date after which the relevance of the operational information expires.

Syntax

def get_operation_info_expiration_date() -> str: ...

operation_info_expiration_date = property(get_operation_info_expiration_date, None)

Default Value

""

Remarks

The date after which the relevance of the operational information expires.

This property is read-only.

operation_info_message_status Property

Indicates the status of the operational request message sequence from the source of the OReq.

Syntax

def get_operation_info_message_status() -> str: ...
def set_operation_info_message_status(value: str) -> None: ...

operation_info_message_status = property(get_operation_info_message_status, set_operation_info_message_status)

Default Value

""

Remarks

Indicates the status of the operational request message sequence from the source of the OReq.

operation_info_prior_transaction_id Property

The transaction ID of the prior transaction to which the operational information refers.

Syntax

def get_operation_info_prior_transaction_id() -> str: ...

operation_info_prior_transaction_id = property(get_operation_info_prior_transaction_id, None)

Default Value

""

Remarks

The transaction ID of the prior transaction to which the operational information refers.

This property is read-only.

operation_info_prior_transaction_id_type Property

The type of transaction ID of the prior transaction to which the operational information refers.

Syntax

def get_operation_info_prior_transaction_id_type() -> int: ...

operation_info_prior_transaction_id_type = property(get_operation_info_prior_transaction_id_type, None)

Default Value

0

Remarks

The type of transaction ID of the prior transaction to which the operational information refers.

This property is read-only.

operation_info_sequence_id Property

Uniquely identifies a message sequence and will remain constant in the sequence of messages.

Syntax

def get_operation_info_sequence_id() -> str: ...

operation_info_sequence_id = property(get_operation_info_sequence_id, None)

Default Value

""

Remarks

Uniquely identifies a message sequence and will remain constant in the sequence of messages.

This property is read-only.

operation_info_sequence_number Property

The current message in the sequence.

Syntax

def get_operation_info_sequence_number() -> int: ...
def set_operation_info_sequence_number(value: int) -> None: ...

operation_info_sequence_number = property(get_operation_info_sequence_number, set_operation_info_sequence_number)

Default Value

0

Remarks

The current message in the sequence. Set this before calling check_response when an OReq packet is received. The component will verify the sequence number of the received OReq to ensure it's not out of sequence.

operation_info_sequence_total Property

The total number of messages in the sequence and will remain constant in the sequence of messages.

Syntax

def get_operation_info_sequence_total() -> int: ...

operation_info_sequence_total = property(get_operation_info_sequence_total, None)

Default Value

0

Remarks

The total number of messages in the sequence and will remain constant in the sequence of messages.

This property is read-only.

operation_info_severity Property

Indicates the importance/severity level of the operational information.

Syntax

def get_operation_info_severity() -> str: ...

operation_info_severity = property(get_operation_info_severity, None)

Default Value

""

Remarks

Indicates the importance/severity level of the operational information.

This property is read-only.

proxy_auth_scheme Property

The type of authorization to perform when connecting to the proxy.

Syntax

def get_proxy_auth_scheme() -> int: ...
def set_proxy_auth_scheme(value: int) -> None: ...

proxy_auth_scheme = property(get_proxy_auth_scheme, set_proxy_auth_scheme)

Default Value

0

Remarks

The type of authorization to perform when connecting to the proxy. This is used only when the proxy_user and proxy_password properties are set.

proxy_auth_scheme should be set to authNone (3) when no authentication is expected.

By default, proxy_auth_scheme is authBasic (0), and if the proxy_user and proxy_password properties are set, the class will attempt basic authentication.

If proxy_auth_scheme is set to authDigest (1), digest authentication will be attempted instead.

If proxy_auth_scheme is set to authProprietary (2), then the authorization token will not be generated by the class. Look at the configuration file for the class being used to find more information about manually setting this token.

If proxy_auth_scheme is set to authNtlm (4), NTLM authentication will be used.

For security reasons, setting this property will clear the values of proxy_user and proxy_password.

proxy_auto_detect Property

Whether to automatically detect and use proxy system settings, if available.

Syntax

def get_proxy_auto_detect() -> bool: ...
def set_proxy_auto_detect(value: bool) -> None: ...

proxy_auto_detect = property(get_proxy_auto_detect, set_proxy_auto_detect)

Default Value

FALSE

Remarks

Whether to automatically detect and use proxy system settings, if available. The default value is False.

proxy_password Property

A password if authentication is to be used for the proxy.

Syntax

def get_proxy_password() -> str: ...
def set_proxy_password(value: str) -> None: ...

proxy_password = property(get_proxy_password, set_proxy_password)

Default Value

""

Remarks

A password if authentication is to be used for the proxy.

If proxy_auth_scheme is set to Basic Authentication, the proxy_user and proxy_password properties are Base64 encoded and the proxy authentication token will be generated in the form Basic [encoded-user-password].

If proxy_auth_scheme is set to Digest Authentication, the proxy_user and proxy_password properties are used to respond to the Digest Authentication challenge from the server.

If proxy_auth_scheme is set to NTLM Authentication, the proxy_user and proxy_password properties are used to authenticate through NTLM negotiation.

proxy_port Property

The Transmission Control Protocol (TCP) port for the proxy Server (default 80).

Syntax

def get_proxy_port() -> int: ...
def set_proxy_port(value: int) -> None: ...

proxy_port = property(get_proxy_port, set_proxy_port)

Default Value

80

Remarks

The Transmission Control Protocol (TCP) port for the proxy proxy_server (default 80). See the description of the proxy_server property for details.

proxy_server Property

If a proxy Server is given, then the HTTP request is sent to the proxy instead of the server otherwise specified.

Syntax

def get_proxy_server() -> str: ...
def set_proxy_server(value: str) -> None: ...

proxy_server = property(get_proxy_server, set_proxy_server)

Default Value

""

Remarks

If a proxy proxy_server is given, then the HTTP request is sent to the proxy instead of the server otherwise specified.

If the proxy_server property is set to a domain name, a DNS request is initiated. Upon successful termination of the request, the proxy_server property is set to the corresponding address. If the search is not successful, an error is returned.

proxy_ssl Property

When to use a Secure Sockets Layer (SSL) for the connection to the proxy.

Syntax

def get_proxy_ssl() -> int: ...
def set_proxy_ssl(value: int) -> None: ...

proxy_ssl = property(get_proxy_ssl, set_proxy_ssl)

Default Value

0

Remarks

When to use a Secure Sockets Layer (SSL) for the connection to the proxy. The applicable values are as follows:

proxy_user Property

A username if authentication is to be used for the proxy.

Syntax

def get_proxy_user() -> str: ...
def set_proxy_user(value: str) -> None: ...

proxy_user = property(get_proxy_user, set_proxy_user)

Default Value

""

Remarks

A username if authentication is to be used for the proxy.

If proxy_auth_scheme is set to Basic Authentication, the proxy_user and proxy_password properties are Base64 encoded and the proxy authentication token will be generated in the form Basic [encoded-user-password].

If proxy_auth_scheme is set to Digest Authentication, the proxy_user and proxy_password properties are used to respond to the Digest Authentication challenge from the server.

If proxy_auth_scheme is set to NTLM Authentication, the proxy_user and proxy_password properties are used to authenticate through NTLM negotiation.

purchase_amount Property

Purchase amount to be authorized.

Syntax

def get_purchase_amount() -> str: ...
def set_purchase_amount(value: str) -> None: ...

purchase_amount = property(get_purchase_amount, set_purchase_amount)

Default Value

""

Remarks

This field contains the purchase amount to be authorized. The transaction amount is to be presented with an implied decimal point. For example, US $10.00 must be represented as 1000, and $0.10 is likewise simply 10. The allowable number of significant digits as well as the positioning of any implied decimal point is dictated by the designated purchase_exponent. This field may not contain a negative number.

purchase_currency Property

Identifies the type of currency used by the merchant.

Syntax

def get_purchase_currency() -> str: ...
def set_purchase_currency(value: str) -> None: ...

purchase_currency = property(get_purchase_currency, set_purchase_currency)

Default Value

"840"

Remarks

This field contains the three digit number assigned by the signing member or processor to identify the currency in which purchase_currency is expressed. This property should contain the ISO-4217 numeric code. For example, the ISO code for US Dollars is "840".

purchase_date Property

The date of the transaction.

Syntax

def get_purchase_date() -> str: ...
def set_purchase_date(value: str) -> None: ...

purchase_date = property(get_purchase_date, set_purchase_date)

Default Value

""

Remarks

This field contains the date and time of the purchase, expressed in UTC. The format of this field must be: YYYYMMDDHHMMSS

purchase_exponent Property

Minor units of currency.

Syntax

def get_purchase_exponent() -> str: ...
def set_purchase_exponent(value: str) -> None: ...

purchase_exponent = property(get_purchase_exponent, set_purchase_exponent)

Default Value

"2"

Remarks

This field indicates the minor units, or number of decimal places, of the currency specified in the purchase_currency property. For instance, the Japanese Yen has a value of "0", the US Dollar a value of "2", and the Kuwati Dinar a value of "3".

range_count Property

The number of records in the Range arrays.

Syntax

def get_range_count() -> int: ...

range_count = property(get_range_count, None)

Default Value

0

Remarks

This property controls the size of the following arrays:

• range_end
• range_start

The array indices start at 0 and end at range_count - 1.

This property is read-only.

range_end Property

The final card number in the current range.

Syntax

def get_range_end(range_index: int) -> str: ...

Default Value

""

Remarks

The final card number in the current range.

The range_index parameter specifies the index of the item in the array. The size of the array is controlled by the range_count property.

This property is read-only.

range_start Property

The first card number in the current range.

Syntax

def get_range_start(range_index: int) -> str: ...

Default Value

""

Remarks

The first card number in the current range.

The range_index parameter specifies the index of the item in the array. The size of the array is controlled by the range_count property.

This property is read-only.

recurring_exp_date Property

Recurring expiration date.

Syntax

def get_recurring_exp_date() -> str: ...
def set_recurring_exp_date(value: str) -> None: ...

recurring_exp_date = property(get_recurring_exp_date, set_recurring_exp_date)

Default Value

""

Remarks

This field contains the date after which no further authorizations shall be performed. The format of this field must be: YYYYMMDD

Required when authentication_indicator is 02 or 03, or when ThreeRIIndicator is 01 or 02.

recurring_frequency Property

The number of days between recurring payments.

Syntax

def get_recurring_frequency() -> str: ...
def set_recurring_frequency(value: str) -> None: ...

recurring_frequency = property(get_recurring_frequency, set_recurring_frequency)

Default Value

""

Remarks

This field indicates the minimum number of days between authorizations.

Required when authentication_indicator is 02 or 03, or when ThreeRIIndicator is 01 or 02.

requestor_id Property

Directory server assigned 3DS Requestor identifier.

Syntax

def get_requestor_id() -> str: ...
def set_requestor_id(value: str) -> None: ...

requestor_id = property(get_requestor_id, set_requestor_id)

Default Value

""

Remarks

This field contains the 3DS Requestor identifier as assigned by the directory server. This is sent in the Authentication Request Message (AReq) sent by the component in the send_auth_request method.

requestor_name Property

Directory server assigned 3DS Requestor name.

Syntax

def get_requestor_name() -> str: ...
def set_requestor_name(value: str) -> None: ...

requestor_name = property(get_requestor_name, set_requestor_name)

Default Value

""

Remarks

This field contains the 3DS Requestor name as assigned by the directory server. This is sent in the Authentication Request Message (AReq) sent by the component in the send_auth_request method.

requestor_url Property

3DS Requestor website or customer care site.

Syntax

def get_requestor_url() -> str: ...
def set_requestor_url(value: str) -> None: ...

requestor_url = property(get_requestor_url, set_requestor_url)

Default Value

""

Remarks

This field contains the fully qualified URL of the 3DS Requestor website or customer care site. This is sent in the Authentication Request Message (AReq) sent by the component in the send_auth_request method.

results_status Property

The status of the Results Request.

Syntax

def get_results_status() -> int: ...
def set_results_status(value: int) -> None: ...

results_status = property(get_results_status, set_results_status)

Default Value

0

Remarks

This field contains the status of the results request and is used when generating the Results Response Message (RRes) via the get_results_response method. This will indicate if the message was successfully received for further processing or provide more detail to the ACS on why the challenge could not be completed.

Possible values include:

Before calling get_results_response, the Server can use the value of the RequestorChallengeInd to determine whether or not a value of 02 is appropriate. It must use the necessary error handling logic when processing ARes messages to determine whether or not a value of 03 is appropriate.

If the transaction_status is D and a DecoupledRequestIndicator value of F or B was used, results_status should be set to 04 and a separate 3RI authentication should be initiated within 60 seconds.

results_url Property

3DS Server URL.

Syntax

def get_results_url() -> str: ...
def set_results_url(value: str) -> None: ...

results_url = property(get_results_url, set_results_url)

Default Value

""

Remarks

Full qualified URL of the 3DS Server to which the directory server will send the Results Request Message (RReq) after the challenge has completed. This is sent to the directory server when calling the send_auth_request method.

sdk_type Property

Type of the 3DS SDK used for the app-based flow.

Syntax

def get_sdk_type() -> str: ...
def set_sdk_type(value: str) -> None: ...

sdk_type = property(get_sdk_type, set_sdk_type)

Default Value

"01"

Remarks

Indicates the type of 3DS SDK. This provides additional information to the DS and ACS to determine the best approach for handling the transaction.

Valid values are:

When Default-SDK is selected (01), SDKWrapped can be used to indicate if the Default-SDK is embedded as a wrapped component in the 3DS Requestor App.

When Split-SDK is selected (02), SplitSDKVariant will indicate the implementation charactistics of the Split-SDK client, and SplitSDKLimited can be used to indicate if the Split-SDK client has limited capabilities.

This property is valid for message_version 2.3.1 only.

serial_number Property

Serial number indicating the state of the current card range cache.

Syntax

def get_serial_number() -> str: ...
def set_serial_number(value: str) -> None: ...

serial_number = property(get_serial_number, set_serial_number)

Default Value

""

Remarks

If this element is present when submitting a Preparation Request Message (PReq) with the request_card_ranges method, the directory server returns card ranges that have been updated since the time of the response which returned this serial number. If this element is not present, the directory server returns all card ranges. This field is updated with a new serial number after each call to request_card_ranges.

server_transaction_id Property

Server transaction identifier.

Syntax

def get_server_transaction_id() -> str: ...
def set_server_transaction_id(value: str) -> None: ...

server_transaction_id = property(get_server_transaction_id, set_server_transaction_id)

Default Value

""

Remarks

Universally unique transaction identifier assigned by the 3DS Server to identify a single transaction. This value is generated by the class when get_method_data or send_auth_request is called.

shipping_address_city Property

The city of the address.

Syntax

def get_shipping_address_city() -> str: ...
def set_shipping_address_city(value: str) -> None: ...

shipping_address_city = property(get_shipping_address_city, set_shipping_address_city)

Default Value

""

Remarks

The city of the address. The maximum length is 50 characters.

shipping_address_country Property

The country of the address.

Syntax

def get_shipping_address_country() -> str: ...
def set_shipping_address_country(value: str) -> None: ...

shipping_address_country = property(get_shipping_address_country, set_shipping_address_country)

Default Value

""

Remarks

The country of the address. The format is a 3 digit country code as defined in ISO 3166-1.

shipping_address_line1 Property

The first line of the street address or equivalent local portion of the address.

Syntax

def get_shipping_address_line1() -> str: ...
def set_shipping_address_line1(value: str) -> None: ...

shipping_address_line1 = property(get_shipping_address_line1, set_shipping_address_line1)

Default Value

""

Remarks

The first line of the street address or equivalent local portion of the address. The maximum length is 50 characters.

shipping_address_line2 Property

The second line of the street address or equivalent local portion of the address.

Syntax

def get_shipping_address_line2() -> str: ...
def set_shipping_address_line2(value: str) -> None: ...

shipping_address_line2 = property(get_shipping_address_line2, set_shipping_address_line2)

Default Value

""

Remarks

The second line of the street address or equivalent local portion of the address. The maximum length is 50 characters.

shipping_address_line3 Property

The third line of the street address or equivalent local portion of the address.

Syntax

def get_shipping_address_line3() -> str: ...
def set_shipping_address_line3(value: str) -> None: ...

shipping_address_line3 = property(get_shipping_address_line3, set_shipping_address_line3)

Default Value

""

Remarks

The third line of the street address or equivalent local portion of the address. The maximum length is 50 characters.

shipping_address_postal_code Property

The ZIP or other postal code of the address.

Syntax

def get_shipping_address_postal_code() -> str: ...
def set_shipping_address_postal_code(value: str) -> None: ...

shipping_address_postal_code = property(get_shipping_address_postal_code, set_shipping_address_postal_code)

Default Value

""

Remarks

The ZIP or other postal code of the address. The maximum length is 16 characters.

shipping_address_state Property

The state or province of the address.

Syntax

def get_shipping_address_state() -> str: ...
def set_shipping_address_state(value: str) -> None: ...

shipping_address_state = property(get_shipping_address_state, set_shipping_address_state)

Default Value

""

Remarks

The state or province of the address. The maximum length is 3 characters and should be the country subdivision code defined in ISO 3166-2.

ssl_accept_server_cert_effective_date Property

The date on which this certificate becomes valid.

Syntax

def get_ssl_accept_server_cert_effective_date() -> str: ...

ssl_accept_server_cert_effective_date = property(get_ssl_accept_server_cert_effective_date, None)

Default Value

""

Remarks

The date on which this certificate becomes valid. Before this date, it is not valid. The date is localized to the system's time zone. The following example illustrates the format of an encoded date:

23-Jan-2000 15:00:00.

This property is read-only.

ssl_accept_server_cert_expiration_date Property

The date on which the certificate expires.

Syntax

def get_ssl_accept_server_cert_expiration_date() -> str: ...

ssl_accept_server_cert_expiration_date = property(get_ssl_accept_server_cert_expiration_date, None)

Default Value

""

Remarks

The date on which the certificate expires. After this date, the certificate will no longer be valid. The date is localized to the system's time zone. The following example illustrates the format of an encoded date:

23-Jan-2001 15:00:00.

This property is read-only.

ssl_accept_server_cert_extended_key_usage Property

A comma-delimited list of extended key usage identifiers.

Syntax

def get_ssl_accept_server_cert_extended_key_usage() -> str: ...

ssl_accept_server_cert_extended_key_usage = property(get_ssl_accept_server_cert_extended_key_usage, None)

Default Value

""

Remarks

A comma-delimited list of extended key usage identifiers. These are the same as ASN.1 object identifiers (OIDs).

This property is read-only.

ssl_accept_server_cert_fingerprint Property

The hex-encoded, 16-byte MD5 fingerprint of the certificate.

Syntax

def get_ssl_accept_server_cert_fingerprint() -> str: ...

ssl_accept_server_cert_fingerprint = property(get_ssl_accept_server_cert_fingerprint, None)

Default Value

""

Remarks

The hex-encoded, 16-byte MD5 fingerprint of the certificate. This property is primarily used for keys which do not have a corresponding X.509 public certificate, such as PEM keys that only contain a private key. It is commonly used for SSH keys.

The following example illustrates the format: bc:2a:72:af:fe:58:17:43:7a:5f:ba:5a:7c:90:f7:02

This property is read-only.

ssl_accept_server_cert_fingerprint_sha1 Property

The hex-encoded, 20-byte SHA-1 fingerprint of the certificate.

Syntax

def get_ssl_accept_server_cert_fingerprint_sha1() -> str: ...

ssl_accept_server_cert_fingerprint_sha1 = property(get_ssl_accept_server_cert_fingerprint_sha1, None)

Default Value

""

Remarks

The hex-encoded, 20-byte SHA-1 fingerprint of the certificate. This property is primarily used for keys which do not have a corresponding X.509 public certificate, such as PEM keys that only contain a private key. It is commonly used for SSH keys.

The following example illustrates the format: 30:7b:fa:38:65:83:ff:da:b4:4e:07:3f:17:b8:a4:ed:80:be:ff:84

This property is read-only.

ssl_accept_server_cert_fingerprint_sha256 Property

The hex-encoded, 32-byte SHA-256 fingerprint of the certificate.

Syntax

def get_ssl_accept_server_cert_fingerprint_sha256() -> str: ...

ssl_accept_server_cert_fingerprint_sha256 = property(get_ssl_accept_server_cert_fingerprint_sha256, None)

Default Value

""

Remarks

The hex-encoded, 32-byte SHA-256 fingerprint of the certificate. This property is primarily used for keys which do not have a corresponding X.509 public certificate, such as PEM keys that only contain a private key. It is commonly used for SSH keys.

The following example illustrates the format: 6a:80:5c:33:a9:43:ea:b0:96:12:8a:64:96:30:ef:4a:8a:96:86:ce:f4:c7:be:10:24:8e:2b:60:9e:f3:59:53

This property is read-only.

ssl_accept_server_cert_issuer Property

The issuer of the certificate.

Syntax

def get_ssl_accept_server_cert_issuer() -> str: ...

ssl_accept_server_cert_issuer = property(get_ssl_accept_server_cert_issuer, None)

Default Value

""

Remarks

The issuer of the certificate. This property contains a string representation of the name of the issuing authority for the certificate.

This property is read-only.

ssl_accept_server_cert_private_key Property

The private key of the certificate (if available).

Syntax

def get_ssl_accept_server_cert_private_key() -> str: ...

ssl_accept_server_cert_private_key = property(get_ssl_accept_server_cert_private_key, None)

Default Value

""

Remarks

The private key of the certificate (if available). The key is provided as PEM/Base64-encoded data.

Note: The ssl_accept_server_cert_private_key may be available but not exportable. In this case, ssl_accept_server_cert_private_key returns an empty string.

This property is read-only.

ssl_accept_server_cert_private_key_available Property

Whether a PrivateKey is available for the selected certificate.

Syntax

def get_ssl_accept_server_cert_private_key_available() -> bool: ...

ssl_accept_server_cert_private_key_available = property(get_ssl_accept_server_cert_private_key_available, None)

Default Value

FALSE

Remarks

Whether a ssl_accept_server_cert_private_key is available for the selected certificate. If ssl_accept_server_cert_private_key_available is True, the certificate may be used for authentication purposes (e.g., server authentication).

This property is read-only.

ssl_accept_server_cert_private_key_container Property

The name of the PrivateKey container for the certificate (if available).

Syntax

def get_ssl_accept_server_cert_private_key_container() -> str: ...

ssl_accept_server_cert_private_key_container = property(get_ssl_accept_server_cert_private_key_container, None)

Default Value

""

Remarks

The name of the ssl_accept_server_cert_private_key container for the certificate (if available). This functionality is available only on Windows platforms.

This property is read-only.

ssl_accept_server_cert_public_key Property

The public key of the certificate.

Syntax

def get_ssl_accept_server_cert_public_key() -> str: ...

ssl_accept_server_cert_public_key = property(get_ssl_accept_server_cert_public_key, None)

Default Value

""

Remarks

The public key of the certificate. The key is provided as PEM/Base64-encoded data.

This property is read-only.

ssl_accept_server_cert_public_key_algorithm Property

The textual description of the certificate's public key algorithm.

Syntax

def get_ssl_accept_server_cert_public_key_algorithm() -> str: ...

ssl_accept_server_cert_public_key_algorithm = property(get_ssl_accept_server_cert_public_key_algorithm, None)

Default Value

""

Remarks

The textual description of the certificate's public key algorithm. The property contains either the name of the algorithm (e.g., "RSA" or "RSA_DH") or an object identifier (OID) string representing the algorithm.

This property is read-only.

ssl_accept_server_cert_public_key_length Property

The length of the certificate's public key (in bits).

Syntax

def get_ssl_accept_server_cert_public_key_length() -> int: ...

ssl_accept_server_cert_public_key_length = property(get_ssl_accept_server_cert_public_key_length, None)

Default Value

0

Remarks

The length of the certificate's public key (in bits). Common values are 512, 1024, and 2048.

This property is read-only.

ssl_accept_server_cert_serial_number Property

The serial number of the certificate encoded as a string.

Syntax

def get_ssl_accept_server_cert_serial_number() -> str: ...

ssl_accept_server_cert_serial_number = property(get_ssl_accept_server_cert_serial_number, None)

Default Value

""

Remarks

The serial number of the certificate encoded as a string. The number is encoded as a series of hexadecimal digits, with each pair representing a byte of the serial number.

This property is read-only.

ssl_accept_server_cert_signature_algorithm Property

The text description of the certificate's signature algorithm.

Syntax

def get_ssl_accept_server_cert_signature_algorithm() -> str: ...

ssl_accept_server_cert_signature_algorithm = property(get_ssl_accept_server_cert_signature_algorithm, None)

Default Value

""

Remarks

The text description of the certificate's signature algorithm. The property contains either the name of the algorithm (e.g., "RSA" or "RSA_MD5RSA") or an object identifier (OID) string representing the algorithm.

This property is read-only.

ssl_accept_server_cert_store Property

The name of the certificate store for the client certificate.

Syntax

def get_ssl_accept_server_cert_store() -> bytes: ...
def set_ssl_accept_server_cert_store(value: bytes) -> None: ...

ssl_accept_server_cert_store = property(get_ssl_accept_server_cert_store, set_ssl_accept_server_cert_store)

Default Value

"MY"

Remarks

The name of the certificate store for the client certificate.

The ssl_accept_server_cert_store_type property denotes the type of the certificate store specified by ssl_accept_server_cert_store. If the store is password-protected, specify the password in ssl_accept_server_cert_store_password.

ssl_accept_server_cert_store is used in conjunction with the ssl_accept_server_cert_subject property to specify client certificates. If ssl_accept_server_cert_store has a value, and ssl_accept_server_cert_subject or ssl_accept_server_cert_encoded is set, a search for a certificate is initiated. Please see the ssl_accept_server_cert_subject property for details.

Designations of certificate stores are platform dependent.

The following designations are the most common User and Machine certificate stores in Windows:

When the certificate store type is cstPFXFile, this property must be set to the name of the file. When the type is cstPFXBlob, the property must be set to the binary contents of a PFX file (i.e., PKCS#12 certificate store).

ssl_accept_server_cert_store_password Property

If the type of certificate store requires a password, this property is used to specify the password needed to open the certificate store.

Syntax

def get_ssl_accept_server_cert_store_password() -> str: ...
def set_ssl_accept_server_cert_store_password(value: str) -> None: ...

ssl_accept_server_cert_store_password = property(get_ssl_accept_server_cert_store_password, set_ssl_accept_server_cert_store_password)

Default Value

""

Remarks

If the type of certificate store requires a password, this property is used to specify the password needed to open the certificate store.

ssl_accept_server_cert_store_type Property

The type of certificate store for this certificate.

Syntax

def get_ssl_accept_server_cert_store_type() -> int: ...
def set_ssl_accept_server_cert_store_type(value: int) -> None: ...

ssl_accept_server_cert_store_type = property(get_ssl_accept_server_cert_store_type, set_ssl_accept_server_cert_store_type)

Default Value

0

Remarks

The type of certificate store for this certificate.

The class supports both public and private keys in a variety of formats. When the cstAuto value is used, the class will automatically determine the type. This property can take one of the following values:

ssl_accept_server_cert_subject_alt_names Property

Comma-separated lists of alternative subject names for the certificate.

Syntax

def get_ssl_accept_server_cert_subject_alt_names() -> str: ...

ssl_accept_server_cert_subject_alt_names = property(get_ssl_accept_server_cert_subject_alt_names, None)

Default Value

""

Remarks

Comma-separated lists of alternative subject names for the certificate.

This property is read-only.

ssl_accept_server_cert_thumbprint_md5 Property

The MD5 hash of the certificate.

Syntax

def get_ssl_accept_server_cert_thumbprint_md5() -> str: ...

ssl_accept_server_cert_thumbprint_md5 = property(get_ssl_accept_server_cert_thumbprint_md5, None)

Default Value

""

Remarks

The MD5 hash of the certificate. It is primarily used for X.509 certificates. If the hash does not already exist, it is automatically computed.

This property is read-only.

ssl_accept_server_cert_thumbprint_sha1 Property

The SHA-1 hash of the certificate.

Syntax

def get_ssl_accept_server_cert_thumbprint_sha1() -> str: ...

ssl_accept_server_cert_thumbprint_sha1 = property(get_ssl_accept_server_cert_thumbprint_sha1, None)

Default Value

""

Remarks

The SHA-1 hash of the certificate. It is primarily used for X.509 certificates. If the hash does not already exist, it is automatically computed.

This property is read-only.

ssl_accept_server_cert_thumbprint_sha256 Property

The SHA-256 hash of the certificate.

Syntax

def get_ssl_accept_server_cert_thumbprint_sha256() -> str: ...

ssl_accept_server_cert_thumbprint_sha256 = property(get_ssl_accept_server_cert_thumbprint_sha256, None)

Default Value

""

Remarks

The SHA-256 hash of the certificate. It is primarily used for X.509 certificates. If the hash does not already exist, it is automatically computed.

This property is read-only.

ssl_accept_server_cert_usage Property

The text description of UsageFlags .

Syntax

def get_ssl_accept_server_cert_usage() -> str: ...

ssl_accept_server_cert_usage = property(get_ssl_accept_server_cert_usage, None)

Default Value

""

Remarks

The text description of ssl_accept_server_cert_usage_flags.

This value will be one or more of the following strings and will be separated by commas:

• Digital Signature
• Non-Repudiation
• Key Encipherment
• Data Encipherment
• Key Agreement
• Certificate Signing
• CRL Signing
• Encipher Only

If the provider is OpenSSL, the value is a comma-separated list of X.509 certificate extension names.

This property is read-only.

ssl_accept_server_cert_usage_flags Property

The flags that show intended use for the certificate.

Syntax

def get_ssl_accept_server_cert_usage_flags() -> int: ...

ssl_accept_server_cert_usage_flags = property(get_ssl_accept_server_cert_usage_flags, None)

Default Value

0

Remarks

The flags that show intended use for the certificate. The value of ssl_accept_server_cert_usage_flags is a combination of the following flags:

Please see the ssl_accept_server_cert_usage property for a text representation of ssl_accept_server_cert_usage_flags.

This functionality currently is not available when the provider is OpenSSL.

This property is read-only.

ssl_accept_server_cert_version Property

The certificate's version number.

Syntax

def get_ssl_accept_server_cert_version() -> str: ...

ssl_accept_server_cert_version = property(get_ssl_accept_server_cert_version, None)

Default Value

""

Remarks

The certificate's version number. The possible values are the strings "V1", "V2", and "V3".

This property is read-only.

ssl_accept_server_cert_subject Property

The subject of the certificate used for client authentication.

Syntax

def get_ssl_accept_server_cert_subject() -> str: ...
def set_ssl_accept_server_cert_subject(value: str) -> None: ...

ssl_accept_server_cert_subject = property(get_ssl_accept_server_cert_subject, set_ssl_accept_server_cert_subject)

Default Value

""

Remarks

The subject of the certificate used for client authentication.

This property must be set after all other certificate properties are set. When this property is set, a search is performed in the current certificate store to locate a certificate with a matching subject.

If a matching certificate is found, the property is set to the full subject of the matching certificate.

If an exact match is not found, the store is searched for subjects containing the value of the property.

If a match is still not found, the property is set to an empty string, and no certificate is selected.

The special value "*" picks a random certificate in the certificate store.

The certificate subject is a comma-separated list of distinguished name fields and values. For instance, "CN=www.server.com, OU=test, C=US, E=support@nsoftware.com". Common fields and their meanings are as follows:

If a field value contains a comma, it must be quoted.

ssl_accept_server_cert_encoded Property

The certificate (PEM/Base64 encoded).

Syntax

def get_ssl_accept_server_cert_encoded() -> bytes: ...
def set_ssl_accept_server_cert_encoded(value: bytes) -> None: ...

ssl_accept_server_cert_encoded = property(get_ssl_accept_server_cert_encoded, set_ssl_accept_server_cert_encoded)

Default Value

""

Remarks

The certificate (PEM/Base64 encoded). This property is used to assign a specific certificate. The ssl_accept_server_cert_store and ssl_accept_server_cert_subject properties also may be used to specify a certificate.

When ssl_accept_server_cert_encoded is set, a search is initiated in the current ssl_accept_server_cert_store for the private key of the certificate. If the key is found, ssl_accept_server_cert_subject is updated to reflect the full subject of the selected certificate; otherwise, ssl_accept_server_cert_subject is set to an empty string.

ssl_cert_effective_date Property

The date on which this certificate becomes valid.

Syntax

def get_ssl_cert_effective_date() -> str: ...

ssl_cert_effective_date = property(get_ssl_cert_effective_date, None)

Default Value

""

Remarks

The date on which this certificate becomes valid. Before this date, it is not valid. The date is localized to the system's time zone. The following example illustrates the format of an encoded date:

23-Jan-2000 15:00:00.

This property is read-only.

ssl_cert_expiration_date Property

The date on which the certificate expires.

Syntax

def get_ssl_cert_expiration_date() -> str: ...

ssl_cert_expiration_date = property(get_ssl_cert_expiration_date, None)

Default Value

""

Remarks

The date on which the certificate expires. After this date, the certificate will no longer be valid. The date is localized to the system's time zone. The following example illustrates the format of an encoded date:

23-Jan-2001 15:00:00.

This property is read-only.

ssl_cert_extended_key_usage Property

A comma-delimited list of extended key usage identifiers.

Syntax

def get_ssl_cert_extended_key_usage() -> str: ...

ssl_cert_extended_key_usage = property(get_ssl_cert_extended_key_usage, None)

Default Value

""

Remarks

A comma-delimited list of extended key usage identifiers. These are the same as ASN.1 object identifiers (OIDs).

This property is read-only.

ssl_cert_fingerprint Property

The hex-encoded, 16-byte MD5 fingerprint of the certificate.

Syntax

def get_ssl_cert_fingerprint() -> str: ...

ssl_cert_fingerprint = property(get_ssl_cert_fingerprint, None)

Default Value

""

Remarks

The hex-encoded, 16-byte MD5 fingerprint of the certificate. This property is primarily used for keys which do not have a corresponding X.509 public certificate, such as PEM keys that only contain a private key. It is commonly used for SSH keys.

The following example illustrates the format: bc:2a:72:af:fe:58:17:43:7a:5f:ba:5a:7c:90:f7:02

This property is read-only.

ssl_cert_fingerprint_sha1 Property

The hex-encoded, 20-byte SHA-1 fingerprint of the certificate.

Syntax

def get_ssl_cert_fingerprint_sha1() -> str: ...

ssl_cert_fingerprint_sha1 = property(get_ssl_cert_fingerprint_sha1, None)

Default Value

""

Remarks

The hex-encoded, 20-byte SHA-1 fingerprint of the certificate. This property is primarily used for keys which do not have a corresponding X.509 public certificate, such as PEM keys that only contain a private key. It is commonly used for SSH keys.

The following example illustrates the format: 30:7b:fa:38:65:83:ff:da:b4:4e:07:3f:17:b8:a4:ed:80:be:ff:84

This property is read-only.

ssl_cert_fingerprint_sha256 Property

The hex-encoded, 32-byte SHA-256 fingerprint of the certificate.

Syntax

def get_ssl_cert_fingerprint_sha256() -> str: ...

ssl_cert_fingerprint_sha256 = property(get_ssl_cert_fingerprint_sha256, None)

Default Value

""

Remarks

The hex-encoded, 32-byte SHA-256 fingerprint of the certificate. This property is primarily used for keys which do not have a corresponding X.509 public certificate, such as PEM keys that only contain a private key. It is commonly used for SSH keys.

The following example illustrates the format: 6a:80:5c:33:a9:43:ea:b0:96:12:8a:64:96:30:ef:4a:8a:96:86:ce:f4:c7:be:10:24:8e:2b:60:9e:f3:59:53

This property is read-only.

ssl_cert_issuer Property

The issuer of the certificate.

Syntax

def get_ssl_cert_issuer() -> str: ...

ssl_cert_issuer = property(get_ssl_cert_issuer, None)

Default Value

""

Remarks

The issuer of the certificate. This property contains a string representation of the name of the issuing authority for the certificate.

This property is read-only.

ssl_cert_private_key Property

The private key of the certificate (if available).

Syntax

def get_ssl_cert_private_key() -> str: ...

ssl_cert_private_key = property(get_ssl_cert_private_key, None)

Default Value

""

Remarks

The private key of the certificate (if available). The key is provided as PEM/Base64-encoded data.

Note: The ssl_cert_private_key may be available but not exportable. In this case, ssl_cert_private_key returns an empty string.

This property is read-only.

ssl_cert_private_key_available Property

Whether a PrivateKey is available for the selected certificate.

Syntax

def get_ssl_cert_private_key_available() -> bool: ...

ssl_cert_private_key_available = property(get_ssl_cert_private_key_available, None)

Default Value

FALSE

Remarks

Whether a ssl_cert_private_key is available for the selected certificate. If ssl_cert_private_key_available is True, the certificate may be used for authentication purposes (e.g., server authentication).

This property is read-only.

ssl_cert_private_key_container Property

The name of the PrivateKey container for the certificate (if available).

Syntax

def get_ssl_cert_private_key_container() -> str: ...

ssl_cert_private_key_container = property(get_ssl_cert_private_key_container, None)

Default Value

""

Remarks

The name of the ssl_cert_private_key container for the certificate (if available). This functionality is available only on Windows platforms.

This property is read-only.

ssl_cert_public_key Property

The public key of the certificate.

Syntax

def get_ssl_cert_public_key() -> str: ...

ssl_cert_public_key = property(get_ssl_cert_public_key, None)

Default Value

""

Remarks

The public key of the certificate. The key is provided as PEM/Base64-encoded data.

This property is read-only.

ssl_cert_public_key_algorithm Property

The textual description of the certificate's public key algorithm.

Syntax

def get_ssl_cert_public_key_algorithm() -> str: ...

ssl_cert_public_key_algorithm = property(get_ssl_cert_public_key_algorithm, None)

Default Value

""

Remarks

The textual description of the certificate's public key algorithm. The property contains either the name of the algorithm (e.g., "RSA" or "RSA_DH") or an object identifier (OID) string representing the algorithm.

This property is read-only.

ssl_cert_public_key_length Property

The length of the certificate's public key (in bits).

Syntax

def get_ssl_cert_public_key_length() -> int: ...

ssl_cert_public_key_length = property(get_ssl_cert_public_key_length, None)

Default Value

0

Remarks

The length of the certificate's public key (in bits). Common values are 512, 1024, and 2048.

This property is read-only.

ssl_cert_serial_number Property

The serial number of the certificate encoded as a string.

Syntax

def get_ssl_cert_serial_number() -> str: ...

ssl_cert_serial_number = property(get_ssl_cert_serial_number, None)

Default Value

""

Remarks

The serial number of the certificate encoded as a string. The number is encoded as a series of hexadecimal digits, with each pair representing a byte of the serial number.

This property is read-only.

ssl_cert_signature_algorithm Property

The text description of the certificate's signature algorithm.

Syntax

def get_ssl_cert_signature_algorithm() -> str: ...

ssl_cert_signature_algorithm = property(get_ssl_cert_signature_algorithm, None)

Default Value

""

Remarks

The text description of the certificate's signature algorithm. The property contains either the name of the algorithm (e.g., "RSA" or "RSA_MD5RSA") or an object identifier (OID) string representing the algorithm.

This property is read-only.

ssl_cert_store Property

The name of the certificate store for the client certificate.

Syntax

def get_ssl_cert_store() -> bytes: ...
def set_ssl_cert_store(value: bytes) -> None: ...

ssl_cert_store = property(get_ssl_cert_store, set_ssl_cert_store)

Default Value

"MY"

Remarks

The name of the certificate store for the client certificate.

The ssl_cert_store_type property denotes the type of the certificate store specified by ssl_cert_store. If the store is password-protected, specify the password in ssl_cert_store_password.

ssl_cert_store is used in conjunction with the ssl_cert_subject property to specify client certificates. If ssl_cert_store has a value, and ssl_cert_subject or ssl_cert_encoded is set, a search for a certificate is initiated. Please see the ssl_cert_subject property for details.

Designations of certificate stores are platform dependent.

The following designations are the most common User and Machine certificate stores in Windows:

When the certificate store type is cstPFXFile, this property must be set to the name of the file. When the type is cstPFXBlob, the property must be set to the binary contents of a PFX file (i.e., PKCS#12 certificate store).

ssl_cert_store_password Property

If the type of certificate store requires a password, this property is used to specify the password needed to open the certificate store.

Syntax

def get_ssl_cert_store_password() -> str: ...
def set_ssl_cert_store_password(value: str) -> None: ...

ssl_cert_store_password = property(get_ssl_cert_store_password, set_ssl_cert_store_password)

Default Value

""

Remarks

If the type of certificate store requires a password, this property is used to specify the password needed to open the certificate store.

ssl_cert_store_type Property

The type of certificate store for this certificate.

Syntax

def get_ssl_cert_store_type() -> int: ...
def set_ssl_cert_store_type(value: int) -> None: ...

ssl_cert_store_type = property(get_ssl_cert_store_type, set_ssl_cert_store_type)

Default Value

0

Remarks

The type of certificate store for this certificate.

The class supports both public and private keys in a variety of formats. When the cstAuto value is used, the class will automatically determine the type. This property can take one of the following values:

ssl_cert_subject_alt_names Property

Comma-separated lists of alternative subject names for the certificate.

Syntax

def get_ssl_cert_subject_alt_names() -> str: ...

ssl_cert_subject_alt_names = property(get_ssl_cert_subject_alt_names, None)

Default Value

""

Remarks

Comma-separated lists of alternative subject names for the certificate.

This property is read-only.

ssl_cert_thumbprint_md5 Property

The MD5 hash of the certificate.

Syntax

def get_ssl_cert_thumbprint_md5() -> str: ...

ssl_cert_thumbprint_md5 = property(get_ssl_cert_thumbprint_md5, None)

Default Value

""

Remarks

The MD5 hash of the certificate. It is primarily used for X.509 certificates. If the hash does not already exist, it is automatically computed.

This property is read-only.

ssl_cert_thumbprint_sha1 Property

The SHA-1 hash of the certificate.

Syntax

def get_ssl_cert_thumbprint_sha1() -> str: ...

ssl_cert_thumbprint_sha1 = property(get_ssl_cert_thumbprint_sha1, None)

Default Value

""

Remarks

The SHA-1 hash of the certificate. It is primarily used for X.509 certificates. If the hash does not already exist, it is automatically computed.

This property is read-only.

ssl_cert_thumbprint_sha256 Property

The SHA-256 hash of the certificate.

Syntax

def get_ssl_cert_thumbprint_sha256() -> str: ...

ssl_cert_thumbprint_sha256 = property(get_ssl_cert_thumbprint_sha256, None)

Default Value

""

Remarks

The SHA-256 hash of the certificate. It is primarily used for X.509 certificates. If the hash does not already exist, it is automatically computed.

This property is read-only.

ssl_cert_usage Property

The text description of UsageFlags .

Syntax

def get_ssl_cert_usage() -> str: ...

ssl_cert_usage = property(get_ssl_cert_usage, None)

Default Value

""

Remarks

The text description of ssl_cert_usage_flags.

This value will be one or more of the following strings and will be separated by commas:

• Digital Signature
• Non-Repudiation
• Key Encipherment
• Data Encipherment
• Key Agreement
• Certificate Signing
• CRL Signing
• Encipher Only

If the provider is OpenSSL, the value is a comma-separated list of X.509 certificate extension names.

This property is read-only.

ssl_cert_usage_flags Property

The flags that show intended use for the certificate.

Syntax

def get_ssl_cert_usage_flags() -> int: ...

ssl_cert_usage_flags = property(get_ssl_cert_usage_flags, None)

Default Value

0

Remarks

The flags that show intended use for the certificate. The value of ssl_cert_usage_flags is a combination of the following flags:

Please see the ssl_cert_usage property for a text representation of ssl_cert_usage_flags.

This functionality currently is not available when the provider is OpenSSL.

This property is read-only.

ssl_cert_version Property

The certificate's version number.

Syntax

def get_ssl_cert_version() -> str: ...

ssl_cert_version = property(get_ssl_cert_version, None)

Default Value

""

Remarks

The certificate's version number. The possible values are the strings "V1", "V2", and "V3".

This property is read-only.

ssl_cert_subject Property

The subject of the certificate used for client authentication.

Syntax

def get_ssl_cert_subject() -> str: ...
def set_ssl_cert_subject(value: str) -> None: ...

ssl_cert_subject = property(get_ssl_cert_subject, set_ssl_cert_subject)

Default Value

""

Remarks

The subject of the certificate used for client authentication.

This property must be set after all other certificate properties are set. When this property is set, a search is performed in the current certificate store to locate a certificate with a matching subject.

If a matching certificate is found, the property is set to the full subject of the matching certificate.

If an exact match is not found, the store is searched for subjects containing the value of the property.

If a match is still not found, the property is set to an empty string, and no certificate is selected.

The special value "*" picks a random certificate in the certificate store.

The certificate subject is a comma-separated list of distinguished name fields and values. For instance, "CN=www.server.com, OU=test, C=US, E=support@nsoftware.com". Common fields and their meanings are as follows:

If a field value contains a comma, it must be quoted.

ssl_cert_encoded Property

The certificate (PEM/Base64 encoded).

Syntax

def get_ssl_cert_encoded() -> bytes: ...
def set_ssl_cert_encoded(value: bytes) -> None: ...

ssl_cert_encoded = property(get_ssl_cert_encoded, set_ssl_cert_encoded)

Default Value

""

Remarks

The certificate (PEM/Base64 encoded). This property is used to assign a specific certificate. The ssl_cert_store and ssl_cert_subject properties also may be used to specify a certificate.

When ssl_cert_encoded is set, a search is initiated in the current ssl_cert_store for the private key of the certificate. If the key is found, ssl_cert_subject is updated to reflect the full subject of the selected certificate; otherwise, ssl_cert_subject is set to an empty string.

ssl_server_cert_effective_date Property

The date on which this certificate becomes valid.

Syntax

def get_ssl_server_cert_effective_date() -> str: ...

ssl_server_cert_effective_date = property(get_ssl_server_cert_effective_date, None)

Default Value

""

Remarks

The date on which this certificate becomes valid. Before this date, it is not valid. The date is localized to the system's time zone. The following example illustrates the format of an encoded date:

23-Jan-2000 15:00:00.

This property is read-only.

ssl_server_cert_expiration_date Property

The date on which the certificate expires.

Syntax

def get_ssl_server_cert_expiration_date() -> str: ...

ssl_server_cert_expiration_date = property(get_ssl_server_cert_expiration_date, None)

Default Value

""

Remarks

The date on which the certificate expires. After this date, the certificate will no longer be valid. The date is localized to the system's time zone. The following example illustrates the format of an encoded date:

23-Jan-2001 15:00:00.

This property is read-only.

ssl_server_cert_extended_key_usage Property

A comma-delimited list of extended key usage identifiers.

Syntax

def get_ssl_server_cert_extended_key_usage() -> str: ...

ssl_server_cert_extended_key_usage = property(get_ssl_server_cert_extended_key_usage, None)

Default Value

""

Remarks

A comma-delimited list of extended key usage identifiers. These are the same as ASN.1 object identifiers (OIDs).

This property is read-only.

ssl_server_cert_fingerprint Property

The hex-encoded, 16-byte MD5 fingerprint of the certificate.

Syntax

def get_ssl_server_cert_fingerprint() -> str: ...

ssl_server_cert_fingerprint = property(get_ssl_server_cert_fingerprint, None)

Default Value

""

Remarks

The hex-encoded, 16-byte MD5 fingerprint of the certificate. This property is primarily used for keys which do not have a corresponding X.509 public certificate, such as PEM keys that only contain a private key. It is commonly used for SSH keys.

The following example illustrates the format: bc:2a:72:af:fe:58:17:43:7a:5f:ba:5a:7c:90:f7:02

This property is read-only.

ssl_server_cert_fingerprint_sha1 Property

The hex-encoded, 20-byte SHA-1 fingerprint of the certificate.

Syntax

def get_ssl_server_cert_fingerprint_sha1() -> str: ...

ssl_server_cert_fingerprint_sha1 = property(get_ssl_server_cert_fingerprint_sha1, None)

Default Value

""

Remarks

The hex-encoded, 20-byte SHA-1 fingerprint of the certificate. This property is primarily used for keys which do not have a corresponding X.509 public certificate, such as PEM keys that only contain a private key. It is commonly used for SSH keys.

The following example illustrates the format: 30:7b:fa:38:65:83:ff:da:b4:4e:07:3f:17:b8:a4:ed:80:be:ff:84

This property is read-only.

ssl_server_cert_fingerprint_sha256 Property

The hex-encoded, 32-byte SHA-256 fingerprint of the certificate.

Syntax

def get_ssl_server_cert_fingerprint_sha256() -> str: ...

ssl_server_cert_fingerprint_sha256 = property(get_ssl_server_cert_fingerprint_sha256, None)

Default Value

""

Remarks

The hex-encoded, 32-byte SHA-256 fingerprint of the certificate. This property is primarily used for keys which do not have a corresponding X.509 public certificate, such as PEM keys that only contain a private key. It is commonly used for SSH keys.

The following example illustrates the format: 6a:80:5c:33:a9:43:ea:b0:96:12:8a:64:96:30:ef:4a:8a:96:86:ce:f4:c7:be:10:24:8e:2b:60:9e:f3:59:53

This property is read-only.

ssl_server_cert_issuer Property

The issuer of the certificate.

Syntax

def get_ssl_server_cert_issuer() -> str: ...

ssl_server_cert_issuer = property(get_ssl_server_cert_issuer, None)

Default Value

""

Remarks

The issuer of the certificate. This property contains a string representation of the name of the issuing authority for the certificate.

This property is read-only.

ssl_server_cert_private_key Property

The private key of the certificate (if available).

Syntax

def get_ssl_server_cert_private_key() -> str: ...

ssl_server_cert_private_key = property(get_ssl_server_cert_private_key, None)

Default Value

""

Remarks

The private key of the certificate (if available). The key is provided as PEM/Base64-encoded data.

Note: The ssl_server_cert_private_key may be available but not exportable. In this case, ssl_server_cert_private_key returns an empty string.

This property is read-only.

ssl_server_cert_private_key_available Property

Whether a PrivateKey is available for the selected certificate.

Syntax

def get_ssl_server_cert_private_key_available() -> bool: ...

ssl_server_cert_private_key_available = property(get_ssl_server_cert_private_key_available, None)

Default Value

FALSE

Remarks

Whether a ssl_server_cert_private_key is available for the selected certificate. If ssl_server_cert_private_key_available is True, the certificate may be used for authentication purposes (e.g., server authentication).

This property is read-only.

ssl_server_cert_private_key_container Property

The name of the PrivateKey container for the certificate (if available).

Syntax

def get_ssl_server_cert_private_key_container() -> str: ...

ssl_server_cert_private_key_container = property(get_ssl_server_cert_private_key_container, None)

Default Value

""

Remarks

The name of the ssl_server_cert_private_key container for the certificate (if available). This functionality is available only on Windows platforms.

This property is read-only.

ssl_server_cert_public_key Property

The public key of the certificate.

Syntax

def get_ssl_server_cert_public_key() -> str: ...

ssl_server_cert_public_key = property(get_ssl_server_cert_public_key, None)

Default Value

""

Remarks

The public key of the certificate. The key is provided as PEM/Base64-encoded data.

This property is read-only.

ssl_server_cert_public_key_algorithm Property

The textual description of the certificate's public key algorithm.

Syntax

def get_ssl_server_cert_public_key_algorithm() -> str: ...

ssl_server_cert_public_key_algorithm = property(get_ssl_server_cert_public_key_algorithm, None)

Default Value

""

Remarks

The textual description of the certificate's public key algorithm. The property contains either the name of the algorithm (e.g., "RSA" or "RSA_DH") or an object identifier (OID) string representing the algorithm.

This property is read-only.

ssl_server_cert_public_key_length Property

The length of the certificate's public key (in bits).

Syntax

def get_ssl_server_cert_public_key_length() -> int: ...

ssl_server_cert_public_key_length = property(get_ssl_server_cert_public_key_length, None)

Default Value

0

Remarks

The length of the certificate's public key (in bits). Common values are 512, 1024, and 2048.

This property is read-only.

ssl_server_cert_serial_number Property

The serial number of the certificate encoded as a string.

Syntax

def get_ssl_server_cert_serial_number() -> str: ...

ssl_server_cert_serial_number = property(get_ssl_server_cert_serial_number, None)

Default Value

""

Remarks

The serial number of the certificate encoded as a string. The number is encoded as a series of hexadecimal digits, with each pair representing a byte of the serial number.

This property is read-only.

ssl_server_cert_signature_algorithm Property

The text description of the certificate's signature algorithm.

Syntax

def get_ssl_server_cert_signature_algorithm() -> str: ...

ssl_server_cert_signature_algorithm = property(get_ssl_server_cert_signature_algorithm, None)

Default Value

""

Remarks

The text description of the certificate's signature algorithm. The property contains either the name of the algorithm (e.g., "RSA" or "RSA_MD5RSA") or an object identifier (OID) string representing the algorithm.

This property is read-only.

ssl_server_cert_store Property

The name of the certificate store for the client certificate.

Syntax

def get_ssl_server_cert_store() -> bytes: ...

ssl_server_cert_store = property(get_ssl_server_cert_store, None)

Default Value

"MY"

Remarks

The name of the certificate store for the client certificate.

The ssl_server_cert_store_type property denotes the type of the certificate store specified by ssl_server_cert_store. If the store is password-protected, specify the password in ssl_server_cert_store_password.

ssl_server_cert_store is used in conjunction with the ssl_server_cert_subject property to specify client certificates. If ssl_server_cert_store has a value, and ssl_server_cert_subject or ssl_server_cert_encoded is set, a search for a certificate is initiated. Please see the ssl_server_cert_subject property for details.

Designations of certificate stores are platform dependent.

The following designations are the most common User and Machine certificate stores in Windows:

When the certificate store type is cstPFXFile, this property must be set to the name of the file. When the type is cstPFXBlob, the property must be set to the binary contents of a PFX file (i.e., PKCS#12 certificate store).

This property is read-only.

ssl_server_cert_store_password Property

If the type of certificate store requires a password, this property is used to specify the password needed to open the certificate store.

Syntax

def get_ssl_server_cert_store_password() -> str: ...

ssl_server_cert_store_password = property(get_ssl_server_cert_store_password, None)

Default Value

""

Remarks

If the type of certificate store requires a password, this property is used to specify the password needed to open the certificate store.

This property is read-only.

ssl_server_cert_store_type Property

The type of certificate store for this certificate.

Syntax

def get_ssl_server_cert_store_type() -> int: ...

ssl_server_cert_store_type = property(get_ssl_server_cert_store_type, None)

Default Value

0

Remarks

The type of certificate store for this certificate.

The class supports both public and private keys in a variety of formats. When the cstAuto value is used, the class will automatically determine the type. This property can take one of the following values:

This property is read-only.

ssl_server_cert_subject_alt_names Property

Comma-separated lists of alternative subject names for the certificate.

Syntax

def get_ssl_server_cert_subject_alt_names() -> str: ...

ssl_server_cert_subject_alt_names = property(get_ssl_server_cert_subject_alt_names, None)

Default Value

""

Remarks

Comma-separated lists of alternative subject names for the certificate.

This property is read-only.

ssl_server_cert_thumbprint_md5 Property

The MD5 hash of the certificate.

Syntax

def get_ssl_server_cert_thumbprint_md5() -> str: ...

ssl_server_cert_thumbprint_md5 = property(get_ssl_server_cert_thumbprint_md5, None)

Default Value

""

Remarks

The MD5 hash of the certificate. It is primarily used for X.509 certificates. If the hash does not already exist, it is automatically computed.

This property is read-only.

ssl_server_cert_thumbprint_sha1 Property

The SHA-1 hash of the certificate.

Syntax

def get_ssl_server_cert_thumbprint_sha1() -> str: ...

ssl_server_cert_thumbprint_sha1 = property(get_ssl_server_cert_thumbprint_sha1, None)

Default Value

""

Remarks

The SHA-1 hash of the certificate. It is primarily used for X.509 certificates. If the hash does not already exist, it is automatically computed.

This property is read-only.

ssl_server_cert_thumbprint_sha256 Property

The SHA-256 hash of the certificate.

Syntax

def get_ssl_server_cert_thumbprint_sha256() -> str: ...

ssl_server_cert_thumbprint_sha256 = property(get_ssl_server_cert_thumbprint_sha256, None)

Default Value

""

Remarks

The SHA-256 hash of the certificate. It is primarily used for X.509 certificates. If the hash does not already exist, it is automatically computed.

This property is read-only.

ssl_server_cert_usage Property

The text description of UsageFlags .

Syntax

def get_ssl_server_cert_usage() -> str: ...

ssl_server_cert_usage = property(get_ssl_server_cert_usage, None)

Default Value

""

Remarks

The text description of ssl_server_cert_usage_flags.

This value will be one or more of the following strings and will be separated by commas:

• Digital Signature
• Non-Repudiation
• Key Encipherment
• Data Encipherment
• Key Agreement
• Certificate Signing
• CRL Signing
• Encipher Only

If the provider is OpenSSL, the value is a comma-separated list of X.509 certificate extension names.

This property is read-only.

ssl_server_cert_usage_flags Property

The flags that show intended use for the certificate.

Syntax

def get_ssl_server_cert_usage_flags() -> int: ...

ssl_server_cert_usage_flags = property(get_ssl_server_cert_usage_flags, None)

Default Value

0

Remarks

The flags that show intended use for the certificate. The value of ssl_server_cert_usage_flags is a combination of the following flags:

Please see the ssl_server_cert_usage property for a text representation of ssl_server_cert_usage_flags.

This functionality currently is not available when the provider is OpenSSL.

This property is read-only.

ssl_server_cert_version Property

The certificate's version number.

Syntax

def get_ssl_server_cert_version() -> str: ...

ssl_server_cert_version = property(get_ssl_server_cert_version, None)

Default Value

""

Remarks

The certificate's version number. The possible values are the strings "V1", "V2", and "V3".

This property is read-only.

ssl_server_cert_subject Property

The subject of the certificate used for client authentication.

Syntax

def get_ssl_server_cert_subject() -> str: ...

ssl_server_cert_subject = property(get_ssl_server_cert_subject, None)

Default Value

""

Remarks

The subject of the certificate used for client authentication.

This property must be set after all other certificate properties are set. When this property is set, a search is performed in the current certificate store to locate a certificate with a matching subject.

If a matching certificate is found, the property is set to the full subject of the matching certificate.

If an exact match is not found, the store is searched for subjects containing the value of the property.

If a match is still not found, the property is set to an empty string, and no certificate is selected.

The special value "*" picks a random certificate in the certificate store.

The certificate subject is a comma-separated list of distinguished name fields and values. For instance, "CN=www.server.com, OU=test, C=US, E=support@nsoftware.com". Common fields and their meanings are as follows:

If a field value contains a comma, it must be quoted.

This property is read-only.

ssl_server_cert_encoded Property

The certificate (PEM/Base64 encoded).

Syntax

def get_ssl_server_cert_encoded() -> bytes: ...

ssl_server_cert_encoded = property(get_ssl_server_cert_encoded, None)

Default Value

""

Remarks

The certificate (PEM/Base64 encoded). This property is used to assign a specific certificate. The ssl_server_cert_store and ssl_server_cert_subject properties also may be used to specify a certificate.

When ssl_server_cert_encoded is set, a search is initiated in the current ssl_server_cert_store for the private key of the certificate. If the key is found, ssl_server_cert_subject is updated to reflect the full subject of the selected certificate; otherwise, ssl_server_cert_subject is set to an empty string.

This property is read-only.

timeout Property

A timeout for the class.

Syntax

def get_timeout() -> int: ...
def set_timeout(value: int) -> None: ...

timeout = property(get_timeout, set_timeout)

Default Value

30

Remarks

If the timeout property is set to 0, all operations will run uninterrupted until successful completion or an error condition is encountered.

If timeout is set to a positive value, the class will wait for the operation to complete before returning control.

The class will use do_events to enter an efficient wait loop during any potential waiting period, making sure that all system events are processed immediately as they arrive. This ensures that the host application does not freeze and remains responsive.

If timeout expires, and the operation is not yet complete, the class fails with an error.

Note: By default, all timeouts are inactivity timeouts, that is, the timeout period is extended by timeout seconds when any amount of data is successfully sent or received.

The default value for the timeout property is 30 seconds.

transaction_status Property

The transaction status from the last parsed message (ARes, RReq, or CRes).

Syntax

def get_transaction_status() -> str: ...

transaction_status = property(get_transaction_status, None)

Default Value

""

Remarks

Indicates whether a transaction qualifies as an authenticated transaction or account verification. Possible values are:

Note: The CRes message can contain only a value of Y or N. Values of D and I are only applicable for 3DS version 2.2.0.

This property is read-only.

add_extension Method

Adds an extension to the collection.

Syntax

def add_extension(id: str, name: str, critical: bool, data: str) -> None: ...

Remarks

Data necessary to support requirements not otherwise defined in the 3-D Secure message are carried in Message Extensions. add_extension adds a new extension to the extensions collection.

Note: The maximum number of extensions is 10.

add_request_field Method

Adds a field to the data in the request.

Syntax

def add_request_field(name: str, value: str, value_type: int) -> None: ...

Remarks

This method can be used to extend the requests constructed by the class. When this method is called, the component will add the specified field to the end of the request.

check_response Method

Parses the specified message.

Syntax

def check_response(response: str) -> None: ...

Remarks

check_response parses a variety of messages that are sent to the Server as part of the authentication process.

The following messages can be parsed using this method:

• The threeDSMethodData form variables received at the method_notification_url
• The Results Request (RReq) message received at the results_url
• The cres form variables received at the notification_url
• The Operation Request Message (OReq) sent from a DS.

When calling the method, pass the message to be parsed as the Response parameter. The properties which are populated after calling this method vary depending on the type of message being parsed. See below for additional information.

Method Data from method_notification_url

After calling get_method_data, a request is made to the card_range_method_url. After this, the ACS will make a POST to method_notification_url to inform the requestor of completion. Retrieve the threeDSMethodData form variable value that was POSTed and pass it to this method. After calling this method, the following properties are populated:

• server_transaction_id

The server_transaction_id may be used to match the response with the request.

Results Request message from results_url

When a challenge is completed for both app-based and browser-based flows, a POST is made to the results_url with a Results Request message.

Prior to checking this RReq message, the ServerTransactionId can be extracted using the ExtractRReqServerTransactionId configuration setting. This value can then be used to look up details on the transaction that were saved prior to starting the challenge process, including the messageVersion which must be set via the message_version property prior to passing the RReq message to the check_response method.

Pass the body of the HTTP request received at results_url to this method. This contains information about the results, and asks for a Results Response to be sent back containing the results_status.

After calling this method, the following properties are populated:

• authentication_eci
• transaction_status
• TransactionStatusReason
• ChallengeCancellationIndicator
• AuthenticationType
• authentication_value

To respond to the POST, set results_status to the appropriate value and call get_results_response to build a response message to be sent back to the directory server. Use the value from get_results_response in the application as the body of the HTTP response. Set the Content-Type header to application/JSON; charset=utf-8

If transaction_status is D and TransactionStatusReason is 29 or 30, this indicates that decoupled authentication should now be performed. When building the Results Response, a results_status value of 04 should be used. Then, within 60 seconds, a new 3RI authentication must be started with the following field requirements:

• ThreeRIIndicator set to 19, indicating Decoupled Authentication Fallback
• DecoupledRequestIndicator set to Y
• AuthenticationInformation set with threeDSReqPriorRef set to the ACS Transaction ID and threeDSReqPriorAuthMethod set to 02 (Cardholder challenge occurred by ACS).

Final Challenge Response from notification_url

In a browser-based flow, the challenge takes place directly between the cardholder and the ACS in a separate iframe or window. The ACS will POST the final challenge response to the notification_url after the challenge is complete. Retrieve the cres form variable value from the POST data and pass it to check_response. After calling this method the following properties are populated:

• server_transaction_id
• transaction_status

In addition to the cres variable, a threeDSSessionData variable will be present if SessionData was set before calling get_challenge_request. The threeDSSessionData value POSTed to notification_url may be passed to EncodedSessionData. Query SessionData to get the decoded session data.

Operation Request Message (OReq)

OReq messages are used to communicate operational information from a DS to the 3DS Server. This message is not part of the 3-D Secure authentication flow.

When an OReq message is received, check_response should be called to validate the message. There may be more than one OReq message sent in a sequence, and check_response should be called for each. The current instance of the Server object can be cached for the duration of the OReq sequence until the final OReq is received. The Operation.SequenceNumber should also be set prior to calling check_response. The component will verify the sequence number of the received OReq to ensure it's not out of sequence.

After calling this method, details are made available in operation.

If any OReq data element fails validation, Operation.MessageStatus will be set to "02". If the OReq is valid, Operation.MessageStatus will be empty.

If the OReq is valid, determine if the final OReq has been received (Operation.SequenceNumber equals Operation.SequenceTotal). If these values match, the final OReq in the sequence has been received, and get_operation_response can be used to generate the ORes message.

For valid OReq messages that are not the final OReq in the sequence, the response should be HTTP Status 200 (OK) with an empty HTTP body.

config Method

Sets or retrieves a configuration setting.

Syntax

def config(configuration_string: str) -> str: ...

Remarks

config is a generic method available in every class. It is used to set and retrieve configuration settings for the class.

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the class, access to these internal properties is provided through the config method.

To set a configuration setting named PROPERTY, you must call Config("PROPERTY=VALUE"), where VALUE is the value of the setting expressed as a string. For boolean values, use the strings "True", "False", "0", "1", "Yes", or "No" (case does not matter).

To read (query) the value of a configuration setting, you must call Config("PROPERTY"). The value will be returned as a string.

get_challenge_request Method

Builds the Challenge Request (CReq) for browser-based flow.

Syntax

def get_challenge_request() -> str: ...

Remarks

The get_challenge_request method is used to build the Challenge Request (CReq) which will be sent in a form post to the acsurl property via the cardholder browser.

An iframe should be created in the cardholder's browser, which will be used to send the challenge request and allow the cardholder and ACS to interact directly.

The size of the challenge window (iframe) may be any of the sizes listed in challenge_window_size. Before calling this method set challenge_window_size to the appropriate value to let the ACS know the size of the window on the cardholder's browser.

Calling this method will return a string which should be placed in a creq form variable.

The SessionData setting may also be set with any data that may be helpful to continue processing the transaction after the final challenge response is received at the notification_url. To prepare the session data for submission, query EncodedSessionData. The encoded string may then be placed in the threeDSSessionData form variable.

Note: The maximum length of the threeDSSessionData form variable, after being encoded, is 1024 bytes.

Example Form

Response Handling

Once the challenge has been completed by the cardholder, the directory server will post a Results Request (RReq) to the results_url specified when calling send_auth_request. See check_response and get_results_response for more details.

The ACS will also post the Challenge Response to the notification_url specified when calling send_auth_request. This post contains data which may be parsed to verify the challenge results. See check_response for more details.

get_method_data Method

Prepares method data to be sent to the ACS before the authentication request is sent.

Syntax

def get_method_data() -> str: ...

Remarks

The get_method_data method prepares data to be transmitted to the ACS via the cardholder's browser.

When a transaction begins, the card range cache should be queried to find details about the card range to which the card number belongs. If a card_range_method_url is defined for the card range, this method should be used to prepare data to be sent via the cardholder's browser to the card_range_method_url.

If the card_range_method_url is not set for the specified card range, set MethodCompletionIndicator to U before calling send_auth_request.

The following properties are applicable when calling this method:

• method_notification_url (required)

This method returns a string which contains encoded data to be sent to the ACS. This includes server_transaction_id and method_notification_url. After calling this method, the returned string can be transmitted to the ACS via the cardholder's browser.

As per the EMVCo specification, create a hidden iframe in the browser and send a form with the field name threeDSMethodData containing the return value from this method and post the form to the card_range_method_url.

The ACS will record information about the customer's environment and then POST back to the method_notification_url. The page at this URL should expect a form variable with the name threeDSMethodData which will contain the original server_transaction_id value in order to match the response with the request. The form variable value will be base64url encoded and may be passed directly to the check_response method. The class will decode and parse the received value and populate server_transaction_id with the value from the received data.

If the response from the ACS is not received within 10 seconds, set MethodCompletionIndicator to N before calling send_auth_request.

get_operation_response Method

Builds and returns the Operation Response Message (ORes) to be sent back to the Directory Server.

Syntax

def get_operation_response() -> str: ...

Remarks

This method builds the Operation Response Message (ORes) to be sent back to the Directory Server in an HTTP reply to the final Operation Request (OReq) message. It returns a JSON object containing the fields required for the ORes.

When an OReq message is received, check_response should be called to validate the message. There may be more than one OReq message sent in a sequence, and check_response should be called for each. While several OReq messages may be received in a sequence (totalling Operation.SequenceTotal), the ORes message is only expected to be generated using get_operation_response after the final OReq. For valid intermediate OReq messages the response should be HTTP Status 200 (OK) with an empty HTTP body.

After passing the final received OReq message to the check_response method, all the properties required to be set before building the ORes will have been populated except for Operation.MessageStatus, which indicates whether or not the message was successfully received for further processing, or provides more detail to the DS on why the requested action could not be completed.

Possible values include:

If any OReq data element fails validation from check_response, Operation.MessageStatus will be set to "02". The error_packet can be queried and should be returned to the DS.

For valid OReq messages, Operation.MessageStatus will be empty. Next, determine if the final OReq has been received (Operation.SequenceNumber equals Operation.SequenceTotal). If these values match, the final OReq in the sequence has been received, and get_operation_response can be used to generate the ORes message.

Once Operation.MessageStatus has been set, get_operation_response can be called and will return a string containing the reply to be sent in the response. In the HTTP server, use the string returned from this method as the body of the reply and set the Content-Type header to application/JSON; charset=utf-8

get_results_response Method

Builds and returns the Results Response Message (RRes) to be sent back to the directory server.

Syntax

def get_results_response() -> str: ...

Remarks

This method builds the Results Response Message (RRes) to be sent back to the directory server in the HTTP reply to the Results Request (RReq). It returns a JSON object containing the fields required for the RRes.

After passing the received RReq message to the check_response method, all the properties required to be set before building the RRes will have been populated except for results_status, which indicates whether or not the message was successfully received for further processing, or provides more detail to the ACS on why the challenge could not be completed.

Possible values include:

The Server can use the value of the RequestorChallengeInd to determine whether or not a value of 02 is appropriate. It must use the necessary error handling logic when processing ARes messages to determine whether or not a value of 03 is appropriate.

Once results_status has been set, get_results_response can be called and will return a string containing the reply to be sent in the response. In the HTTP server, use the string returned from this method as the body of the reply and set the Content-Type header to application/JSON; charset=utf-8

interrupt Method

Interrupts the current action.

Syntax

def interrupt() -> None: ...

Remarks

This method interrupts any processing that the class is currently executing.

request_card_ranges Method

Requests card ranges from the directory server.

Syntax

def request_card_ranges() -> None: ...

Remarks

request_card_ranges requests card ranges and additional information from the directory server.

When a transaction is initiated, the first step that should be taken is to find information about the card range to which the card number belongs. This includes the protocol version(s) supported by the ACS and DS, and if one exists, any corresponding Method URL (used in the browser flow).

Results of this method should be cached in order to quickly look up information when processing transactions. It is recommended to call this method once every 24 hours at a minimum, and once per hour as a maximum to refresh the cache. The class will not cache the returned values; it is up to the user to cache these values in an appropriate location.

The first time this method is called, serial_number will be empty, indicating that all results should be returned. This is an offset the server will use to return only new updates to the card ranges (if any) since the last request. The serial_number will be populated after this method returns, and this value should be saved to be used in subsequent calls.

When a response is received, the card ranges will be made available via the component events and properties.

When message_version is set to 2.3.1, the on_card_range_data event will fire for each card range data object received, and the ranges and acs_protocol_infos properties will be populated to be accessed within the event handler. Optionally, the DS may return a list of URLs that the 3DS Server can use for communication with the DS. If present, these will be available via both the on_dsurl event and the dsur_ls property.

When message_version is set to 2.2.0 or 2.1.0, the on_card_range event will fire for each card range that is returned, and the results will also be held in the card_ranges property.

The following properties are applicable when calling this method:

• directory_server_url (required)
• serial_number
• server_transaction_id
• ServerOperatorId
• EnableDownloadCardRangeDataFile (2.3.1 only)

The following properties are populated after calling this method:

• card_ranges
• DSStartProtocolVersion
• DSEndProtocolVersion
• serial_number
• DSTransactionId
• ResendRequestCardRanges

Note that when message_version 2.3.1, the card range data is only available using the on_card_range_data event.

When using message_version 2.2.0 or 2.3.1, the returned ranges may include ACS Information Indicators. These are used to indicate additional functionality supported by the ACS for the card range(s). For 2.2.0, a ACSInformationIndicator field is exposed in both card_ranges collection and on_card_range event. In version 2.3.1, this information is availalbe in the acs_protocol_infos collection via the Indicator field. Possible values are:

• 01 - Authentication Available at ACS
• 02 - Attempts Supported by ACS or DS
• 03 - Decoupled Authentication Supported
• 04 - Whitelisting Supported
• 05 - Device Binding Supported (2.3.1 only)
• 06 - WebAuthn Authentication Supported (2.3.1 only)
• 07 - SPC Authentication Supported (2.3.1 only)
• 08 - Transaction Risk Analysis Exemption Supported (2.3.1 only)
• 09 - Trust List Exemption Supported (2.3.1 only)
• 10 - Low Value Exemption Supported (2.3.1 only)
• 11 - Secure Corporate Payments Exemption Supported (2.3.1 only)
• 80-99 - Reserved for DS Use

If an error is identified with the card range data received from the directory server when calling the request_card_ranges method, the ResendRequestCardRanges configuration setting will be true, indicating that the request should be resent. When resending, if serial_number was specified for the initial request, it should be set to an empty string before calling request_card_ranges again. Otherwise, the request can be sent without the serial number again, but the server may respond with an error due to multiple requests within an hour.

Note that retrieving card ranges can consume a lot of memory, especially when retrieving the initial set of ranges. The StoreCardRangeData and UseJsonDOM configuration settings can be set to help minimize the amount of memory used. A CardRangeTempPath setting can also be used to specify a temporary path to which the PRes packet will be temporarily written prior to parsing.

When using message_version 2.3.1, if UseJsonDOM is false, the card ranges will need to be cached and processed after the request_card_ranges method returns. The card ranges would then need to be processed in the order indicated by the CardRangeRecordsReadOrder configuration setting. A check will also need to be made for overlap of ranges. If issue(s) are found, the ReportCardRangeError configuration setting should be used to report the error to the directory server.

reset Method

Clears all properties to their default values.

Syntax

def reset() -> None: ...

Remarks

This method clears all properties to their default values.

reset_transaction_info Method

Resets transaction specific information.

Syntax

def reset_transaction_info() -> None: ...

Remarks

This method must be called between transactions when using the same class instance.

Each transaction that is attempted uses transaction specific values that should not be re-used in subsequent transactions. Call this method to make sure that any transaction specific information is cleared between transactions.

This method resets only the transaction specific information without resetting any other values which have been configured. This allows re-use of the same component instance.

In a Browser-Based flow the following are reset:

• Internal ephemeral encryption keys
• Values added by add_request_field
• account_type
• acsurl
• AppIP
• AppURLIndicator
• authentication_eci
• authentication_value
• billing_address
• browser_accept_header
• browser_ip_address
• browser_java_enabled_val
• browser_java_script_enabled_val
• browser_language
• browser_screen_color_depth
• browser_screen_height
• browser_time_zone
• browser_user_agent
• BrowserUserDeviceId
• BrowserUserId
• card_exp_date
• cardholder_email
• cardholder_home_phone
• cardholder_mobile_phone
• cardholder_name
• cardholder_work_phone
• card_number
• client_auth_request
• client_auth_response
• data_packet_out
• error_packet
• operation
• purchase_amount
• purchase_date
• recurring_exp_date
• recurring_frequency
• results_status
• server_transaction_id
• shipping_address
• transaction_status
• AccountAgeIndicator
• AccountChangeDate
• AccountChangeIndicator
• AccountDate
• AccountDayTransactions
• AccountId
• AccountPasswordChangeDate
• AccountPasswordChangeIndicator
• AccountProvisioningAttempts
• AccountPurchaseCount
• AccountYearTransactions
• ACSChallengeMandatedIndicator
• ACSReferenceNumber
• ACSTransactionId
• AddressMatch
• AuthenticationType
• CardholderInformation
• ChallengeCancellationIndicator
• DecoupledRequestIndicator
• DeliveryEmailAddress
• DeliveryTimeframe
• DSReferenceNumber
• DSTransactionId
• EncodedSessionData
• IncomingRawExtensions
• OutgoingRawExtensions
• extensions
• IncomingExtensionCount
• IncomingExtensionId
• IncomingExtensionName
• IncomingExtensionCritical
• IncomingExtensionData
• GiftCardAmount
• GiftCardCount
• GiftCardCurrency
• InstalmentPaymentData
• InteractionCounter
• MethodCompletionIndicator
• PaymentAccountAge
• PaymentAccountAge
• PaymentAccountAgeIndicator
• PaymentAccountAgeIndicator
• PreOrderDate
• PreOrderPurchaseIndicator
• AuthenticationInformation
• ReorderItemsIndicator
• ReqAuthCount
• ReqAuthData[Index]
• ReqAuthMethod[Index]
• ReqAuthTimestamp[Index]
• SessionData
• ShipAddressUsageDate
• ShipAddressUsageIndicator
• ShipIndicator
• ShipNameIndicator
• SuspiciousAccountActivity
• ThreeRIIndicator
• TransactionStatusReason
• TransactionType
• WhitelistStatus
• WhitelistStatusSource
• EMVPaymentTokenSource

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)
• message_version (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 in 2.1.0, required in 2.2.0 and 2.3.1 if BrowserJavaScriptEnabled is true)
• browser_screen_width (required in 2.1.0, required in 2.2.0 and 2.3.1 if BrowserJavaScriptEnabled is true)
• browser_time_zone (required in 2.1.0, required in 2.2.0 and 2.3.1 if BrowserJavaScriptEnabled is true)
• browser_user_agent (required)
• browser_ip_address (conditional)
• browser_java_enabled_val (required in 2.1.0, required in 2.2.0 and 2.3.1 if BrowserJavaScriptEnabled is true)
• browser_java_script_enabled_val (not valid in 2.1.0, required in 2.2.0 and 2.3.1)
• browser_screen_color_depth (required in 2.1.0, required in 2.2.0 and 2.3.1 if BrowserJavaScriptEnabled is true)
• accept_language (2.3.1 only)
• acquirer_country_code (2.3.1 only)

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, D or S), 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.

SPC-Based Authentication

SPC (Secure Payment Confirmation) provides a method to perform a challenge using preestablished FIDO credentials when using a Browser. The SPC authentication can be initiated by the 3DS Requestor via an extra AReq/ARes message pair or by the ACS via a standard Browser Challenge Flow.

For an SPC authentication to execute correctly, the following prerequisites apply:

1. The ACS has an enrolled FIDO authenticator on the device for this Cardholder.
2. The 3DS Requestor and/or the ACS have detected that the Cardholder Browser supports the related SPC APIs (allow="payment *; publickey-credentialsget *"). For the ACS, this information can be obtained via the Browser User Agent data element or via data obtained via the 3DS Method.

SPC-based authentication can be enabled with the following additions:

Prior to sending the initial authentication request packet (AReq) using the send_auth_request method, the ThreeDSRequestorSpcSupport configuration setting should be set to True to indicate that SPC is supported by the 3DS Requestor.

If SPC is accepted by the ACS, the resulting transaction_status should be S. The response will also contain a list of enrolled FIDO (WebAuthn) credentials associated with the cardholder, and SPC transaction data. This data is available in the following configuration settings:

• WebAuthnCredentialListCount
• WebAuthnCredentialListWebAuthnCredential
• WebAuthnCredentialListRelyingPartyId
• SPCTransactionAdditionalData
• SPCTransactionChallenge
• SPCTransactionChallengeInfoText
• SPCTransactionCurrency
• SPCTransactionDisplayName
• SPCTransactionIcon
• SPCTransactionIssuerImage
• SPCTransactionIssuerImageDark
• SPCTransactionIssuerImageMonochrome
• SPCTransactionPayeeName
• SPCTransactionPayeeOrigin
• SPCTransactionPSImage
• SPCTransactionPSImageDark
• SPCTransactionPSImageMonochrome
• SPCTransactionTimeout
• SPCTransactionValue

If a new instance of the Server component will be used after authentication to send the second AReq, the AuthenticationInformation value should be saved to be used later.

This information is relayed to the 3DS Requestor implementation, and the 3DS Requestor invokes the SPC authentication (SPC API) against the WebAuthn Credential list. The cardholder authenticates using the FIDO authenticator on their device, and the 3DS Requestor retrieves the Assertion Data from the SPC API call.

The 3DS Server is then configured to includes this FIDO Assertion Data is then included in a new authentication request by setting the ReqAuthData[Index] and a ReqAuthMethod[Index] of 09. If the AuthenticationInformation value was saved earlier, it can be set via the same configuration setting. If the 3DS Requestor encounters an error during SPC API invokation, this can be indicated using the SPCIncompletionIndicator.

The send_auth_request method should then be called again to transmit this data to the ACS (by way of the DS) in a second AReq.

When send_auth_request returns, the 3DS Server proceed the same as the regular browser-based flow when the ARes is returned.

When SPC authentication is to be performed, the authenticaton must be completed within 9 minutes. The component will automatically start an internal timer that can be checked using the CheckSPCTimeout configuration setting. This will return the number of seconds left for SPC authentication to complete. If the time has expired before receiving the Assertion Data from the 3DS Requestor, checking this configuration setting will cause the component to automatically send the second AReq message with an SPCIncompletionIndicator value of 03, indicating that SPC authentication timed out.

Note that SPC-based authentication is only available when a message_version of 2.3.1 is used.

on_card_range Event

Fired when the response to a Preparation Request Message (PReq) is received.

Syntax

class ServerCardRangeEventParams(object):
  @property
  def range_start() -> str: ...

  @property
  def range_end() -> str: ...

  @property
  def range_action() -> str: ...

  @property
  def acs_start_protocol_version() -> str: ...

  @property
  def acs_end_protocol_version() -> str: ...

  @property
  def ds_start_protocol_version() -> str: ...

  @property
  def ds_end_protocol_version() -> str: ...

  @property
  def three_ds_method_url() -> str: ...

  @property
  def acs_information_indicator() -> str: ...

  @property
  def valid() -> bool: ...
  @valid.setter
  def valid(value) -> None: ...

# In class Server:
@property
def on_card_range() -> Callable[[ServerCardRangeEventParams], None]: ...
@on_card_range.setter
def on_card_range(event_hook: Callable[[ServerCardRangeEventParams], None]) -> None: ...

Remarks

The on_card_range event fires for each range of card numbers to be added or removed from the cache. The RangeAction parameter indicates whether the range specified by the RangeStart and RangeEnd arguments is to be added or deleted from the current cache.

Note that the card ranges must be processed in the order returned.

These card ranges are also returned outside this event in the card_range_start, card_range_end, card_range_action, card_range_acs_start_protocol_version, card_range_acs_end_protocol_version, and card_range_method_url properties.

on_card_range_data Event

Fired when the response to a Preparation Request Message (PReq) is received. This event is used for card range data returned when version 2.3.1 of the protocol is used.

Syntax

class ServerCardRangeDataEventParams(object):
  @property
  def range_action() -> str: ...

  @property
  def issuer_country_code() -> str: ...

  @property
  def ds_protocol_versions() -> int: ...

  @property
  def status() -> int: ...
  @status.setter
  def status(value) -> None: ...

# In class Server:
@property
def on_card_range_data() -> Callable[[ServerCardRangeDataEventParams], None]: ...
@on_card_range_data.setter
def on_card_range_data(event_hook: Callable[[ServerCardRangeDataEventParams], None]) -> None: ...

Remarks

When card ranges are requested using using message_version 2.3.1, the on_card_range_data event will fire for each card range data object received in the Preparation Response Message (PRes) returned from the directory server.

This data indicates the most recent protocol versions supported by the ACS and, optionally, the DS that hosts that range. If configured, the ACS URL for the 3DS Method will be included as well, along with the 3DS features supported by the ACS, such as Trust List or Decoupled Authentication.

The RangeAction parameter indicates whether the ranges defined in the ranges property are to be added, deleted, or modified in the current cache.

Within the event, a few properties will also be populated, both with details for the current ranges in question. The ranges collection will hold the card ranges for which the rest of the data applies. The acs_protocol_infos collection will hold protocol versions and other associated information supported by the ACS for the card ranges.

on_data_packet_in Event

Fired when receiving a data packet from the server.

Syntax

class ServerDataPacketInEventParams(object):
  @property
  def data_packet() -> bytes: ...

# In class Server:
@property
def on_data_packet_in() -> Callable[[ServerDataPacketInEventParams], None]: ...
@on_data_packet_in.setter
def on_data_packet_in(event_hook: Callable[[ServerDataPacketInEventParams], None]) -> None: ...

Remarks

This event fires when a packet is received. The entire data packet (including all framing and error detection characters) is contained in the DataPacket parameter. This parameter may be inspected for advanced troubleshooting, or to extract additional response properties beyond the scope of this component.

on_data_packet_out Event

Fired when sending a data packet to the server.

Syntax

class ServerDataPacketOutEventParams(object):
  @property
  def data_packet() -> bytes: ...

# In class Server:
@property
def on_data_packet_out() -> Callable[[ServerDataPacketOutEventParams], None]: ...
@on_data_packet_out.setter
def on_data_packet_out(event_hook: Callable[[ServerDataPacketOutEventParams], None]) -> None: ...

Remarks

This event fires right before each data packet is sent. The entire data packet (including all framing and error detection characters) is contained in the DataPacket parameter. This parameter may be inspected for advanced troubleshooting, or may be modified to support additional features beyond the scope of this component.

on_dsurl Event

Fired for each DS URL present in the Preparation Response Message (PRes).

Syntax

class ServerDSURLEventParams(object):
  @property
  def three_ds_server_to_ds_url() -> str: ...

  @property
  def ds_country_code() -> str: ...

# In class Server:
@property
def on_dsurl() -> Callable[[ServerDSURLEventParams], None]: ...
@on_dsurl.setter
def on_dsurl(event_hook: Callable[[ServerDSURLEventParams], None]) -> None: ...

Remarks

The on_dsurl event fires for each DS URL returned from the directory server when requesting card ranges via the request_card_ranges method.

Each DSURL object contains a ThreeDSServerToDsUrl and, optionally, a CountryCode. For a given card range, if the Issuer Country Code matches the DS CountryCode, the 3DS Server uses this ThreeDSServerToDsUrl to communicate with the DS. If there is no match, the 3DS Server uses the default 3DS Server to DS URL.

on_error Event

Information about errors during data delivery.

Syntax

class ServerErrorEventParams(object):
  @property
  def error_code() -> int: ...

  @property
  def description() -> str: ...

# In class Server:
@property
def on_error() -> Callable[[ServerErrorEventParams], None]: ...
@on_error.setter
def on_error(event_hook: Callable[[ServerErrorEventParams], None]) -> None: ...

Remarks

The on_error event is fired in case of exceptional conditions during message processing.

ErrorCode contains an error code and Description contains a textual description of the error. For a list of valid error codes and their descriptions, please refer to the Error Codes section.

on_log Event

Fires once for each log message.

Syntax

class ServerLogEventParams(object):
  @property
  def log_level() -> int: ...

  @property
  def message() -> str: ...

  @property
  def log_type() -> str: ...

# In class Server:
@property
def on_log() -> Callable[[ServerLogEventParams], None]: ...
@on_log.setter
def on_log(event_hook: Callable[[ServerLogEventParams], None]) -> None: ...

Remarks

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.

on_message_extension Event

Fired when a Message Extension is present in a message being parsed.

Syntax

class ServerMessageExtensionEventParams(object):
  @property
  def name() -> str: ...

  @property
  def id() -> str: ...

  @property
  def data() -> str: ...

  @property
  def critical() -> bool: ...

  @property
  def recognized() -> bool: ...
  @recognized.setter
  def recognized(value) -> None: ...

# In class Server:
@property
def on_message_extension() -> Callable[[ServerMessageExtensionEventParams], None]: ...
@on_message_extension.setter
def on_message_extension(event_hook: Callable[[ServerMessageExtensionEventParams], None]) -> None: ...

Remarks

Enables the parsing of Message Extension data by firing when extensions have been included in a ARes, CRes, RReq or PRes message that is being parsed. Message Extensions carry additional data not defined in the 3DS Protocol. This event fires once for each such extension. Event arguments correspond to the four elements comprising the extension, as well as an indication of whether or not the extension is recognized:

If a 3-D Secure application receives a message containing a critical extension that it does not recognize, it must treat it as invalid and return Error Code = 202. This event will fire before the exception is thrown.

on_ssl_server_authentication Event

Fired after the server presents its certificate to the client.

Syntax

class ServerSSLServerAuthenticationEventParams(object):
  @property
  def cert_encoded() -> bytes: ...

  @property
  def cert_subject() -> str: ...

  @property
  def cert_issuer() -> str: ...

  @property
  def status() -> str: ...

  @property
  def accept() -> bool: ...
  @accept.setter
  def accept(value) -> None: ...

# In class Server:
@property
def on_ssl_server_authentication() -> Callable[[ServerSSLServerAuthenticationEventParams], None]: ...
@on_ssl_server_authentication.setter
def on_ssl_server_authentication(event_hook: Callable[[ServerSSLServerAuthenticationEventParams], None]) -> None: ...

Remarks

During this event, the client can decide whether or not to continue with the connection process. The Accept parameter is a recommendation on whether to continue or close the connection. This is just a suggestion: application software must use its own logic to determine whether or not to continue.

When Accept is False, Status shows why the verification failed (otherwise, Status contains the string OK). If it is decided to continue, you can override and accept the certificate by setting the Accept parameter to True.

on_ssl_status Event

Fired when secure connection progress messages are available.

Syntax

class ServerSSLStatusEventParams(object):
  @property
  def message() -> str: ...

# In class Server:
@property
def on_ssl_status() -> Callable[[ServerSSLStatusEventParams], None]: ...
@on_ssl_status.setter
def on_ssl_status(event_hook: Callable[[ServerSSLStatusEventParams], None]) -> None: ...

Remarks

The event is fired for informational and logging purposes only. This event tracks the progress of the connection.

Server Config Settings

The class accepts one or more of the following configuration settings. Configuration settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the class, access to these internal properties is provided through the config method.

Server Config Settings

SSL Config Settings

Server Errors

Server Errors

HTTP Errors

The class may also return one of the following error codes, which are inherited from other classes.

TCPClient Errors

SSL Errors

TCP/IP Errors