Client Module

Properties Methods Events Configuration Settings Errors

The Client component is designed for use on mobile devices and facilitates EMV® 3-D Secure (EMV 3DS) authentication.

Syntax

nsoftware.IPWorks3DS.Client

Remarks

The Client class is a counterpart to the 3DS Server class. It is designed for use on mobile devices and supports operations that facilitate EMV® 3-D Secure (EMV 3DS) authentication in both frictionless and challenge flows.

Preparing the Authentication Request

To begin, device specific information must be collected and prepared for transmission to the directory server. This can be done by calling the AddDeviceParam method. Consult the EMV 3DS Specifications for more details about applicable device parameters for your particular operating system.

The GetAuthRequest method is used to obtain the request message to be send to the directory server. GetAuthRequest encrypts the device info and prepares all the data necessary to be sent by the 3DS Server class in the SendAuthRequest method.

After calling this method, the returned data must be transmitted via a separate secure channel to the server where 3DS Server is being used.

The following properties are required before calling the method:


Property	Description
DeviceParams	Contains device information parameters. Add parameters via AddDeviceParam.
DirectoryServerCert	Used to encrypt the device parameters.
DirectoryServerId	Identifies the DirectoryServerCert within the directory server.
SDKAppId	A UUID for the specific installation.
SDKReferenceNumber	An Id assigned by EMVCo to identify the vendor and software version.

Calling this method returns required information used by 3DS Server to send the authentication request. Transmit the value returned by this method to the system where 3DS Server is used. The method used to transmit this value is outside the scope of the class.

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

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

Interaction With the 3DS Server Class

As mentioned above, the request to the Directory Server must be made by the 3DS Server class which resides on a server under control of the merchant. A web server is required even for app-based authentication both to send the authentication request and to be notified of authentication results later in the flow.

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

Sending the Authentication Request

The act of sending the authentication request takes place with the 3DS Server class.

SendAuthRequest begins the 3-D Secure transaction flow by sending an authentication request to the DirectoryServerURL.

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

Prior to calling SendAuthRequest, 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:

AcquirerBIN (required)
AcquirerMerchantId (required)
CardholderName (required)
CardNumber (required)
DirectoryServerURL (required)
MerchantCategoryCode (required)
MerchantCountryCode (required)
MerchantName (required)
PurchaseAmount (required)
PurchaseDate (required)
RequestorId (required)
RequestorName (required)
RequestorURL (required)
ResultsURL (required)
AccountType
AuthenticationIndicator
BillingAddress*
CardholderEmail
CardholderHomePhone
CardholderMobilePhone
CardholderWorkPhone
DecoupledMaxTimeout
DecoupledRequestIndicator
DeviceChannel
MessageCategory
PurchaseCurrency
PurchaseExponent
ServerOperatorId
ServerTransactionId
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 ClientAuthRequest 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 MethodURL has been set by the ACS. Card range data may be retrieved by calling RequestCardRanges.

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

If a MethodURL 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 GetMethodData 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 SendAuthRequest.

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

NotificationURL (required)
BrowserAcceptHeader (required in 2.1.0 and 2.2.0)
BrowserLanguage (required in 2.1.0 and 2.2.0)
BrowserScreenHeight (required in 2.1.0, required in 2.2.0 if BrowserJavaScriptEnabled is true)
BrowserScreenWidth (required in 2.1.0, required in 2.2.0 if BrowserJavaScriptEnabled is true)
BrowserTimeZone (required in 2.1.0, required in 2.2.0 if BrowserJavaScriptEnabled is true)
BrowserUserAgent (required in 2.1.0 and 2.2.0)
BrowserIPAddress (conditional in 2.1.0 and 2.2.0)
BrowserJavaEnabledVal (required in 2.1.0, required in 2.2.0 if BrowserJavaScriptEnabled is true)
BrowserJavaScriptEnabledVal (not valid in 2.1.0, required in 2.2.0)
BrowserScreenColorDepth (required in 2.1.0, required in 2.2.0 if BrowserJavaScriptEnabled is true)

