PCI Watch

Tracking changes across the Payment Card Industry

EMV® 3-D Secure SDK Specification

v2.3.1.1 Specifications
3-D Secure

EMV® 3-D Secure SDK Specification Version 2.3.1.1 May 2023

EMV® 3-D Secure SDK Specification v2.3.1.1

Introduction

Legal Notice

/ 137 The EMV® Specifications are provided “AS IS” without warranties of any kind, and EMVCo neither assumes nor accepts any liability for any errors or omissions contained in these Specifications. EMVCO DISCLAIMS ALL REPRESENTATIONS AND WARRANTIES, EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NONINFRINGEMENT, AS TO THESE SPECIFICATIONS. EMVCo makes no representations or warranties with respect to intellectual property rights of any third parties in or in relation to the Specifications. EMVCo undertakes no responsibility to determine whether any implementation of the EMV® Specifications may violate, infringe, or otherwise exercise the patent, copyright, trademark, trade secret, know-how, or other intellectual property rights of third parties, and thus any person who implements any part of the EMV® Specifications should consult an intellectual property attorney before any such implementation. Without limiting the foregoing, the Specifications may provide for the use of public key encryption and other technology, which may be the subject matter of patents in several countries. Any party seeking to implement these Specifications is solely responsible for determining whether its activities require a license to any such technology, including for patents on public key encryption technology. EMVCo shall not be liable under any theory for any party’s infringement of any intellectual property rights in connection with the EMV® Specifications.

Introduction

/ 137 Revision Log The following table lists the version history for the EMV® 3-D Secure SDK Specification. EMVCo Specification Bulletins provide the detailed updates made with each specification release. Version Release Date 2.1.0 October 2017 2.2.0 December 2018 2.3.0.0 2.3.1.0 2.3.1.1 September 2021 August 2022 May 2023 Associated Specification Bulletins SB 205: EMV® 3-D Secure SDK and Device Information Updates, Clarifications & Errata for v2.1.0 SB 211: EMV® 3-D Secure SDK Updates, Clarifications & Errata EMV® 3-D Secure SDK Specification version 2.3.0.0 SB 275: EMV® 3-D Secure SDK Specification version 2.3.1.0 SB 296: EMV® 3-D Secure SDK Specification version 2.3.1.1

Introduction

2.2. 2.2. 2.3.1 2.3.2 2.3. 3.2. 3.3. 3.3. 3.4.1 3.4.2 3.4.3 3.4. 4. 4.1.1 4.1.2 4.1.

Introduction

/ 137 4.1. 4.1. 4.2.1 4.2.2 4.2. 4.3.1 4.3.2 4.3.3 4.3.4 4.3. 4.4.1 4.4.2 4.4.3 4.4. 4.5.1 4.5.2 4.5.3 4.5.4 4.5.5 4.5.6 4.5.7 4.5.8 4.5.9 4.5. 4.6.1 4.6.2 4.6.3 4.6.4 4.6.5 4.6. 4.7.1 4.7.2 4.7.3 4.7.

Introduction

4.8.1 4.8.2 4.8.3 4.8.4 4.8.5 4.8. 4.9.1 4.9.2 4.9.3 4.9.4 4.9.5 4.9. 4.10.1 4.10.2 4.10.3 4.10.4 4.10.5 4.10. 4.11. 4.11. 4.11. 4.11. 4.11. 4.11. 4.11. 4.11. 4.11. 4.11. 4.12.1 4.12.2 4.12.3 4.12.4 4.12.5 4.12.6 4.12.

Introduction

4.13.1 4.13.2 4.13.3 4.13.4 4.13.5 4.13.6 4.13. 4.14. 4.14. 4.14. 4.15. 4.15. 4.15. 4.16. 4.16. 4.16. 4.17. 4.17. 4.17. 4.17. 4.18. 4.19. 4.20. 4.21. 4.21.

Introduction

7.2. 7.2. 3DS SDK Versioning Requirements and Protocol Versioning Support... A. A. C. C. C.

Introduction

Introduction

