/n software 3-D Secure V2 Node.js Edition

Questions / Feedback?

Client Class

Properties   Methods   Events   Configuration Settings   Errors  

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

Syntax

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:

PropertyDescription
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 CardRangeMethodURL has been set by the ACS. Card range data may be retrieved by calling RequestCardRanges.

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

If a CardRangeMethodURL 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:

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 ChallengeSelectInfoName, 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 class with short descriptions. Click on the links for further details.

ACSHTMLHTML provided by the ACS.
ACSHTMLRefreshACS HTML refresh.
ACSRootCertCountThe number of records in the ACSRootCert arrays.
ACSRootCertEncodedThe certificate (PEM/base64 encoded).
ACSRootCertStoreThe name of the certificate store for the client certificate.
ACSRootCertStorePasswordIf 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.
ACSRootCertStoreTypeThe type of certificate store for this certificate.
ACSRootCertSubjectThe subject of the certificate used for client authentication.
ACSUITypeUI type rendered by the 3DS SDK.
ChallengeAdditionalInformationChallenge additional information text.
ChallengeCancellationIndicatorChallenge Cancellation Indicator.
ChallengeCompleteWhether or not the challenge cycle is complete.
ChallengeDataEntryCardholder entered data.
ChallengeInfoHeaderChallenge information screen header.
ChallengeInfoLabelChallenge information label.
ChallengeInfoTextChallenge information text.
ChallengeInfoTextIndicatorChallenge information text indicator.
ChallengeSelectInfoCountThe number of records in the ChallengeSelectInfo arrays.
ChallengeSelectInfoNameThe name of the selection option.
ChallengeSelectInfoValueThe value of the selection option.
DataPacketOutContains the data packet sent to the server.
DeviceParamCountThe number of records in the DeviceParam arrays.
DeviceParamCategoryThe category of the parameter.
DeviceParamFieldNameThe name of the parameter.
DeviceParamValueThe value of the parameter.
DeviceParamValueTypeThe type of the value.
DirectoryServerCertEncodedThe certificate (PEM/base64 encoded).
DirectoryServerCertStoreThe name of the certificate store for the client certificate.
DirectoryServerCertStorePasswordIf 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.
DirectoryServerCertStoreTypeThe type of certificate store for this certificate.
DirectoryServerCertSubjectThe subject of the certificate used for client authentication.
DirectoryServerIdValue of the Registered Application Provider Identifier (RID) unique to the payment system.
ErrorPacketThe error packet.
ExpandableInformationLabelExpandable information label.
ExpandableInformationTextExpandable information text.
ExtensionCountThe number of records in the Extension arrays.
ExtensionCriticalWhether the extension is critical.
ExtensionDataThe extension data as JSON.
ExtensionIdThe id of the specified extension.
ExtensionNameThe extension name.
IssuerImageExtraHighIssuer image URL (extra high density).
IssuerImageHighIssuer image URL (high density).
IssuerImageMediumIssuer image URL (medium density).
OOBContinuationIndicatorOOB continuation indicator.
OOBContinueLabelOOB continuation label.
PaymentSystemImageExtraHighPayment system image URL (extra high density).
PaymentSystemImageHighPayment system image URL (high density).
PaymentSystemImageMediumPayment system image URL (medium density).
ProxyAuthSchemeThis property is used to tell the class which type of authorization to perform when connecting to the proxy.
ProxyAutoDetectThis property tells the class whether or not to automatically detect and use proxy system settings, if available.
ProxyPasswordThis property contains a password if authentication is to be used for the proxy.
ProxyPortThis property contains the TCP port for the proxy Server (default 80).
ProxyServerIf a proxy Server is given, then the HTTP request is sent to the proxy instead of the server otherwise specified.
ProxySSLThis property determines when to use SSL for the connection to the proxy.
ProxyUserThis property contains a user name, if authentication is to be used for the proxy.
ResendInformationLabelLabel for UI button allowing users to request that authentication information be resent.
SDKAppIdThe unique SDK App Id.
SDKTransactionIdSDK Transaction ID.
SSLAcceptServerCertEncodedThe certificate (PEM/base64 encoded).
SSLCertEncodedThe certificate (PEM/base64 encoded).
SSLCertStoreThe name of the certificate store for the client certificate.
SSLCertStorePasswordIf 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.
SSLCertStoreTypeThe type of certificate store for this certificate.
SSLCertSubjectThe subject of the certificate used for client authentication.
SSLServerCertEncodedThe certificate (PEM/base64 encoded).
SubmitAuthenticationLabelLabel for UI button users select to submit authentication.
TimeoutA timeout for the class.
TransactionStatusThe transaction status from the last parsed message (ARes, RReq, or CRes).
WhitelistingDataEntryWhitelisting Data Entry.
WhitelistingInformationTextWhitelisting information text.
WhyInformationLabelLabel for why information section.
WhyInformationTextText to explain the authentication task to the user.

Method List


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

AddDeviceParamAdds a device parameter to the collection.
AddExtensionAdds an extension to the collection.
AddRequestFieldAdds a field to the data in the request.
CheckAuthResponseChecks the received packet.
ConfigSets or retrieves a configuration setting.
GetAuthRequestPrepares data to be sent by the 3DS Server.
InterruptInterrupts the current action.
ResetClears all properties to their default values.
ResetTransactionInfoResets transaction specific information.
SendChallengeRequestBuilds and sends the Challenge Request in an app-based challenge flow.

Event List


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

DataPacketInFired when receiving a data packet from the server.
DataPacketOutFired when sending a data packet to the server.
ErrorInformation about errors during data delivery.
LogFires once for each log message.
SSLServerAuthenticationFired after the server presents its certificate to the client.
SSLStatusShows the progress of the secure connection.

Configuration Settings


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

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

Copyright (c) 2022 /n software inc. - All rights reserved.
/n software 3-D Secure V2 Node.js Edition - Version 2.2 [Build 8318]