Response Handling

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


Transaction Status	Description
Y	Authenticated successfully
C	Cardholder challenge required
N	Not authenticated
A	Not authenticated, but a proof of authentication attempt was generated in AuthenticationValue
U	Not authenticated due to technical or other issue
R	Not authenticated because the issuer is rejecting authentication
D	Challenge required; decoupled authentication confirmed
I	Informational only; 3DS Requestor challenge preference acknowledged

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

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

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

The following properties are applicable after calling this method:

AuthenticationECI
AuthenticationValue
TransactionStatus
TransactionStatusReason
CardholderInformation
ACSURL (if challenge required)
ACSChallengeMandatedIndicator (if challenge required)
AuthenticationType (if challenge required)
DecoupledConfirmationIndicator

Response Handling - App-Based Flow

After calling this method, ClientAuthResponse is populated with data to be transmitted back to the 3DS SDK. If a challenge is required, the ClientAuthResponse 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 SendAuthRequest 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 TransactionStatus is also populated in the 3DS Server class and may be inspected prior to transmitting ClientAuthResponse back to the 3DS SDK.

Response Handling - Browser-Based Flow

If TransactionStatus is C, then additional steps are required to complete the authentication. The GetChallengeRequest 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 ResultsURL value that was specified when calling SendAuthRequest.

See the GetChallengeRequest method for more details.

If TransactionStatus 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 ResultsURL that was specified when calling SendAuthRequest.

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

Processing the Authentication Response

After the response to the authentication request is received from the 3DS Server class, call CheckAuthResponse to verify and parse the response. See the 3DS Server's SendAuthRequest method for details about obtaining the response.

Before calling this method, ACSRootCerts must be populated with the root certificates used by the ACS to sign the response. This method will validate the signature of the signed content if present.

After calling this method, inspect TransactionStatus to determine if the transaction requires a challenge. If TransactionStatus is C, a challenge is required and SendChallengeRequest should be called to proceed with the challenge flow. If TransactionStatus is D, decoupled authentication will take place outside of the 3-D Secure flow and the results will be posted to the 3DS Server.

If TransactionStatus is Y or A, the transaction is complete.

Challenge Interaction

If TransactionStatus is C, a challenge is required. The challenge takes place between the cardholder and the ACS. During this interaction the class will communicate directly with the ACS from the app where it is used to exchange information.

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

When the TransactionStatus is C after calling CheckAuthResponse, a challenge to the cardholder is required. This method sends the challenge request and parses the response. The ACS may provide multiple challenges to the cardholder during this process. As a result this method may need to be called multiple times throughout the authentication process.

After this method is called, check ChallengeComplete to determine if the challenge process is complete. If it is complete (True), check TransactionStatus to determine the outcome. If ChallengeComplete is False, additional challenge interaction is required.

First Request

The first time this method is called, information about the required challenge is obtained from the ACS. The ACS connection information is automatically set when CheckAuthResponse is called; there is no need to specify any ACS connection information.

All required properties for the first call to this method are automatically set after CheckAuthResponse is called. If the transaction has been canceled, set ChallengeCancellationIndicator to inform the ACS.

After calling this method, the ACS will respond with details about the challenge to be presented to the cardholder. The ACSUIType property indicates the way the ACS will interact with the cardholder. The ChallengeComplete property will be False after the first call to this method since the challenge interaction is not yet complete.

The following properties are applicable when ACSUIType is Text (01), Single-Select (02), or Multi-Select (03):

Use the values in the above properties to populate values in the native UI in the app. The UI must follow the guidelines defined in the EMV 3DS specification.

The following properties are applicable when ACSUIType is Out-of-Band (04):

Use the values in the above properties to populate values in the native UI in the app. The UI must follow the guidelines defined in the EMV 3DS specification.

The following properties are applicable when ACSUIType is HTML (05):