/ 137 Tables Table 3. Table 3. Table 3. Table 3. Table 4. Table 4. Table 4. Table 4. Table 4. Table 4. Table 4. Table 4. Table 4. Table 4. Table 4. Table 4. Table 4. Table 4. Table 4. Table 4. Table 4. Table 4. Table 4. Table 4. Table 4. Table 4. Table 4. Table 4. Table 4. Table 4. Table 4. Table 4. Table 4. Table 4. Table 4. Table 4. Table 4. Table 4. Table 4. Table 4.

Introduction

/ 137 Table 4.37: Table 4.38: Table 4.39: Table 4.40: Table 4.41: Table 4.42: Table 4.43: Table 4.44: Table 4.45: Table 4.46: Table 4.47: Table 4.48: Table 4.49: Table 4.50: Table 4.51: Table 4.52: Table 4.53: Table 4.54: Table 4.55: Table 4.56: Table 4.57: Table 4.58: Table 4.59: Table 4.60: Table 4.61: Table 4.62: Table 4.63: Table 4.64: Table 4.65: Table 4.66: Table 4.67: Table 4.68: Table 4.69: Table 4.70: Table 4.71: Table 4.72: Table 4.73: Table 4.74: Table 4.75: Table 4.76: Table 4.77: Table 4.

Introduction

/ 137 Table 4. Table 4. Table 4. Table 4. Table 4. Table 4. Table 4. Table 4. Table 4. Table 4. Table 4. Table 4. Table 4. Table 4. Table 4. Table 4. Table 4. Table 4. Table 4. Table 4. Table 4. Table 4. Table 4. Table 4. Table 4. Table 4. Table 5. Table 5. Table 8. Table A.

Introduction

/ 137 1 Introduction The EMV® 3-D Secure protocol is aimed at securing authentication in both browser-based and mobile-based apps. The mobile-device-side component of 3-D Secure is the 3DS Default SDK (later referred to as 3DS SDK in this document). 3-D Secure Requestors, such as Merchants, integrate this SDK with their mobile App and make the App available to end users.

Purpose

This document specifies the requirements for the EMV 3-D Secure Default SDK. For purposes of this document, when the phrase 3-D Secure, and/or 3DS is utilised, the intent is EMV 3-D Secure. Audience This document is intended for use by implementers who want to develop a 3DS Default SDK. Normative

References

For the standards containing provisions that are referenced in this specification refer to Table 1.1 of the EMV® 3-D Secure Protocol and Core Functions Specification (hereinafter referred to as the Core Specification).

Definitions

For the definition of the terms used in this specification, refer to Table 1.3 in the Core Specification. Abbreviations For the abbreviations used in this specification, refer to Table 1.4 of the Core Specification.

Introduction

