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.
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:
|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)
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.
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)
- BrowserUserAgent (required in 2.1.0 and 2.2.0)
- BrowserIPAddress (conditional in 2.1.0 and 2.2.0)
After calling this method the TransactionStatus property holds the result. Possible values are:
|C||Cardholder challenge required|
|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:
- ACSURL (if challenge required)
- ACSChallengeMandatedIndicator (if challenge required)
- AuthenticationType (if challenge required)
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.
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.
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 web view element is not utilized as a browser, but as a UI element whose content is provided by the ACS.
The second time this method is called, the purpose is to provide a response to the ACS. At this point the customer should have responded to the challenge provided by the ACS in the response to the first call. If the transaction has been canceled, set 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***.comThe 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 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:
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.
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.|
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.|
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.|
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.|