In the case of an HTML interaction, the app should create a webview and populate this with the HTML in ACSHTML.

As per the EMV® 3-D Secure specification, the HTML UI is presented to the cardholder via a web view which remains in control of the app. The app must intercept any remote URL requests made from within the web view, and instead handle them within the app. Preventing the cardholder from making requests in the web view to another server is critical to the security of the environment. According to the EMVCo specification, intercepting these requests has two effects:

Prevents malicious HTML from redirecting a user to a phishing site.
Conceptually puts the web view form under the control of the ACS, rather than the app.

The following are key points mentioned in the EMV 3DS specification:

Navigation attempts from within the web view must be captured by the app and handled internally. This includes all requests including images, javascript files, css, etc.
The web view element is not utilized as a browser, but as a UI element whose content is provided by the ACS.

Please refer to the EMV 3DS specification for more details and guidance on this topic. This information is not meant to replace the text in the EMV 3DS specification.

Second Request

The second time this method is called, the purpose is to provide a response to the ACS. At this point the customer should have responded to the challenge provided by the ACS in the response to the first call. If the transaction has been canceled, set ChallengeCancellationIndicator to inform the ACS. The following properties are applicable when calling this method the second time:

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

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

mobile: **** **** 329
email: s******k**@g***.com

The value to provide in ChallengeDataEntry is the Name, i.e. mobile.

When ACSUIType is Multi-Select (03), set ChallengeDataEntry to a comma-separated list of names of the selected options. For instance if ChallengeSelectInfo contains elements with names like chicago_illinois, st_louis_missouri, and portland_oregon, and the user chose two options, the value specified in ChallengeDataEntry would be chicago_illinois,portland_oregon.

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

Completing the Challenge

After calling SendChallengeRequest a second time with the cardholder's responses, the ACS may require additional challenges. Check the ChallengeComplete property to determine if the challenge is complete. If False, more challenges are required by the ACS and the same process of displaying the challenge info, collecting the response, and submitting it to the ACS should be performed again.

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

Note: As part of the challenge completion the ACS also notifies the 3DS Server of the results. This is done by posting the results to the URL defined by the ResultsURL property of the 3DS Server class.

Logging Notes

Logging in the component is handled through the Log event. This will fire anytime a message is built or a response is parsed, including error messages.

When the 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 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 DataPacketIn and DataPacketOut 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 module with short descriptions. Click on the links for further details.