/ 137 Supporting Documentation The following documents are specific to the EMV 3-D Secure protocol and should be used in conjunction with this specification. These documents as well as the EMV® 3-D Secure Frequently Asked Questions are located on the EMVCo website under the 3-D Secure heading.

  • EMV® 3-D Secure—Protocol and Core Functions Specification
  • EMV® 3-D Secure SDK Technical Guide
  • EMV® 3-D Secure SDK—Device Information
  • EMV® 3-D Secure Split-SDK Specification
  • EMV® 3-D Secure JSON Message Samples Terminology and Conventions The following words are used often in this specification and have a specific meaning: Shall Defines a product or system capability which is mandatory. May Defines a product or system capability which is optional or a statement which is informative only and is out of scope for this specification. Should Defines a product or system capability which is recommended. Ends 3-D Secure Processing As outlined in Chapter 3 of the Core Specification, defines a specific exception scenario in the 3-D Secure authentication flows where further processing is outside the scope of this specification. Refer to Table 1.3 in the Core Specification for additional information. Ends Processing As outlined in Chapter 3 of the Core Specification, defines a specific exception scenario in the 3-D Secure authentication flows where a 3-D Secure component experiences an error and does not process the transaction normally. Therefore, subsequent components take action on the error instance. Refer to Table 1.3 in the Core Specification for additional information. 3DS SDK When this specification refers to the 3DS SDK, EMVCo has defined two options for a 3DS SDK implementation. The options are as follows: Introduction / 137 1. Default-SDK—Software component designed as an SDK that is integrated into a 3DS Requestor App. In earlier versions of the Core Specification, this is referred to as the 3DS SDK. 2. Split-SDK—Client-server implementation of the 3DS SDK. Some functions of the SplitSDK entity can be performed by either the Split-SDK Client or the Split-SDK Server or, in some situations, both. This SDK option is defined in the EMV 3-D Secure—Split-SDK Specification. Unless explicitly noted otherwise, the term 3DS SDK applies as identified above. Refer to the applicable SDK specification for detailed information regarding either SDK option. Activate the 3DS SDK Detailed information about the 3DS SDK activation can be obtained in the applicable 3DS SDK specification. When the Core Specification refers to "Activate the 3DS SDK" in the context of a SDK implementation, the applicable action is the initialize method as defined in Section 4.1.1 of this specification. Perform the Challenge Detailed information about the 3DS SDK performing the challenge can be obtained in the applicable 3DS SDK specification. When the Core Specification refers to "Perform the Challenge" in the context of a SDK implementation, the applicable action is the doChallenge method as defined in Section 4.4.2 of this specification. EMV 3-D Secure Architecture and Flows Overview / 137 2 EMV 3-D Secure Architecture and Flows Overview This chapter provides an overview of the components in the 3-D Secure architecture and an introduction to the 3-D Secure authentication flows. For detailed information about these components and authentication flows, see Chapter 2 of the Core Specification. Participating Components Figure 2-1 illustrates the interaction of the components in the EMV 3-D Secure ecosystem. Figure 2-1: EMV 3-D Secure Component Interaction 1, 2, 7 9, 10 3, 5 11, 12 3, 6 11, 12 EMV 3-D Secure Architecture and Flows Overview / 137 Authentication Flow Overview This section provides an overview of the following two 3-D Secure authentication flows:
  • Frictionless Flow
  • Challenge Flow 2.2.1 Frictionless Flow The Frictionless Flow initiates a 3-D Secure authentication flow and consists of an AReq message and an ARes message. The Frictionless Flow does not require further Cardholder interaction to achieve a successful authentication and complete the 3-D Secure authentication process. The following steps provide a high-level view of the Frictionless Flow: Start: The Cardholder initiates a transaction using a 3DS Requestor App on a Consumer Device. 1. The 3DS SDK collects the device information and provides it to the 3DS Requestor App. 2. The 3DS Requestor App initiates communication with the 3DS Server and provides the information that is required to create an AReq message. 3. The 3DS Server creates and sends an AReq message to the DS. The DS then forwards the message to the appropriate ACS. 4. The ACS evaluates the payment, Cardholder, and device authentication data provided in the message. 5. If the ACS determines that the transaction does not require additional authentication, then the ARes message that it returns to the DS indicates that the Frictionless Flow must be applied. 6. The DS forwards the message to the 3DS Server. 7. The 3DS Server communicates the result of the ARes message to the 3DS Requestor App. Note: 3-D Secure processing ends here. For Payment Authorisation, the subsequent steps apply: 8. The Merchant proceeds with authorisation exchange with its Acquirer. If appropriate, the Merchant, Acquirer, or Payment Processor can submit a standard authorisation request. 9. The Acquirer can process an authorisation with the Issuer through the DS and return the authorisation results to the Merchant.

2.2.2 Challenge Flow In addition to the AReq and ARes messages that comprise the Frictionless Flow, the Challenge Flow consists of CReq, CRes, RReq, and RRes messages. If the ACS determines that further Cardholder interaction is required to complete the authentication, the Frictionless Flow transitions into the Challenge Flow. For example, a challenge may be necessary because the transaction is deemed high-risk, is above certain thresholds, or requires a higher level of authentication due to country mandates (or regulations).

EMV 3-D Secure Architecture and Flows Overview

