PCI Watch

Tracking changes across the Payment Card Industry
ℹ️
Tracked metadata: Sourced from EMVCo's public document index. PCI Watch records each document's details and its extracted text so changes can be tracked over time; the document PDF itself is hosted by EMVCo.
View on EMVCo.com →

EMV® 3-D Secure Wrapped-SDK Best Practices

v1.0 Best Practices
3-D Secure
Extracted document text

EMVCo's index flattens the document's layout, so this text is best used for searching and comparing versions rather than reading end-to-end.

EMV® 3-D Secure Wrapped-SDK Best Practices Version 1.0 July 2024 EMV® 3-D Secure Wrapped-SDK Best Practices Legal Notice Page 2 of 31 Legal Notice This document is subject to change by EMVCo at any time. This document does not create any binding obligations upon EMVCo or any third party regarding the subject matter of this document, which obligations will exist, if at all, only to the extent set forth in separate written agreements executed by EMVCo or such third parties. In the absence of such a written agreement, no product provider, test laboratory or any other third party should rely on this document, and EMVCo shall not be liable for any such reliance. No product provider, test laboratory or other third party may refer to a product, service or facility as EMVCo approved, in form or in substance, nor otherwise state or imply that EMVCo (or any agent of EMVCo) has in whole or part approved a product provider, test laboratory or other third party or its products, services, or facilities, except to the extent and subject to the terms, conditions and restrictions expressly set forth in a written agreement with EMVCo, or in an approval letter, compliance certificate or similar document issued by EMVCo. All other references to EMVCo approval are strictly prohibited by EMVCo. Under no circumstances should EMVCo approvals, when granted, be construed to imply any endorsement or warranty regarding the security, functionality, quality, or performance of any particular product or service, and no party shall state or imply anything to the contrary. EMVCo specifically disclaims any and all representations and warranties with respect to products that have received evaluations or approvals, and to the evaluation process generally, including, without limitation, any implied warranties of merchantability, fitness for purpose or noninfringement. All warranties, rights and remedies relating to products and services that have undergone evaluation by EMVCo are provided solely by the parties selling or otherwise providing such products or services, and not by EMVCo, and EMVCo will have no liability whatsoever in connection with such products and services. This document is provided "AS IS" without warranties of any kind, and EMVCo neither assumes nor accepts any liability for any errors or omissions contained in this document. EMVCO DISCLAIMS ALL REPRESENTATIONS AND WARRANTIES, EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NON-INFRINGEMENT, AS TO THIS DOCUMENT. EMVCo makes no representations or warranties with respect to intellectual property rights of any third parties in or in relation to this document. EMVCo undertakes no responsibility to determine whether any implementation of this document 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 this document should consult an intellectual property attorney before any such implementation. Without limiting the foregoing, this document 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 this document 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 this document. © 2024 EMVCo, LLC. All rights reserved. Reproduction, distribution and other use of this document is permitted only pursuant to the applicable agreement between the user and EMVCo found at www.emvco.com. EMV® is a registered trademark or trademark of EMVCo, LLC in the United States and other countries. EMV® 3-D Secure Wrapped-SDK Best Practices Contents Page 3 of 31 Contents Legal Notice ............................................................................................................................... 2 Contents .................................................................................................................................... 3 1 Introduction ......................................................................................................................... 6 1.1 Supporting Documentation ............................................................................................... 6 2 Background......................................................................................................................... 7 2.1 Understanding the 3DS SDK and Its Functionality ............................................................ 7 2.2 Mobile Application Development Approaches ................................................................... 7 3 Wrapped-SDK Approach and Project.................................................................................. 9 4 Sample Wrapped-SDK Implementations ............................................................................10 4.1 Flutter ..............................................................................................................................10 4.1.1 Overview ...................................................................................................................10 4.1.2 Implementation Notes ...............................................................................................11 4.1.3 Summary of Findings ................................................................................................13 4.1.4 Flutter Wrapped-SDK Code Sample..........................................................................14 ThreeDS2Service...............................................................................................................14 1. initialize3dsService ....................................................................................................14 2. createTransaction ......................................................................................................15 3. cleanup......................................................................................................................15 4. getSDKVersion ..........................................................................................................15 5. getWarnings ..............................................................................................................15 Transaction ........................................................................................................................15 1. getAuthenticationRequestParameters .......................................................................15 2. doChallenge ..............................................................................................................15 3. showProgressView / hideProgressView.....................................................................16 4. close ..........................................................................................................................16 ChallengeStatusReceiver ...................................................................................................16 4.2 React Native....................................................................................................................18 4.2.1 Overview ...................................................................................................................18 React Native Packages (Modules) .....................................................................................18 4.2.2 Implementation Notes ...............................................................................................19 Installation and Setup ........................................................................................................19 Lines of Code.....................................................................................................................19 © 2024 EMVCo, LLC. All rights reserved. Reproduction, distribution and other use of this document is permitted only pursuant to the applicable agreement between the user and EMVCo found at www.emvco.com. EMV® is a registered trademark or trademark of EMVCo, LLC in the United States and other countries. EMV® 3-D Secure Wrapped-SDK Best Practices Contents Page 4 of 31 4.2.3 Summary of Findings ................................................................................................19 4.2.4 React Native Code Sample .......................................................................................20 ThreeDS2Service...............................................................................................................20 1. initialize3dsService ....................................................................................................20 2. createTransaction ......................................................................................................20 3. cleanup......................................................................................................................21 4. getSDKVersion ..........................................................................................................21 5. getWarnings ..............................................................................................................21 Transaction ........................................................................................................................21 1. getAuthenticationRequestParameters .......................................................................21 2. doChallenge ..............................................................................................................21 3. showProgressView / hideProgressView.....................................................................21 4. close ..........................................................................................................................21 ChallengeStatusReceiver ...................................................................................................22 4.3 Cordova...........................................................................................................................23 4.3.1 Overview ...................................................................................................................23 Cordova Plugins.................................................................................................................23 4.3.2 Implementation Notes ...............................................................................................24 System Requirements........................................................................................................24 Installation and Setup ........................................................................................................24 Using Types.......................................................................................................................25 Lines of Code.....................................................................................................................25 4.3.3 Summary of Findings ................................................................................................25 4.3.4 Cordova Code Sample ..............................................................................................25 ThreeDS2Service...............................................................................................................25 1. initialize3dsService ....................................................................................................25 2. createTransaction ......................................................................................................26 3. cleanup......................................................................................................................27 4. getSDKVersion ..........................................................................................................27 5. getWarnings ..............................................................................................................27 Transaction ........................................................................................................................27 1. getAuthenticationRequestParameters .......................................................................27 2. doChallenge ..............................................................................................................28 3. showProgressView / hideProgessView ......................................................................28 © 2024 EMVCo, LLC. All rights reserved. Reproduction, distribution and other use of this document is permitted only pursuant to the applicable agreement between the user and EMVCo found at www.emvco.com. EMV® is a registered trademark or trademark of EMVCo, LLC in the United States and other countries. EMV® 3-D Secure Wrapped-SDK Best Practices Contents Page 5 of 31 4. close ..........................................................................................................................29 ChallengeStatusReceiver ...................................................................................................29 5 Feedback and Key Findings...............................................................................................31 © 2024 EMVCo, LLC. All rights reserved. Reproduction, distribution and other use of this document is permitted only pursuant to the applicable agreement between the user and EMVCo found at www.emvco.com. EMV® is a registered trademark or trademark of EMVCo, LLC in the United States and other countries. EMV® 3-D Secure Wrapped-SDK Best Practices Introduction Page 6 of 31 1 Introduction This document outlines the recommendations for integrating an existing EMV 3-D Secure (3DS) Default-SDK into a 3DS Requestor (Merchant) Application (App) using hybrid or cross-platform development environments, such as Flutter, React Native, etc. The main objective is to ensure that the functionalities and security measures defined in the EMV 3-D Secure SDK Specification and EMV 3-D Secure Protocol and Core Functions Specification version 2.3.1.1 (and subsequent versions) are preserved throughout the integration process. The guidelines and examples presented in this document are supported by the feedback obtained from prototyping a 3DS Requestor App containing an approved 3DS Default-SDK using hybrid or cross-platform development environments and security analysis conducted by code security experts. The frameworks evaluated for this project were Flutter, React Native and Cordova. The document summarises: • any issues that could prevent the use of a hybrid app development framework for a Wrapped-SDK; • the recommendations to be followed by vendors when developing a Wrapped-SDK using a hybrid app development framework; and • the main difficulties related to the use of a hybrid app development framework – general or specific to any of the evaluated frameworks. 1.1 Supporting Documentation The following documents, available on the EMVCo website, are specific to the EMV 3-D Secure protocol and should be used in conjunction with this document. • EMV® 3-D Secure—Protocol and Core Functions Specification version 2.3.1.1 • EMV® 3-D Secure—SDK Specification v2.3.1.1 • EMV® 3-D Secure Specifications Frequently Asked Questions (FAQ) • EMV® 3-D Secure Approval—Administrative Process version 1.3 © 2024 EMVCo, LLC. All rights reserved. Reproduction, distribution and other use of this document is permitted only pursuant to the applicable agreement between the user and EMVCo found at www.emvco.com. EMV® is a registered trademark or trademark of EMVCo, LLC in the United States and other countries. EMV® 3-D Secure Wrapped-SDK Best Practices Background 2 Background Page 7 of 31 2.1 Understanding the 3DS SDK and Its Functionality The 3DS SDK is instrumental in enabling 3DS authentication flows in Merchant applications. It operates in the context of a 3DS Requestor App, where it undertakes a series of essential steps to ensure the security and integrity of transactions: • Initiation of the authentication flow – the 3DS Requestor App initiates the authentication process with the 3DS SDK, and the 3DS SDK collects and encrypts the device information before passing it back to the app. • Communication with the 3DS Server – the 3DS Requestor App communicates device information and transaction data to the 3DS Server, which then interfaces with the Directory Server (DS) and Access Control Server (ACS) to determine the authentication requirements. • Execution of the authentication flow – if a challenge is deemed necessary, the 3DS Requestor App calls the 3DS SDK to step in to proceed with the Challenge Flow, which involves communication with the ACS via CReq and CRes messages, displaying challenge UI to the Cardholder, collecting responses, and concluding the challenge. • Securing communication and user interaction – throughout these processes, the 3DS SDK maintains strict security measures, ensuring encrypted communication with the ACS, and providing a secure environment for Cardholder interactions. 2.2 Mobile Application Development Approaches As stated in the EMV® 3-D Secure SDK Specification, the 3DS Default-SDK is the mobile device-side component of the 3DS ecosystem. There are multiple approaches to developing this component, depending on the application development framework used: • native app development, wherein the native technologies of the target platform are used. This allows for the most optimal implementation in terms of performance, but might result in redundant effort if multiple platforms are being supported. • hybrid app development, wherein web and native technologies are combined in the application. This allows for quicker application development if both web and mobile platforms are being targeted, but performance tends to be much slower, as everything is rendered in an embedded browser. • cross-platform app development, wherein a common language/code is used to develop the application targeting multiple platforms. This allows for quicker application development and usually offers better performance than hybrid apps. © 2024 EMVCo, LLC. All rights reserved. Reproduction, distribution and other use of this document is permitted only pursuant to the applicable agreement between the user and EMVCo found at www.emvco.com. EMV® is a registered trademark or trademark of EMVCo, LLC in the United States and other countries. EMV® 3-D Secure Wrapped-SDK Best Practices Background Page 8 of 31 The optimal approach will depend on an application’s business use cases, but more developers have turned to using hybrid and cross-platform app development due to the time and effort saved. The 3DS Default-SDK is normally developed using the native technologies of the platform. For both the hybrid and cross-platform frameworks, the 3DS SDK component may be implemented directly in the selected programming language. However, there will eventually be some calls to native application programming interfaces (APIs) for some functionalities, especially when collecting the device information-related parameters. © 2024 EMVCo, LLC. All rights reserved. Reproduction, distribution and other use of this document is permitted only pursuant to the applicable agreement between the user and EMVCo found at www.emvco.com. EMV® is a registered trademark or trademark of EMVCo, LLC in the United States and other countries. EMV® 3-D Secure Wrapped-SDK Best Practices Wrapped-SDK Approach and Project Page 9 of 31 3 Wrapped-SDK Approach and Project The Wrapped-SDK approach reuses existing EMVCo-approved 3DS Default-SDK products in hybrid or cross-platform app development. This aims to streamline the 3DS SDK integration into these types of applications and allow the reuse of such approved products so that no additional EMVCo approval will be required for the 3DS Default-SDK. If the 3DS Default-SDK code is modified for use in the context of a Wrapped-SDK, the vendor will perform an analysis to determine if it is a minor or major change, and potentially seek a new approval for the 3DS Default-SDK. The project objectives were as follows: 1. Validate Default-SDK integration in hybrid or cross-platform app development frameworks The project aimed to validate the feasibility of developing an app that integrates DefaultSDKs using three hybrid app development frameworks (Flutter, React Native, and Cordova). 2. Ensure functional integrity and security Key to the project’s success was ensuring that the functionalities of the 3DS SDK remained intact, with no impact on the frictionless and challenge flows, the user experience, the 3DS SDK performances and its security. Additionally, the project aimed to achieve this without modifications to the existing 3DS SDK code. 3. Support the 3DS community to integrate the 3DS SDK in the 3DS Requestor App. To achieve these objectives, the project leveraged: • a vendor’s expertise in 3DS SDK and mobile app development; • two existing approved 3DS Default-SDKs (Android and iOS) for integration with the 3DS Requestor App; and • three hybrid and cross-platform app development frameworks (Flutter, React Native, and Cordova) selected for their relevance in the app development landscape. A total of six app prototypes were developed (Android + iOS, three hybrid/cross-platform app development frameworks) to demonstrate the support of the 3DS frictionless and challenge flow (SMS-OTP and out-of-band app switching) for Native and HTML UI. © 2024 EMVCo, LLC. All rights reserved. Reproduction, distribution and other use of this document is permitted only pursuant to the applicable agreement between the user and EMVCo found at www.emvco.com. EMV® is a registered trademark or trademark of EMVCo, LLC in the United States and other countries. EMV® 3-D Secure Wrapped-SDK Best Practices Sample Wrapped-SDK Implementations Page 10 of 31 4 Sample Wrapped-SDK Implementations Three mobile app development frameworks were used to create the Wrapped-SDK prototypes: Flutter, React Native and Cordova. Each implementation focused on creating a “wrapper” layer to translate the existing 3DS Default-SDK interfaces into the target framework language. This prototype wrapper layer focused on the following interfaces from the EMV 3-D Secure—SDK Specification v2.3.1.1: • ThreeDS2Service interface • Transaction interface • ChallengeStatusReceiver interface Other interfaces or classes defined in the EMV 3-D Secure—SDK Specification, such as the ConfigParameters or UiCustomization, were also partially implemented to perform the basic flows for the app transactions. For a full implementation of a Wrapped-SDK, it is recommended to implement the wrapper for the remaining interfaces or classes defined in that specification. 4.1 Flutter 4.1.1 Overview A Flutter plugin is a type of package that relies on platform-specific functionality. In the case of the 3DS SDK, the plugin essentially provides a communication mechanism between Flutter and iOS/Android. The structure of the plugin should be as follows: From an application perspective, it resembles any other package. A minimal package consists of the following: pubspec.yaml, which is a metadata file that declares the package name, version, author, and other details. © 2024 EMVCo, LLC. All rights reserved. Reproduction, distribution and other use of this document is permitted only pursuant to the applicable agreement between the user and EMVCo found at www.emvco.com. EMV® is a registered trademark or trademark of EMVCo, LLC in the United States and other countries. EMV® 3-D Secure Wrapped-SDK Best Practices Sample Wrapped-SDK Implementations Page 11 of 31 The lib directory contains the public code in the package, minimally a single .dart file. Federated Plugins Federated plugins are a way of splitting support for different platforms into separate packages. A federated plugin can use one package for iOS, another for Android, another for web, and yet another for a car (as an example of an IoT device). A federated plugin requires the following packages: 1. app-facing package – the package that plugin users depend on in order to use the plugin. This package specifies the API used by the Flutter app. 2. platform package(s) – one or more packages that contain platform-specific implementation code. The app-facing package calls into these packages – they are not included in an app unless they contain platform-specific functionality accessible to the end user. 3. platform interface package – the package that glues the app-facing packing to the platform package(s). This package declares an interface that any platform package must implement to support the app-facing package. Having a single package that defines this interface ensures that all platform packages implement the functionality in the same manner. 4.1.2 Implementation Notes System Requirements • Operating System: macOS • Tools: Flutter uses Git for installation and upgrade. It is recommended to install Xcode, which includes Git, but Git can also be installed separately. • Integrated development environment: Flutter apps can be built and run with Android Studio or Visual Studio Code. This document is intended to be used for Android Studio. • SDK: Download and install the Flutter SDK. Note: Flutter relies on a complete installation of Android Studio to supply its Android platform dependencies. Implementation Details • The communication between Flutter and the native part is asynchronous. • There is no shared memory between Dart and the native side – only message passing. • The serialization and deserialization of the values passed between Dart and the native side occurs automatically. © 2024 EMVCo, LLC. All rights reserved. Reproduction, distribution and other use of this document is permitted only pursuant to the applicable agreement between the user and EMVCo found at www.emvco.com. EMV® is a registered trademark or trademark of EMVCo, LLC in the United States and other countries. EMV® 3-D Secure Wrapped-SDK Best Practices Sample Wrapped-SDK Implementations Some automatic data mapping (serialization-deserialization): Page 12 of 31 • Some tools can be used to generate type-safe wrapper code between Flutter and the native platform. In this project, Pigeon was used for this purpose. • All data sent back and forth should be in a method channel. • The native sides should have classes with the platform channel names to enable the Flutter engine to search for those classes and methods. • All calls through the platform channels are asynchronous. On the native side, new threads can be spawned if needed. Multiple platform channels are possible, as long as they have different names. © 2024 EMVCo, LLC. All rights reserved. Reproduction, distribution and other use of this document is permitted only pursuant to the applicable agreement between the user and EMVCo found at www.emvco.com. EMV® is a registered trademark or trademark of EMVCo, LLC in the United States and other countries. EMV® 3-D Secure Wrapped-SDK Best Practices Sample Wrapped-SDK Implementations Page 13 of 31 • The system spawns Flutter’s main thread (root isolate). It is not the same as the platform’s main thread. • The minimum target platform versions supported are listed here. • The Default-SDKs were used as-is by the wrappers, without requiring additional modification to ensure compatibility with the Flutter framework. Lines of Code The Flutter Wrapper-SDK code size overhead is only 9% relative to the native code of the Default-SDK. 4.1.3 Summary of Findings No major difficulties were encountered during the creation of the Flutter wrapper for the existing EMVCo-approved Default-SDKs (Android, iOS). There was no need to change the 3DS SDK binary. Additionally, all tested 3DS flows worked as previously (i.e., SMS-OTP native and App-based HTML challenges, OOB app switching). © 2024 EMVCo, LLC. All rights reserved. Reproduction, distribution and other use of this document is permitted only pursuant to the applicable agreement between the user and EMVCo found at www.emvco.com. EMV® is a registered trademark or trademark of EMVCo, LLC in the United States and other countries. EMV® 3-D Secure Wrapped-SDK Best Practices Sample Wrapped-SDK Implementations 4.1.4 Flutter Wrapped-SDK Code Sample ThreeDS2Service 1. initialize3dsService Page 14 of 31 final uiCustomization = SdkUiCustomization( toolbarCustomization: SdkToolbarCustomization( backgroundColor: '#951728', buttonText: 'Button', headerText: 'Header', ), labelCustomization: SdkLabelCustomization( headingTextColor: '#951728', headingTextFontName: 'Courier', headingTextFontSize: 15, ), textBoxCustomization: SdkTextBoxCustomization( borderColor: '#951728', borderWidth: 1, cornerRadius: 10, ), buttonCustomization: [ SdkButtonCustomization( buttonType: SdkButtonType.submitButton, backgroundColor: '#951728', cornerRadius: 10), ]); try { await ThreeDS2SdkPlugin.initialize3dsServiceWithCustomizationMap("en-US", { SdkUICustomizationType.defaultType: uiCustomization }); } catch (e) { //handle Sdk init error here } © 2024 EMVCo, LLC. All rights reserved. Reproduction, distribution and other use of this document is permitted only pursuant to the applicable agreement between the user and EMVCo found at www.emvco.com. EMV® is a registered trademark or trademark of EMVCo, LLC in the United States and other countries. EMV® 3-D Secure Wrapped-SDK Best Practices Sample Wrapped-SDK Implementations 2. createTransaction const String paymentSystem = "_CARDNETWORK_RID_"; const String messageVersion = "2.3.1"; Page 15 of 31 await ThreeDS2SdkPlugin.createTransaction(paymentSystem, messageVersion); 3. cleanup await ThreeDS2SdkPlugin.cleanup(); 4. getSDKVersion var version = await ThreeDS2SdkPlugin.getSDKVersion(); 5. getWarnings var warnings = await ThreeDS2SdkPlugin.getServiceWarnings(); Transaction 1. getAuthenticationRequestParameters var parameters = await ThreeDS2SdkPlugin.getAuthenticationRequestParameters(); 2. doChallenge String status = authenticationResponse[kTransactionStatus] as String; if (status == 'C') { await ThreeDS2SdkPlugin.doChallenge( timeout: int.parse(default3dsMaxTimeout), acsSignedContent: authenticationResponse[kACSSignedContent] as String, threeDSServerTransactionID: authenticationResponse[kThreeDSServerTransID] as String, acsTransactionID: authenticationResponse[kACSTransactionID] as String, © 2024 EMVCo, LLC. All rights reserved. Reproduction, distribution and other use of this document is permitted only pursuant to the applicable agreement between the user and EMVCo found at www.emvco.com. EMV® is a registered trademark or trademark of EMVCo, LLC in the United States and other countries. EMV® 3-D Secure Wrapped-SDK Best Practices Sample Wrapped-SDK Implementations Page 16 of 31 acsRefNumber: authenticationResponse[kACSReferenceNumber] as String), threeDSRequestorAppURL: defaultThreeDSRequestorAppURL); } 3. showProgressView / hideProgressView await ThreeDS2SdkPlugin.showProgressView(); await ThreeDS2SdkPlugin.closeProgressView(); 4. close await ThreeDS2SdkPlugin.closeTransaction(); ChallengeStatusReceiver TransactionDelegate.setup(this); @override void challengeCancelled() { cleanupTransaction(); emit(TransactionCancelledState("Challenge canceled")); } @override void challengeCompleted(ChallengeCompletion challengeCompletion) { cleanupTransaction(); emit( TransactionSuccessState('COMPLETED CHALLENGE transStatus: ${challengeCompletion.transactionStatus} ' 'lastCRes: ${challengeCompletion.lastCRes}')); } @override void challengeProtocolError(ProtocolError error) { cleanupTransaction(); emit( TransactionFailureState(error.toString())); } © 2024 EMVCo, LLC. All rights reserved. Reproduction, distribution and other use of this document is permitted only pursuant to the applicable agreement between the user and EMVCo found at www.emvco.com. EMV® is a registered trademark or trademark of EMVCo, LLC in the United States and other countries. EMV® 3-D Secure Wrapped-SDK Best Practices Sample Wrapped-SDK Implementations @override void challengeRuntimeError(ChallengeRuntimeError error) { cleanupTransaction(); emit( TransactionFailureState(error.toString())); } @override void challengeTimedout() { cleanupTransaction(); emit( TransactionFailureState("Timeout")); } Page 17 of 31 © 2024 EMVCo, LLC. All rights reserved. Reproduction, distribution and other use of this document is permitted only pursuant to the applicable agreement between the user and EMVCo found at www.emvco.com. EMV® is a registered trademark or trademark of EMVCo, LLC in the United States and other countries. EMV® 3-D Secure Wrapped-SDK Best Practices Sample Wrapped-SDK Implementations 4.2 React Native Page 18 of 31 4.2.1 Overview React Native is an open-source framework for building mobile applications. It works by using a combination of JavaScript and native components to create mobile applications. React Native Packages (Modules) Native modules bridge JavaScript code with platform-specific native code. They enable access to native APIs, functionality, and components that are not available through the React Native core. Native modules provide a way to write platform-specific code (Objective-C, Java, and Kotlin for Android) and expose that code to a JavaScript application. For iOS, among other things, this also enables access to native libraries such as the 3DS SDK. There are two ways to write a native module for a React Native application: 1. Directly within the React Native application’s iOS/Android projects; OR 2. As an npm package that can be installed as a dependency by React Native applications. The initial structure of the RN module is as follows: How modules work: 1. Separate native module: write the native code (Objective-C, Swift, Java, Kotlin) that performs the desired functionality or accesses the native API. 2. Bridge to JavaScript: expose the native code to JavaScript by creating a bridge module that defines methods or events to be used from JavaScript. 3. Use in JavaScript: in the JavaScript code, import and use the native module like any other JavaScript module. © 2024 EMVCo, LLC. All rights reserved. Reproduction, distribution and other use of this document is permitted only pursuant to the applicable agreement between the user and EMVCo found at www.emvco.com. EMV® is a registered trademark or trademark of EMVCo, LLC in the United States and other countries. EMV® 3-D Secure Wrapped-SDK Best Practices Sample Wrapped-SDK Implementations Page 19 of 31 4. Compile and run: when building a React Native app, the JavaScript code communicates with the native module through the bridge, allowing access to the native functionality (3DS SDK). 4.2.2 Implementation Notes System Requirements • Operating system: macOS, Windows • Integrated development environment: It is recommended to use the Visual Studio Code code editor and its handy React Native Tools. • Dependencies: Node, Watchman, the React Native command-line interface (CLI), Xcode, CocoaPods, a JDK, and Android Studio will be needed. brew install node brew install watchman • React Native has a built-in CLI. Rather than install and manage a specific version of the CLI globally, it is recommended to access the current version at runtime using npx, which ships with Node.js. With npx react-native, the current stable version of the CLI will be downloaded and executed at the time the command is run. Installation and Setup In order for a React Native package to be used, it typically needs to be added as a dependency in the React Native project’s package.json file. Once added, the package can be imported in the React Native code and the exposed APIs can be used to access the desired functionality. • npm does not work with unpublished/local dependencies – this is a known issue for npm. yarn can be used instead. • JavaScript is not as type-safe as Flutter (in terms of JSON parsing for internal communication and class/typecasting), but TypeScript can be used instead in some cases. • The method mapping for native-to-wrapped SDK is almost the same as for Flutter. Lines of Code The React Native Wrapper-SDK code size overhead is only 3% relative to the native code of the Default-SDK. 4.2.3 Summary of Findings No major difficulty was encountered during the creation of the React Native wrapper for the existing EMVCo-approved Default-SDKs (Android, iOS). There was also no need to change the 3DS SDK binary. Additionally, all tested 3DS flows worked as previously (i.e., SMS-OTP native and App-based HTML challenges, OOB app switching). © 2024 EMVCo, LLC. All rights reserved. Reproduction, distribution and other use of this document is permitted only pursuant to the applicable agreement between the user and EMVCo found at www.emvco.com. EMV® is a registered trademark or trademark of EMVCo, LLC in the United States and other countries. EMV® 3-D Secure Wrapped-SDK Best Practices Sample Wrapped-SDK Implementations 4.2.4 React Native Code Sample Page 20 of 31 ThreeDS2Service 1. initialize3dsService const uiCustomization: UiCustomization = { toolbarCustomization: { backgroundColor: '#2196f3', buttonText: 'Button', headerText: 'Header', }, textBoxCustomization: { borderColor: '#aaaaaa', borderWidth: 1, cornerRadius: 3, }, labelCustomization: { headingTextColor: '#ffffff', headingTextFontSize: 15, }, buttonCustomization: [ { buttonType: ButtonType.Submit, textColor: '#ffffff', cornerRadius: 10, } ] } const uiMap = new Map() uiMap.set(CustomizationType.Default : uiCustomization) ThreeDS2SdkPlugin.initialize3dsServiceWithCustomizationMap(locale, uiCustomization) 2. createTransaction const paymentSystem = "_CARDNETWORK_RID_"; const messageVersion = "2.3.1"; await ThreeDS2SdkPlugin.createTransaction(paymentSystem, messageVersion); © 2024 EMVCo, LLC. All rights reserved. Reproduction, distribution and other use of this document is permitted only pursuant to the applicable agreement between the user and EMVCo found at www.emvco.com. EMV® is a registered trademark or trademark of EMVCo, LLC in the United States and other countries. EMV® 3-D Secure Wrapped-SDK Best Practices Sample Wrapped-SDK Implementations 3. cleanup await ThreeDS2SdkPlugin.cleanup(); Page 21 of 31 4. getSDKVersion var version = await ThreeDS2SdkPlugin.getSDKVersion(); 5. getWarnings var result = await ThreeDS2SdkPlugin.getServiceWarnings() Transaction 1. getAuthenticationRequestParameters var parameters = await ThreeDS2SdkPlugin.getAuthenticationRequestParameters(); 2. doChallenge let status = authenticationResponse .get(kTransactionStatus); if (status == 'C') { await ThreeDS2SdkPlugin.doChallenge( Number(default3dsMaxTimeout), authenticationResponse.get(kACSSignedContent), authenticationResponse.get(kThreeDSServerTransID), authenticationResponse.get(kACSTransactionID), authenticationResponse.get(kACSReferenceNumber), defaultThreeDSRequestorAppURL); } 3. showProgressView / hideProgressView await ThreeDS2SdkPlugin.showProgressView(); await ThreeDS2SdkPlugin.hideProgressView(); 4. close await ThreeDS2SdkPlugin.closeTransaction(); © 2024 EMVCo, LLC. All rights reserved. Reproduction, distribution and other use of this document is permitted only pursuant to the applicable agreement between the user and EMVCo found at www.emvco.com. EMV® is a registered trademark or trademark of EMVCo, LLC in the United States and other countries. EMV® 3-D Secure Wrapped-SDK Best Practices Sample Wrapped-SDK Implementations ChallengeStatusReceiver Page 22 of 31 async function subscribeToSdkListeners() { ThreeDS2SdkPlugin.addSuccessListener((result: ChallengeCompletion) => { cleanupTransaction(); Alert.alert('Success', JSON.stringify(result), [{text: 'OK'}]); }); ThreeDS2SdkPlugin.addCanceledListener(() => { cleanupTransaction(); }); ThreeDS2SdkPlugin.addTimedoutListener(() => { cleanupTransaction(); Alert.alert('Timeout', 'Transaction timed out.', [{text: 'OK'}]); }); ThreeDS2SdkPlugin.addProtocolErrorListener((error: ProtocolError) => { cleanupTransaction(); Alert.alert('Error', error, [{text: 'OK'}]); }); ThreeDS2SdkPlugin.addRuntimeErrorListener((error: ChallengeRuntimeError) => { cleanupTransaction(); Alert.alert( 'Error', `Challenge runtime error. n Error code: ${error.errorCode} n Error message: ${error.errorMessage}`, [{text: ‘OK’}], ); }); } © 2024 EMVCo, LLC. All rights reserved. Reproduction, distribution and other use of this document is permitted only pursuant to the applicable agreement between the user and EMVCo found at www.emvco.com. EMV® is a registered trademark or trademark of EMVCo, LLC in the United States and other countries. EMV® 3-D Secure Wrapped-SDK Best Practices Sample Wrapped-SDK Implementations 4.3 Cordova Page 23 of 31 4.3.1 Overview Apache Cordova is an open-source mobile development framework. It enables the use of standard web technologies – HTML5, CSS3, and JavaScript – for cross-platform development. Applications execute within wrappers targeted to each platform and rely on standards-compliant API bindings to access each device’s capabilities such as sensors, data, or network status. Cordova Plugins A plugin is a package of injected code that allows the Cordova WebView within which the app renders to communicate with the native platform on which it runs. Plugins provide access to device and platform functionality that is ordinarily unavailable to web-based apps. Plugins comprise a single JavaScript interface along with corresponding native code libraries for each supported platform (Objective-C for iOS, Java for Android). In essence, this hides the various native code implementations behind a common JavaScript interface. Among other things, this also enables access to native libraries such as the 3DS SDK. The initial structure of the Cordova plugin is as follows: How plugins work: 1. Separate native code: write the native code (Objective-C, Java) that performs the desired functionality or accesses the native API. 2. Bridge to JavaScript: expose the native code to JavaScript by creating a bridge module that defines methods or events to be used from JavaScript. 3. Use in JavaScript: in the JavaScript code, import and use the native plugin like any other JavaScript plugin. © 2024 EMVCo, LLC. All rights reserved. Reproduction, distribution and other use of this document is permitted only pursuant to the applicable agreement between the user and EMVCo found at www.emvco.com. EMV® is a registered trademark or trademark of EMVCo, LLC in the United States and other countries. EMV® 3-D Secure Wrapped-SDK Best Practices Sample Wrapped-SDK Implementations Page 24 of 31 4. Compile and run: when building a Cordova app, the JavaScript code communicates with the native code through the bridge, allowing access to the native functionality (SDK). 4.3.2 Implementation Notes System Requirements • Operating system: MacOS, Windows • Integrated development environment: No specific recommendation is provided. While Visual Studio Code was used in this project, the iOS and Android apps can also be started from Xcode or Android Studio, respectively. • Cordova CLI: o Download and install Node.js. Following installation, node and npm should be able to be invoked on the command line. o (Optional) Download and install a Git client. Following installation, Git should be able to be invoked on the command line. The CLI uses it to download assets when they are referenced using a URL to a Git repository. o Install the Cordova module using the npm utility of Node.js. The Cordova module will automatically be downloaded by the npm utility. • Prerequisites: To build and run apps, SDKs need to be installed for each platform. To check if the requirements for building the platform are satisfied, invoke: cordova requirements • Additional tools used: o Webpack and Babel allowed the reuse of parts of the existing Typescript code from the React Native implementation. o cordova-plugin-device: for information on the device hardware and software o cordova-plugin-dialogs: for native UI dialogs (app-side). Installation and Setup To use a Cordova plugin, the plugin typically needs to be added as a dependency in the Cordova project’s package.json file. Once added, the package can be used in the Cordova code and the exposed APIs can be used to access the desired functionality. Adding the Cordova plugin: cordova plugin add Using the Cordova plugin: cordova.plugins.. © 2024 EMVCo, LLC. All rights reserved. Reproduction, distribution and other use of this document is permitted only pursuant to the applicable agreement between the user and EMVCo found at www.emvco.com. EMV® is a registered trademark or trademark of EMVCo, LLC in the United States and other countries. EMV® 3-D Secure Wrapped-SDK Best Practices Sample Wrapped-SDK Implementations Page 25 of 31 Using Types To use the types from the Cordova plugin in a Typescript project, add the following line at the beginning of the .ts file: /// { console.log('Transaction success listener called'); cleanupTransaction(); showAlert(JSON.stringify(result), 'Success'); }); cordova.plugins.ThreeDS2Sdk.addCanceledListener(function () { console.log('Transaction cancelled listener called'); cleanupTransaction(); }); cordova.plugins.ThreeDS2Sdk.addTimedoutListener(function () { console.log('Transaction timeout listener called'); cleanupTransaction(); showAlert('Transaction timed out', 'Timeout'); }); cordova.plugins.ThreeDS2Sdk.addRuntimeErrorListener((error: any) => { console.log('Transaction runtime error listener called'); cleanupTransaction(); showAlert(error, 'Error'); }); cordova.plugins.ThreeDS2Sdk.addProtocolErrorListener((error: any) => { console.log('Transaction protocol error listener called'); cleanupTransaction(); showAlert(error, 'Error'); © 2024 EMVCo, LLC. All rights reserved. Reproduction, distribution and other use of this document is permitted only pursuant to the applicable agreement between the user and EMVCo found at www.emvco.com. EMV® is a registered trademark or trademark of EMVCo, LLC in the United States and other countries. EMV® 3-D Secure Wrapped-SDK Best Practices Sample Wrapped-SDK Implementations }); console.log('Transaction listeners added'); } catch (error) { console.log('Transaction listeners error: ' + error); } } Page 30 of 31 © 2024 EMVCo, LLC. All rights reserved. Reproduction, distribution and other use of this document is permitted only pursuant to the applicable agreement between the user and EMVCo found at www.emvco.com. EMV® is a registered trademark or trademark of EMVCo, LLC in the United States and other countries. EMV® 3-D Secure Wrapped-SDK Best Practices Feedback and Key Findings Page 31 of 31 5 Feedback and Key Findings Based on the project outcome, it was found that the integration of the EMV 3DS SDK with the mobile app code and generation of app prototypes is possible with all three hybrid app development frameworks using the Wrapped-SDK approach. There were no blocking points or major technical issues. No modifications to the 3DS SDK code were necessary. According to the EMV 3-D Secure Approval Administrative Process document, this constitutes a minor change and will not require a new LOA. There was no impact on the different 3DS authentication flows (frictionless and challenge). The challenge UI (HTML and Native) is correctly rendered, with no noticeable impact on performance. The increase in code size for wrapping the SDK is acceptable considering the advantages for vendors using hybrid app development frameworks. Security analysis of the prototype Wrapped-SDK found that no security vulnerabilities were introduced to the 3DS SDK, with the disclaimer that the Wrapped-SDK is developed using industry-accepted security standards. © 2024 EMVCo, LLC. All rights reserved. Reproduction, distribution and other use of this document is permitted only pursuant to the applicable agreement between the user and EMVCo found at www.emvco.com. EMV® is a registered trademark or trademark of EMVCo, LLC in the United States and other countries.