ACSHTML	HTML provided by the ACS.
ACSHTMLRefresh	ACS HTML refresh.
ACSRootCertCount	The number of records in the ACSRootCert arrays.
ACSRootCertEncoded	The certificate (PEM/base64 encoded).
ACSRootCertStore	The name of the certificate store for the client certificate.
ACSRootCertStorePassword	If the certificate store is of a type that requires a password, this property is used to specify that password in order to open the certificate store.
ACSRootCertStoreType	The type of certificate store for this certificate.
ACSRootCertSubject	The subject of the certificate used for client authentication.
ACSUIType	UI type rendered by the 3DS SDK.
ChallengeAdditionalInformation	Challenge additional information text.
ChallengeCancellationIndicator	Challenge Cancellation Indicator.
ChallengeComplete	Whether or not the challenge cycle is complete.
ChallengeDataEntry	Cardholder entered data.
ChallengeInfoHeader	Challenge information screen header.
ChallengeInfoLabel	Challenge information label.
ChallengeInfoText	Challenge information text.
ChallengeInfoTextIndicator	Challenge information text indicator.
ChallengeSelectInfo	Challenge selection information.
DataPacketOut	Contains the data packet sent to the server.
DeviceParams	Device information parameters.
DirectoryServerCertEncoded	The certificate (PEM/base64 encoded).
DirectoryServerCertStore	The name of the certificate store for the client certificate.
DirectoryServerCertStorePassword	If the certificate store is of a type that requires a password, this property is used to specify that password in order to open the certificate store.
DirectoryServerCertStoreType	The type of certificate store for this certificate.
DirectoryServerCertSubject	The subject of the certificate used for client authentication.
DirectoryServerId	Value of the Registered Application Provider Identifier (RID) unique to the payment system.
ErrorPacket	The error packet.
ExpandableInformationLabel	Expandable information label.
ExpandableInformationText	Expandable information text.
Extensions	Extensions to be included in the next outgoing packet.
IssuerImageExtraHigh	Issuer image URL (extra high density).
IssuerImageHigh	Issuer image URL (high density).
IssuerImageMedium	Issuer image URL (medium density).
OOBContinuationIndicator	OOB continuation indicator.
OOBContinueLabel	OOB continuation label.
PaymentSystemImageExtraHigh	Payment system image URL (extra high density).
PaymentSystemImageHigh	Payment system image URL (high density).
PaymentSystemImageMedium	Payment system image URL (medium density).
Proxy	A set of properties related to proxy access.
ResendInformationLabel	Label for UI button allowing users to request that authentication information be resent.
SDKAppId	The unique SDK App Id.
SDKTransactionId	SDK Transaction ID.
SSLAcceptServerCertEncoded	The certificate (PEM/base64 encoded).
SSLCertEncoded	The certificate (PEM/base64 encoded).
SSLCertStore	The name of the certificate store for the client certificate.
SSLCertStorePassword	If the certificate store is of a type that requires a password, this property is used to specify that password in order to open the certificate store.
SSLCertStoreType	The type of certificate store for this certificate.
SSLCertSubject	The subject of the certificate used for client authentication.
SSLServerCertEncoded	The certificate (PEM/base64 encoded).
SubmitAuthenticationLabel	Label for UI button users select to submit authentication.
Timeout	A timeout for the component.
TransactionStatus	The transaction status from the last parsed message (ARes, RReq, or CRes).
WhitelistingDataEntry	Whitelisting Data Entry.
WhitelistingInformationText	Whitelisting information text.
WhyInformationLabel	Label for why information section.
WhyInformationText	Text to explain the authentication task to the user.

Method List

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


AddDeviceParam	Adds a device parameter to the collection.
AddExtension	Adds an extension to the collection.
AddRequestField	Adds a field to the data in the request.
CheckAuthResponse	Checks the received packet.
Config	Sets or retrieves a configuration setting.
GetAuthRequest	Prepares data to be sent by the 3DS Server.
Interrupt	Interrupts the current action.
Reset	Clears all properties to their default values.
ResetTransactionInfo	Resets transaction specific information.
SendChallengeRequest	Builds and sends the Challenge Request in an app-based challenge flow.

Event List

The following is the full list of the events fired by the module with short descriptions. Click on the links for further details.


DataPacketIn	Fired when receiving a data packet from the server.
DataPacketOut	Fired when sending a data packet to the server.
Error	Information about errors during data delivery.
Log	Fires once for each log message.
SSLServerAuthentication	Fired after the server presents its certificate to the client.
SSLStatus	Shows the progress of the secure connection.

Configuration Settings

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