/ 137 3DS Requestors decide whether to proceed with the challenge, or to terminate the 3-D Secure authentication process. The following steps provide a high-level view of the Challenge Flow: Start: The Cardholder initiates a transaction using a 3DS Requestor App on a Consumer Device. 1. The 3DS SDK collects the device information and provides it to the 3DS Requestor App. 2. The 3DS Requestor App initiates communication with the 3DS Server and provides the information that is required to create an AReq. 3. The 3DS Server creates and sends an AReq message to the DS. The DS then forwards the message to the ACS. 4. The ACS evaluates the payment, Cardholder, and device authentication data provided in the message. 5. If the ACS determines that the transaction requires additional authentication, then the ARes message that it returns to the DS indicates that the Challenge Flow must be Applied. 6. The DS forwards the message to the 3DS Server. 7. The 3DS Server returns the authentication status to the 3DS Requestor App. 8. The 3DS Requestor App invokes the 3DS SDK to perform Cardholder authentication. 9. The 3DS SDK sends a CReq message directly to the ACS. 10. The ACS receives the CReq message and returns a CRes message to the 3DS SDK. Note: Based on the CRes obtained from the ACS, the 3DS SDK displays the challenge-specific screens for the Cardholder to enter their authentication credentials. Steps 9 and 10 are repeated until the ACS has determined the outcome of the authentication. 11. The ACS sends an RReq message to the DS, which then forwards the message to the 3DS Server. 12. The 3DS Server receives an RReq message and returns an RRes message to the DS, which then forwards the message to the ACS. 13. The ACS sends the final CRes message to the 3DS SDK with the outcome of the authentication. Note: 3-D Secure processing ends here. For Payment Authorisation, the subsequent steps apply: 14. The Merchant proceeds with authorisation exchange with its Acquirer. If Appropriate, the Merchant, Acquirer, or Payment Processor can submit a standard authorisation request. 15. The Acquirer can process an authorisation with the Issuer through the Payment System and return the authorisation results to the Merchant.

EMV 3-D Secure Architecture and Flows Overview

/ 137 UI Types for Challenge Flow The UI for the Challenge Flow can be rendered in one of the following formats:

  • Native UI
  • HTML UI 2.3.1 Challenge Flow Implemented Using Native UI The Native UI integrates into the 3DS Requestor App UI to facilitate a consistent user experience. The Native UI has a similar look and feel as the 3DS Requestor’s App with the authentication content provided by the Issuer. This format also allows for Issuer and Payment System branding. Both the 3DS Requestor App and the 3DS SDK control the rendering of the UI such that the authentication pages inherit the 3DS Requestor’s UI design elements. For more information about the Native UI, refer to Section 4.2.2 of the Core Specification.

2.3.2 Challenge Flow Implemented Using HTML UI The HTML UI provides Cardholders with an Issuer-consistent App-based experience across Consumer Devices that are able to render HTML. The HTML UI templates provides Issuers the ability to include Issuer-specific design elements (for example, branding, colours, and/or fonts). The HTML UI implementation establishes a client-server relationship between the ACSprovided HTML document loaded in a 3DS Requestor’s web view and the SDK process itself. This is accomplished by intercepting remote URL requests issued by the web view, and handling them within the SDK, rather than allowing them to pass through to the Consumer Device operating system and hence on to the Internet. This has two effects:

  • Prevents maliciously formed HTML within the web view flow from requesting external resources or redirecting to an external malicious site (for example, a phishing page).
  • Changes the web view form into an extension of the SDK’s UI, one that’s defined by the remote ACS using HTML, rather than by the SDK or 3DS Requestor’s App. For more information about the HTML UI, refer to Section 4.2.5 of the Core Specification.

2.3.3 Challenge Flow Implemented Using Out-of-Band (OOB) UI The Out-of-Band (OOB) user interface allows Issuers to utilise authentication methods other than dynamic and static data such as an Issuer’s mobile App. When an OOB challenge is necessary, the Issuer/ACS provides instructions to the Cardholder to explain the authentication process.

Getting Started with the EMV 3-D Secure Default SDK

/ 137 3 Getting Started with the EMV 3-D Secure Default SDK The EMV 3-D Secure Default SDK (3DS SDK) is a client-side component of the 3-D Secure ecosystem. When a Cardholder initiates an in-App transaction, the 3DS SDK integrated in the 3DS Requestor App performs operations related to 3-D Secure authentication. This chapter provides an overview of the 3DS SDK components, lifecycle and flows. Component Architecture Figure 3-1 shows the 3DS SDK component architecture. Figure 3-1: 3DS SDK Component Architecture 1. The 3DS Requestor App collects the parameters that are required for authentication from the 3DS SDK and initiates the authentication flow. 2. If the authentication flow indicates that no challenge is required, then the Frictionless Flow is applied.

Getting Started with the EMV 3-D Secure Default SDK

/ 137 If the authentication flow indicates that a challenge is required, then the 3DS Requestor App invokes the 3DS SDK to apply the Challenge Flow. 3. The 3DS SDK performs the following steps: a. Communicate with the ACS to initiate the Challenge Flow. b. Display the challenge UI to the Cardholder. c. Collect the Cardholder’s challenge response. d. Complete the Challenge Flow. e. Return the Challenge Response to the 3DS Requestor App. Lifecycle Figure 3-2 provides a high-level view of the lifecycle of the 3DS SDK. Figure 3-2: High-Level 3DS SDK Lifecycle

Getting Started with the EMV 3-D Secure Default SDK

/ 137 3.2.1 Lifecycle Phases Initialization The initialization phase takes place during either the 3DS Requestor App startup as a background task or when a transaction is initiated. In this phase, the SDK collects device information against the protocol versions that it supports and performs security checks. This phase takes place only once during a single 3DS Requestor App session. Obtaining authentication request parameters The 3DS SDK, while adhering to the protocol version for the transaction, encrypts the device information that it collects during initialization and send this information along with the SDK information to the 3DS Requestor App. Cardholder authentication If a challenge is required, then the 3DS SDK performs cardholder authentication. Cleanup The cleanup phase is called only once during a single 3DS Requestor App session to free up resources that are used by the 3DS SDK. Authentication Flows The following sections show the interaction between the 3DS Requestor App and the 3DS SDK code elements during the Frictionless Flow and the Challenge Flow. Note: In these sections, a diagram showing the flow is followed by a sequence of steps that provide a more detailed description of the flow. If the steps are not in agreement with the diagram at any point, then the steps take precedence over the diagram.

3.3.1 Frictionless Flow Figure 3-3 shows the interaction between the 3DS Requestor App and the 3DS SDK code elements during the Frictionless Flow.

Getting Started with the EMV 3-D Secure Default SDK Figure 3-3: Frictionless Flow

/ 137 The following steps summarise the events that occur during the Frictionless Flow: 1. The Cardholder launches the 3DS Requestor App. 2. The 3DS Requestor App creates instances of ConfigParameters, locale and UiCustomization for initialization. 3. The 3DS Requestor App calls the initialize method to initialize the 3DS SDK either during App startup as a background task or when a transaction is initiated. Note: This method is called only once during a single 3DS Requestor App session.

Getting Started with the EMV 3-D Secure Default SDK

/ 137 4. In the initialize method call, the 3DS SDK shall: Seq 3.1 [Req 1] Perform security checks and generate warnings for each security check that fails. Seq 3.2 [Req 2] Collect device information. Note: Steps 5 to 18 are performed per transaction. There can be multiple transactions in a single 3DS Requestor App session. 5. The Cardholder submits payment information by using the 3DS Requestor App. 6. (Optional) The 3DS Requestor App calls the getWarnings method. 7. In the getWarnings method call, the 3DS SDK shall: Seq 3.3 [Req 3] Return a list of warnings produced by the 3DS SDK during initialization. 8. (Optional) The 3DS Requestor App may call the getSDKVersion. 9. In the getSDKVersion method call, the 3DS SDK shall: Seq 3.4 [Req 4] Return the version of the 3DS SDK that is integrated with the 3DS Requestor App. 10. The 3DS Requestor App calls the createTransaction method. 11. In the createTransaction method call, the 3DS SDK shall: Seq 3.5 [Req 5] Create and return an instance of the Transaction interface implementation. 12. The 3DS Requestor App calls the getProgressView method. 13. In the getProgressView method call, the 3DS SDK returns an instance of Progress View (processing screen). Refer to [Req 141]–[Req 144] in the Core Specification for additional detail. Returns an instance of Progress View (processing screen). 14. The 3DS Requestor App calls the getAuthenticationRequestParameters method. 15. In the getAuthenticationRequestParameters method call, the 3DS SDK shall: Seq 3.6 [Req 7] Return the device information and 3DS SDK information, i.e., SDK transaction ID, Ephemeral public key, protocol version used, etc. 16. The 3DS Requestor App and the 3DS Requestor Environment together execute the AReq message flow. 17. The ARes message that is returned indicates that the Frictionless Flow must be applied. Therefore, no further action is required. 18. The 3DS Requestor App calls the close method to allow the 3DS SDK to clean up resources that are held by the Transaction object. 19. The 3DS Requestor App calls the cleanup method to allow the 3DS SDK to free up resources that were used. Note: The cleanup method shall be called only once during a 3DS Requestor App session.