AcceptAnyACSCert	Whether to accept any ACS certificate during signature validation.
ACSRenderingInterface	Challenge interface type presented to cardholder.
ACSRenderingUITemplate	Challenge type presented to cardholder.
ACSSignedContent	String value of the JWS object of the ARes message created by the ACS.
ACSTransactionId	Unique transaction identifier assigned by the ACS.
ACSURL	ACS URL to which the challenge request is sent.
ChallengeResponse	Challenge Response (CRes).
ChallengeTimeRemaining	Amount of time left to complete challenge.
DeviceRenderingInterface	SDK Interface Device Rendering Types supported.
DeviceRenderingUIType	SDK UI Types supported.
DSTransactionId	Directory server transaction ID.
ErrorCode	Code from the last error message.
ErrorDescription	Description from the last error message.
ErrorDetail	Additional details from the last error message.
IncomingExtensionCount	The number of extensions received from the directory server.
IncomingExtensionCritical[Index]	Whether the extension is critical.
IncomingExtensionData[Index]	The extension data as JSON.
IncomingExtensionId[Index]	The id of the specified extension.
IncomingExtensionName[Index]	The extension name.
IncomingRawExtensions	The full JSON formatted extension data received from the directory server.
LogLevel	Level of logging enabled.
MaskSensitive	Whether to mask sensitive data in the Log event.
MerchantAppURL	3DS Requestor App URL.
MessageType	Type of message that is passed.
OOBAppLabel	OOB app label.
OOBAppURL	OOB app URL.
OutgoingRawExtensions	The full JSON formatted extension data sent to the directory server.
ProtocolVersion	Protocol version identifier.
ResendChallengeInfo	Resend challenge information code.
SDKEphemeralPrivateKey	Private key component of the ephemeral key pair generated by the Client.
SDKEphemeralPublicKey	Public key component of the ephemeral key pair generated by the Client.
SDKMaxTimeout	SDK Maximum Timeout.
SDKReferenceNumber	Assigned SDK reference number.
ServerTransactionId	Unique transaction identifier assigned by the 3DS Server.
TransactionStatusReason	Reason for value of TransactionStatus.
UseAESGCM	Whether or not to use AESGCM as the encryption algorithm.
XChildCount	The number of child elements of the current element.
XChildName[i]	The name of the child element.
XChildXText[i]	The inner text of the child element.
XElement	The name of the current element.
XParent	The parent of the current element.
XPath	Provides a way to point to a specific element in the returned XML or JSON response.
XSubTree	A snapshot of the current element in the document.
XText	The text of the current element.
LogSSLPackets	Controls whether SSL packets are logged when using the internal security API.
OpenSSLCADir	The path to a directory containing CA certificates.
OpenSSLCAFile	Name of the file containing the list of CA's trusted by your application.
OpenSSLCipherList	A string that controls the ciphers to be used by SSL.
OpenSSLPrngSeedData	The data to seed the pseudo random number generator (PRNG).
ReuseSSLSession	Determines if the SSL session is reused.
SSLCACerts	A newline separated list of CA certificate to use during SSL client authentication.
SSLCheckCRL	Whether to check the Certificate Revocation List for the server certificate.
SSLCipherStrength	The minimum cipher strength used for bulk encryption.
SSLEnabledCipherSuites	The cipher suite to be used in an SSL negotiation.
SSLEnabledProtocols	Used to enable/disable the supported security protocols.
SSLEnableRenegotiation	Whether the renegotiation_info SSL extension is supported.
SSLIncludeCertChain	Whether the entire certificate chain is included in the SSLServerAuthentication event.
SSLNegotiatedCipher	Returns the negotiated ciphersuite.
SSLNegotiatedCipherStrength	Returns the negotiated ciphersuite strength.
SSLNegotiatedCipherSuite	Returns the negotiated ciphersuite.
SSLNegotiatedKeyExchange	Returns the negotiated key exchange algorithm.
SSLNegotiatedKeyExchangeStrength	Returns the negotiated key exchange algorithm strength.
SSLNegotiatedVersion	Returns the negotiated protocol version.
SSLProvider	The name of the security provider to use.
SSLSecurityFlags	Flags that control certificate verification.
SSLServerCACerts	A newline separated list of CA certificate to use during SSL server certificate validation.
TLS12SignatureAlgorithms	Defines the allowed TLS 1.2 signature algorithms when UseInternalSecurityAPI is True.
TLS12SupportedGroups	The supported groups for ECC.
TLS13KeyShareGroups	The groups for which to pregenerate key shares.
TLS13SignatureAlgorithms	The allowed certificate signature algorithms.
TLS13SupportedGroups	The supported groups for (EC)DHE key exchange.

/n software 3-D Secure V2 macOS Edition