Getting Started with the EMV 3-D Secure Default SDK

/ 137 3.3.2 Challenge Flow Figure 3-4 shows the interaction between the 3DS Requestor App and the 3DS SDK code elements during the Challenge Flow. Figure 3-4: Challenge Flow The following steps summarise the events that take place during the Challenge Flow: Note: Steps 1 to 16 are the same as the steps in the Frictionless Flow. 17. The ARes message that is returned indicates whether the Challenge Flow is applied. 18. The 3DS Requestor App creates a callback object. This object implements the ChallengeStatusReceiver interface to receive challenge status notification from the 3DS SDK at the end of the challenge process.

Getting Started with the EMV 3-D Secure Default SDK

/ 137 19. The 3DS Requestor App calls the doChallenge method. One of the parameters of the doChallenge method is ChallengeStatusReceiver. The 3DS Requestor App passes the callback object created as part of Step 18 using this parameter to the 3DS SDK. Another parameter that is passed by the 3DS Requestor App is a timeout value (in minutes) for the Challenge process. 20. In the doChallenge method call, the 3DS SDK shall: Seq 3.7 [Req 66] Start a timer to measure the time taken by the challenge process. Note: Within a single doChallenge method call, steps 21 to 23 shall be performed for each CReq/CRes exchange. 21. The 3DS SDK initiates the Challenge Flow by displaying the UI for the challenge screens as defined in [Req 358] of the Core Specification. 22. The Cardholder responds to the challenge. 23. The 3DS SDK uses a graphical element (a processing view) on the Challenge screen to show that the Cardholder’s response is being processed. Refer to [Req 147], [Req 148] and [Req 151] in the Core Specification for additional detail. 24. The 3DS SDK shall: Seq 3.8 [Req 10] Call one of the methods (completed, cancelled, protocolError or runtimeError) of the ChallengeStatusReceiver callback object to return the result of the challenge process to the 3DS Requestor App. After the method is run, the 3DS SDK gets back control and cleans up resources that are held by the Transaction object (implementer-specific). Seq 3.9 [Req 67] If a timeout occurs at any point, that is, if the time taken by the challenge process as measured by the timer (refer to Step 20) exceeds the timeout value (minimum of 5 minutes) passed by the 3DS Requestor App (refer Step 19), then the 3DS SDK shall:

  • Send an Error Message (as defined in Section A.9 of the Core Specification) to the ACS with Error Component = C and Error Code = 402.
  • Call the timedout method of the ChallengeStatusReceiver callback object.
  • Clean up resources that are held by the Transaction object. Note: The last step in this flow is the cleanup step which is the same as Step 19 in the Frictionless Flow. Summary of 3DS SDK Code Elements The following tables provide a summary of the code elements to include in the 3DS SDK package.

3.4.1 Interface

Summary

Table 3.1 summarises the interfaces to be included in the 3DS SDK package.

Getting Started with the EMV 3-D Secure Default SDK Table 3.1: Interfaces

/ 137

Requirement

ID Interface [Req 11] ThreeDS2Service [Req 12] ChallengeStatusReceiver [Req 13] Transaction

Description

This interface shall provide methods to process 3-D Secure transactions. For detailed information, see Interface ThreeDS2Service. This interface shall provide methods to receive challenge status notifications from the 3DS SDK. For detailed information, see Interface ChallengeStatusReceiver. An object that implements the Transaction interface shall hold parameters that are required to create AReq messages and to perform the Challenge Flow. For detailed information, see Interface Transaction.

3.4.2 Class Summary Table 3.2 summarises the classes to be included in the 3DS SDK package. Table 3.2: Classes Requirement ID Class [Req 14] ConfigParameters [Req 15] ChallengeParameters Description This class shall represent the configuration parameters that are required by the 3DS SDK for initialization. For detailed information, see Class ConfigParameters. This class shall hold the data that is required to conduct a challenge process. For detailed information, see Class ChallengeParameters.

Getting Started with the EMV 3-D Secure Default SDK

/ 137 Requirement ID Class Description [Req 16] AuthenticationRequestParamete rs This class shall hold transaction data that the 3DS Server requires to create the AReq. For detailed information, see Class AuthenticationRequestParame ters. [Req 17] UiCustomization This class shall provide the functionality required for 3DS SDK UI customization. For detailed information, see Class UiCustomization. [Req 18] Customization This class shall serve as a superclass for the ButtonCustomization class, ToolbarCustomization class, LabelCustomization class, and TextBoxCustomization class. This class shall provide methods to pass UI customization parameters to the 3DS SDK. For detailed information, see Class Customization. [Req 19] ButtonCustomization This class shall provide methods for the 3DS Requestor App to pass button customization parameters to the 3DS SDK. For detailed information, see Class ButtonCustomization. [Req 20] ToolbarCustomization This class shall provide methods for the 3DS Requestor App to pass toolbar customization parameters to the 3DS SDK. For detailed information, see Class ToolbarCustomization. [Req 21] LabelCustomization This class shall provide methods for the 3DS Requestor App to pass label customization parameters to the 3DS SDK. For detailed information, see Class LabelCustomization.

Getting Started with the EMV 3-D Secure Default SDK Requirement ID Class [Req 22] TextBoxCustomization [Req 23] ErrorMessage [Req 24] CompletionEvent [Req 25] RuntimeErrorEvent [Req 26] ProtocolErrorEvent [Req 27] Warning

/ 137 Description This class shall provide methods for the 3DS Requestor App to pass text box customization parameters to the 3DS SDK. For detailed information, see Class TextBoxCustomization. This class shall represent an error message that is returned by the ACS to the 3DS SDK or an error message that is generated by the 3DS SDK to be returned to the ACS. For detailed information, see Class ErrorMessage. This class shall represent an event that indicates that the challenge process has been completed. For detailed information, see Class CompletionEvent. This class shall represent a run-time error that is encountered during the authentication process. For detailed information, see Class RuntimeErrorEvent. This class shall represent an EMV 3-D Secure protocol-defined error that is returned by the ACS. For detailed information, see Class ProtocolErrorEvent. This class shall represent a warning produced by the 3DS SDK while performing security checks during initialization. For detailed information, see Class Warning.

3.4.3 Exception Summary Table 3.3 summarises the exceptions to be included in the 3DS SDK package.

Getting Started with the EMV 3-D Secure Default SDK Table 3.3: Exceptions

/ 137 Requirement ID Exception Description [Req 28] InvalidInputException This exception shall be thrown if an input parameter is invalid. For detailed information, see Class InvalidInputException. [Req 29] SDKAlreadyInitializedException This exception shall be thrown if the 3DS SDK instance has already been initialized. For detailed information, see Class SDKAlreadyInitializedExcep tion. [Req 30] SDKNotInitializedException This exception shall be thrown if the 3DS SDK instance has not been initialized. For detailed information, see Class SDKNotInitializedException. [Req 31] SDKRuntimeException This exception shall be thrown if an internal error is encountered by the 3DS SDK. For detailed information, see Class SDKRuntimeException.

3.4.4 Enum Summary Table 3.4 summarises the enum to be included in the 3DS SDK package. Table 3.4: Enum Requirement ID [Req 32] Severity Enum [Req 33] ButtonType Description This enum shall define severity levels of warnings produced by the 3DS SDK. For detailed information, see Enum Severity. This enum shall define the button type. For detailed information, see Enum ButtonType.

Getting Started with the EMV 3-D Secure Default SDK Requirement ID Enum [Req 34] UICustomizationType

/ 137 Description This enum shall define the UICustomization type. For detailed information, see Enum UICustomization Type.

Code Elements of the EMV 3-D Secure Default SDK

/ 137 4 Code Elements of the EMV 3-D Secure Default SDK The 3DS SDK package contains code elements that describe and define the contracts between the 3DS Requestor App and the 3DS SDK. This chapter provides detailed information about these code elements. Note: The information in this chapter is not intended to be specific to any platform or programming language. However, for instructional purposes, Java-based and Android-based code samples have been used to illustrate how to use this information. These code samples can be adapted and used on any mobile platform or programming language.

4.1 Interface ThreeDS2Service The ThreeDS2Service interface is the main 3DS SDK interface and it provides methods to process transactions. The following Java code snippet shows the definition of the ThreeDS2Service interface: public interface ThreeDS2Service { public void initialize(...) public Transaction createTransaction (...) public void cleanup(...) public String getSDKVersion(...) public List getWarnings(...) } Table 4.1 summarises the methods that are provided by the ThreeDS2Service interface. Table 4.1: ThreeDS2Service Interface Methods Method initialize Description Initializes the 3DS SDK instance.

Code Elements of the EMV 3-D Secure Default SDK

/ 137 Method Description createTransaction Creates an instance of Transaction through which the 3DS Requestor App gets the data that is required to perform the transaction. cleanup Frees up resources that are used by the 3DS Requestor App until it is closed. It shall be called only once during a single 3DS Requestor App session. getSDKVersion Returns the version of the 3DS SDK that is integrated with the 3DS Requestor App. getWarnings Returns warnings produced by the 3DS SDK while performing security checks during initialization. 4.1.1 initialize The 3DS Requestor App calls the initialize method at the start of the payment stage of a transaction. The App passes configuration parameters, UI configuration parameters, and (optionally) user locale to this method. Note: The ThreeDS2Service instance is unusable until it is initialized. The following tasks are performed during initialization:

  • Security checks
  • Collection of device information for all versions of the protocol that the SDK supports. For more information about the device identification parameters that are collected, refer to the EMV 3-D Secure SDK—Device Information. Depending on the 3DS Requestor App implementation, a ThreeDS2Service instance is called either during 3DS Requestor App startup as a background task or when a transaction is initiated. The state is maintained until the cleanup method is called. The following Android code snippet shows the signature of the initialize method: public void initialize(android.content.Context ApplicationContext, ConfigParameters configParameters, String locale, Map uiCustomizationMap) throws InvalidInputException, SDKAlreadyInitializedException, SDKRuntimeException initialize Parameters Parameter ApplicationContext Table 4.2: initialize Parameters Mandatory Description Yes An instance of Android Application context. Code Elements of the EMV 3-D Secure Default SDK / 137 Parameter configParameters locale uiCustomizationMap Mandatory Description Yes Configuration information used during initialization. For more information, see Class ConfigParameters. No String that represents the locale for the App’s user interface. For example, the value of locale can be “en-US” in Java. Note: If this parameter is not provided, then the default device locale is used. No UI configuration information that is used to specify the UI layout and theme for a UICustomizationType. For example, font style and font size for DEFAULT or DARK mode. For more information, see Class UiCustomization, Enum UICustomization Type. initialize Return Value None. initialize Exceptions Table 4.3: initialize Exceptions Exception Description InvalidInputException This exception is thrown in any of the following scenarios:
  • configParameters is null.
  • The value of configParameters, locale, or uiCustomization is invalid. For more information, see Class InvalidInputException. SDKAlreadyInitializedException This exception is thrown if the 3DS SDK instance has already been initialized. For more information, see Class SDKAlreadyInitializedException. SDKRuntimeException This exception is thrown if an internal error is encountered by the 3DS SDK. For more information, see Class SDKRuntimeException. Code Elements of the EMV 3-D Secure Default SDK / 137 4.1.2 createTransaction The createTransaction method creates an instance of Transaction through which the 3DS Requestor App gets the data that is required to perform the transaction. The 3DS Requestor App calls the createTransaction method for each transaction that is to be processed. When the createTransaction method is called:
  • The 3DS SDK uses the information adhering to the protocol version passed in the optional messageVersion parameter if it supports the protocol version. If it does not support the protocol version, it generates an Invali

Shown in part. Read the original for the full text.