Android 3DS SDK

Contents

• Introduction
  • System requirements and delivery
  • Versioning
  • Supporting documentation
• Integration
  • Importing the SDK
  • Update the SDK
  • Set an environment
  • JDK desugaring
  • Handle application backup rules
  • Additional configuration for App bundles
• Card schemes configuration
• Access the SDK
  • Initialise the SDK
• The API
  • Initialisation warnings
  • SDK version
  • ConfigParameters
  • UiCustomization
  • Exceptions
  • Warnings
  • Transaction creation
  • Cleaning the SDK
  • Transaction operations
  • Authentication request parameters
  • Challenge flow
    • Challenge parameters
    • Challenge flow results
• Dark mode support
• Required permissions
• Security
  • PCI requirements
  • ProGuard rules
  • Recommendations for the integrator
• Gradle
• Dependencies
• Release notes

Introduction

This document serves as a guide for the integrator of Ravelin’s Android 3DS SDK, providing details on how the 3DS SDK should be configured and integrated into an Android application.

System requirements and delivery

Ravelin’s Android 3DS SDK supports a minimum Android version Android 5 (API Level 21).

Developed as a standard Android Library, Ravelin provides a single AAR artifact along with the Maven POM file that lists dependencies.

We also include the following.

• An API token.
• Environment code.
• An integration guide.
• A demo application demonstrating 3DS authentication with and without a challenge. The demonstration app includes show cases of different types of frictionless and challenge flows.

Versioning

The Android 3DS SDK follows semantic versioning - The version can be described as MAJOR.MINOR.PATCH, where:

• MAJOR - incompatible version changes
• MINOR - improvements
• PATCH - bug / security fix

Supporting documentation

The Ravelin 3DS SDK is built and tested according to the following supporting EMV 3DS documentation. Therefore, this guide should be used in conjunction with the following specifications:

• EMV 3-D Secure - Protocol and Core Functions Specification version 2.2.0
• EMV 3-D Secure - Specification Bulletin No. 214 v3
• EMV 3-D Secure - Protocol and Core Functions Specification version 2.1.0
• EMV 3-D Secure - Specification Bulletin No. 204 v7
• EMV 3-D Secure - SDK specification version 2.2.0
• EMV 3-D Secure - SDK specification version 2.1.0
• EMV 3-D Secure - Device Information 1.6
• EMV 3-D Secure - Specification Bulletin No. 285
• PCI 3DS SDK - Security Standard 1.1v

Integration

This section provides technical details on how to integrate the Android 3DS SDK into your application. The integration process requires basic knowledge of the gradle build tool.

Importing the SDK

Before attempting to use Gradle for Ravelin, ensure that you have a valid username and password for the Maven private repository as well as the repository url. This can be obtained from a Ravelin integrations engineer.

IMPORTANT - Do not store the repository credentials within Source Control. The credentials can be stored in a user’s gradle.properties file. The filename should also be added to your project .gitignore file to avoid pushing it into your VCS.

ravelinRepoUsername = username
ravelinRepoPassword = password

Within the Project level build.gradle.kts, make sure the repositories include the appropriate Ravelin maven repository:

allprojects {
    repositories {
        /* other repositories */
        maven {
            credentials {
                username = properties["ravelinRepoUsername"] as? String
                password = properties["ravelinRepoPassword"] as? String
            }
            authentication {
                create<BasicAuthentication>("basic")
            }
            setUrl("https://maven.ravelin.com/repositories/threeds2service/")
        }
    }
}

Please note that in case you are using the settings.gradle.kts file to configure your repositories, you should add the repository to the dependencyResolutionManagement.

Then in the Module level build.gradle.kts add the Ravelin 3DS SDK to the app dependencies:

dependencies {
    /* other dependencies */
    implementation("com.ravelin.threeds2service:threeds2service-sdk:1.4.1")
}

The library will be fetched with its own dependencies as described in the POM file. These dependencies are described in Dependencies.

Update the SDK

Occasionally, new releases of the Ravelin 3DS SDK may be published. Such updates may introduce breaking changes. It is recommended to check the release notes section in this guide for additional information about the changes in each release.

Set an environment

This section refers to ConfigParameters.

JDK desugaring

The following configuration is required in order to support Java API desugaring in Android API level 23 or older:

// Add the following to your build.gradle.kts file
compileOptions {
    // Other configurations ...
    isCoreLibraryDesugaringEnabled = true
}

// Add the following dependency to your build.gradle.kts file:
dependencies {
    // Other dependencies
    coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:2.0.4")
}

Handle application backup rules

The Ravelin 3DS SDK defines backup rules in its Manifest file. In case that backup is enabled and you have backup rules in your own application manifest file, make sure to merge the 3DS SDK backup rules, otherwise they will be override during the Manifest merging process and that may result with an unexpected behaviour.

<application android:dataExtractionRules="@xml/backup_rules_31_and_above"
    android:fullBackupContent="@xml/backup_rules_until_30" tools:targetApi="s" />

Extraction rules for Android API >= 12:

<data-extraction-rules disableIfNoEncryptionCapabilities="false">
    <include domain="sharedpref" path="." />
    <include domain="file" path="." />
    <exclude domain="sharedpref" path="my_secret_shared_prefs.xml" />
    <exclude domain="sharedpref" path="my-3ds-shared-preference.xml" />
    <exclude domain="file" path="datastore/user_pref.pb" />
</data-extraction-rules>

Extraction rules for Android API < 12:

<?xml version="1.0" encoding="utf-8"?>
<data-extraction-rules>
    <cloud-backup disableIfNoEncryptionCapabilities="false">
        <include domain="sharedpref" path="." />
        <include domain="file" path="." />
        <exclude domain="sharedpref" path="my_secret_shared_prefs.xml" />
        <exclude domain="sharedpref" path="my-3ds-shared-preference.xml" />
        <exclude domain="file" path="datastore/user_pref.pb" />
    </cloud-backup>
</data-extraction-rules>

Additional configuration for App bundles

The Ravelin 3DS SDK uses a Java native interface (JNI) to communicate with a native library. In case you publish your app as a bundle (aab file), additional configuration is required to avoid receiving the following error: java.lang.UnsatisfiedLinkError. This error happens when users try to side-load the app with an apk file which is not compatible with their device architecture. The steps to avoid such an error are:

1. In your gradle.properties file add the following configuration:

   android.bundle.enableUncompressedNativeLibs = false

2. In your AndroidManifest.xml file set the following attribute in your application tag:

<application android:extractNativeLibs="true" />
<!--or-->
<!--android:extractNativeLibs //in Manifest.xml if minSdk < 23-->

Card schemes configuration

The Ravelin 3DS SDK provides an authentication service for payment transactions which is supported by different Card schemes. Each card scheme provides a public key for device data encryption, a key chain to verify the authenticity of signed certificates that arrive from the ACS (Access Control Server) and the Card scheme logos. In order to comply with the PCI 3DS SDK 1.1v requirements these values cannot be bundled with the SDK. In order to protect this data, the Ravelin 3DS SDK fetches the data from a remote host over a secured TLS link protected by an API token. The metadata downloaded from the host is stored in an encrypted storage.

The following list consists of card schemes, Ravelin 3DS SDK is certified with:

The integrator needs to set the directory server Id parameter when calling the API for creation of transactions with an argument matching a value from the table above.

Access the SDK

A copy of the SDK object is generated when calling the get() function from the ThreeDS2ServiceInstance class companion object. This helps assuring that only a single copy of the SDK class is generated during the life cycle of the application. The following code snippet is an example of how to access this object:

fun provides3dsSdk(): ThreeDS2Service = ThreeDS2ServiceInstance.get()

Initialise the SDK

The SDK needs to be initialised, exactly one time throughout the lifecycle of the application, before it can be used. The SDK initialisation function initialize is a suspended function and therefore, may be called from a coroutine or from another suspend function. Note: If you haven’t worked with coroutines before, please refer to the official documentation in [Coroutines]. In the following example, the SDK is being initialised from a view model using the view model scope.

protected var coroutineExceptionHandler = CoroutineExceptionHandler { _, exception ->
    Log.e(
        TAG,
        "coroutine terminated with an error: ${exception.message}"
    )
    // Handle the error...
}
fun initSdk() =
    viewModelScope.launch(coroutineContext + coroutineExceptionHandler) {
        val warnings = threeDS2Service.initialize(
            application,
            configParameters,
            locale,
            darkUiCustomization,
            lightUiCustomization,
            this
        )
    }

In this example, we have used a life cycle aware coroutine scope (the viewModelScope). It may be that within your app, you define an unmanaged CoroutineScope object. In that case you need to define a SupervisorJob of type CompletableJob to gain a better control over exceptions and cancellation of child coroutines. The coroutineExceptionHandler is of importance for catching exceptions from child coroutines, including coroutines which are created inside the 3DS SDK.

Parameters

(*) Please provide a String the following format:

"${language}-${country}"

The API

This section describes the Android 3DS API.

Initialisation warnings

Calling the function initialize on a threeDS2Service object returns a set of initialisation warnings (see Initialise the SDK and Warnings). It is possible to obtain these warnings also by calling the getWarnings method on the same object. Calling this method without initialising the SDK first, should result with the SDK throwing an SDKNotInitializedException exception.

Method signature

@Throws(SDKNotInitializedException::class)
fun getWarnings(): List<Warning?>

SDK version

Call this method to obtain the version of the SDK. When called before initialising the SDK, it throws an SDKNotInitializedException exception.

Method signature

@Throws(
    SDKNotInitializedException::class,
    SDKRuntimeException::class
)
override fun getSDKVersion(): String

ConfigParameters

An interface which defines a set of methods for initialising the SDK. To generate an instance of ConfigParameters, one should use the ConfigParametersBuilder. The ConfigParametersBuilder consists of the following function members:

1. setEnvironment

The environment is a String type that is given to the integrator during the integration stage. The integrator needs to call the function with this argument. Please make sure you own such a value before working with the API. This value helps setting the correct environment for the SDK.

Method signature

fun setEnvironment(environment: String)

Parameters

2. setApiToken

This is the token extracted from your CID page at the Ravelin dashboard. You should be setting the publishable key.

Method signature

fun setApiToken(apiToken: String)

Parameters

3. setAppVersion

The version of the installed application. This field is essential for us to be able to monitor the app.

Method signature

fun setAppVersion(appVersion: String)

Parameters

the following is an example of how to generate the ConfigurationParameters object:

ConfigParametersBuilder.Builder()
.setEnvironment("Environment value provided during the integration stage")
.setApiToken("ApiToken")
.setAppVersion("1.0.0")
.build()

UiCustomization

According to the EMVCo 3DS SDK specification, the integrator shall be given the option to customise the challenge UI in the native scenario (The HTML UI is set by the ACS and cannot be customised by the SDK). The following table, lists the customisable parameters of each component in the UI:

(*) There are several types of configurable buttons: SUBMIT, CONTINUE, NEXT, CANCEL and RESEND

UI customisation is optional and the user may choose to use it or not. In case that the user decides to ignore UI customisation, the SDK will use its default themes and styles. The integrator may customise the UI of both the light and dark themes or neither of them. The following code snippet shows how to customise the light mode theme (the dark mode customisation should be configured in the same manner but called with dark mode arguments):

fun getSdkLightUiCustomization() = UiCustomization().apply {
    val defaultButtonCustomization = defaultLightButtonCustomization()
    setToolbarCustomization(lightToolbarCustomization())
    setButtonCustomization(
        defaultButtonCustomization,
        UiCustomization.ButtonType.NEXT
    )
    setButtonCustomization(
        lightCancelButtonCustomization(),
        UiCustomization.ButtonType.CANCEL
    )
    setButtonCustomization(
        defaultButtonCustomization,
        UiCustomization.ButtonType.CONTINUE
    )
    setButtonCustomization(
        defaultButtonCustomization,
        UiCustomization.ButtonType.SUBMIT
    )
    setButtonCustomization(
        lightResendButtonCustomization(),
        UiCustomization.ButtonType.RESEND
    )
    setLabelCustomization(lightLabelCustomization())
    setTextBoxCustomization(lightTextBoxCustomization())
}

private fun defaultLightButtonCustomization() = ButtonCustomization().apply {
    setBackgroundColor("#FF80CBC4")
    setCornerRadius(36)
    setTextColor("#FF000000")
    setTextFontName("sans-serif.ttf")
    setTextFontSize(16)
}

private fun lightToolbarCustomization() = ToolbarCustomization().apply {
    setBackgroundColor("#FFF44336")
    setTextColor("#FF76FF03")
    setTextFontName("Shizuru-Regular.ttf")
    setTextFontSize(14)
    setButtonText("Cancel")
    setHeaderText("Secure Checkout")
}

private fun lightCancelButtonCustomization() = ButtonCustomization().apply {
    setTextColor("#FF29F7F4")
    setTextFontName("sans-serif.ttf")
    setTextFontSize(16)
    setBackgroundColor("#00000000")
}

private fun lightResendButtonCustomization() = ButtonCustomization().apply {
    setCornerRadius(36)
    setBackgroundColor("#FFF6DDDC")
    setTextColor("#FFA0B053")
    setTextFontName("sans-serif.ttf")
    setTextFontSize(16)
}

private fun lightLabelCustomization() = LabelCustomization().apply {
    setHeadingTextColor("#FF000000")
    setHeadingTextFontName("sans-serif.ttf")
    setHeadingTextFontSize(22)
    setTextColor("#FF000000")
    setTextFontName("sans-serif.ttf")
    setTextFontSize(15)
}

private fun lightTextBoxCustomization() = TextBoxCustomization().apply {
    setBorderColor("#FF842361")
    setCornerRadius(36)
    setBorderWidth(8)
    setTextColor("#FF333333")
    setTextFontName("sans-serif.ttf")
    setTextFontSize(16)
}

The values set in the above code snippet were only used as an illustration. Where it applies, values are given in pixels. The RESEND button is a special case, as the setBackgroundColor changes the border color only.

Exceptions

According to the EMVCo SDK Specification, the SDK throws four types of exceptions when errors occur:

While in the challenge flow, instead of throwing exceptions, the SDK reports errors via ChallengeStatusReceiver.runtimeError(RuntimeErrorEvent). This RuntimeErrorEvent has both the error message and error code.

Warnings

During initialisation (see Initialise the SDK), the SDK performs a number of required security checks. These checks may return different types of warnings back to your Application. It’s up to the Requestor Application how to handle such warnings - The SDK will continue to operate normally, should the application ignores them. Below is a list of the possible warnings the SDK may emit:

The SDK takes additional security measures to protect itself and to protect the app, acc. to PCI 3DS SDK - Security Standard 1.1v.

Transaction creation

In order to make authentication requests, we require a Transaction object. To create a new Transaction object you need to call the createTransaction(...) function on the threeDS2Service object. The createTransaction(...) may fail due to the following reasons: – SDKNotInitializedException when called on a non initialized SDK. – SDKRuntimeException when unable to find or open the directory server keys. – InvalidInputException when it fails to identify the message version or the directory server ID given to it as arguments.

The following code snippet demonstrate a possible way to call the function and catch its exceptions :

fun generateAuthenticationRequest(
    directoryServerId: String,
    messageVersion: String
) =
    try {
        transaction = threeDS2Service.createTransaction(
            directoryServerId,
            messageVersion
        )
        val authenticationParameters =
            transaction?.getAuthenticationRequestParameters()
    } catch (ex: InvalidInputException) {
        //handle exception
    } catch (ex: SDKNotInitializedException) {
        //handle exception
    } catch (ex: SDKRuntimeException) {
        //handle exception
    }

Parameters

Cleaning the SDK

The requestor application should call this function to free resources designated to the Ravelin 3DS SDK. Like the initialize function, which prepares the 3DS SDK, it should be called only once through out the life cycle of the application. Calling this method, without initialising the SDK first, will cause an SDKNotInitializedException exception to be thrown. Call this function before terminating the application or when you know, you won’t require the SDK anymore while the application is still alive.

Function signature

@Throws(SDKNotInitializedException::class)
fun cleanup(applicationContext: Context)

Parameters

Transaction operations

1. The method getAuthenticationRequestParameters

In order to make an authentication request, the Ravelin 3DS SDK should prepare a set of parameters. This process includes the following operations: – Encrypting the device data, with the directory server public key. – Generating an ephemeral public key for a possible challenge. – Generating an SDK transaction ID. – Sharing the SDK application ID, which is generated during the first initialisation of the SDK for every app installation. – Sharing the SDK reference number. – Sharing the message version used by the SDK.

Method signature

@Throws(SDKRuntimeException::class)
fun getAuthenticationRequestParameters(): AuthenticationRequestParameters?

2. The function doChallenge

When the ACS(Access Control Server) requires a challenge to take place, the requestor application starts the challenge by calling the doChallenge function with proper challenge parameters. The function receives the current Activity as a reference. It is required to start the challenge Activity. The challengeParameters parameter is an instance of the ChallengeParameters class and it implements an interface with the same name. Please see Challenge parameters . The challengeStatusReceiver parameter is a callback which defines the required behavior of the SDK upon completion. Please see Challenge flow results. Once started, the SDK is on charge and communicates directly with the ACS. It also generates its own Activity to display the challenge UI. The user shall also set a time limitation in the timeOut parameter. This parameter defines how long a challenge may persist. The challenge will be automatically completed when this time limitation is reached. The minimal value for this parameter should not be lower than 5 minutes. Setting a value lower than 5 will not result with an error but the SDK will set the timeout to 5 minutes by default.

Function signature

@Throws(InvalidInputException::class, SDKRuntimeException::class)
fun doChallenge(
    currentActivity: Activity?,
    challengeParameters: ChallengeParameters?,
    challengeStatusReceiver: ChallengeStatusReceiver?,
    timeOut: Int
)

Parameters

3. The function getProgressView

When called, this method generates a processing screen which displays the Android default progress bar and the DS logo. The processing screen is an indication to the user that some activity is taking place in the background either by the application or by the 3DS SDK. The processing screen should be displayed only in 2 cases: – The requestor application is making an authentication request. In that case the processing screen will be displayed during the AReq/ARes messaging. – The first CReq/CRes cycle.

Please note that ProgressDialog was deprecated in Android API 26 but it is still a requirement of the EMVCo specification and part of the Transaction contract.

Function signature

@Throws(InvalidInputException::class, SDKRuntimeException::class)
fun getProgressView(currentActivity: Activity?): ProgressDialog?

Parameters

4. The method close

Call this function when the transaction is completed. This function cleans resources related to the transaction. Calling any of the other functions on a closed transaction will result with an SDKRuntimeException thrown by the 3DS SDK. Make sure to call this function whether the transaction was successful or not.

Method signature

fun close()

Authentication request parameters

As mentioned above (under Transaction operations), the method getAuthenticationRequestParameters called on an instance of a transaction, returns an object which implements the AuthenticationRequestParameters interface. The properties of this object are used to generate the AReq message.

1. The method getDeviceData

Returns the encrypted device data which is collected during the initialisation of the SDK. This data is important for the ACS to conduct its TRA.

Method signature

fun getDeviceData(): String?

2. The method getSDKTransactionID

A unique identifier generated by the SDK during a transaction creation. This ID is used to identify the transaction.

Method signature

fun getSDKTransactionID(): String?

3. The method getSDKAppID

A unique identifier generated by the SDK during installation, i.e. during the first initialisation of the SDK. It is used to identify the requestor application on the user device.

Method signature

fun getSDKAppID(): String?

4. The method getSDKReferenceNumber

A unique identifier of the SDK generated by EMVCo. during the certification of the SDK. It is used to identify the SDK during authentication requests.

Method signature

fun getSDKReferenceNumber(): String?

5. The method getSDKEphemeralPublicKey

The SDK Ephemeral Public Key. An ephemeral key pair is used to establish a secure session between the 3DS SDK and the ACS during the challenge flow.

Method signature

fun getSDKEphemeralPublicKey(): String?

6. The method getMessageVersion

Returns the protocol version that it used during the transaction.

Method signature

fun getMessageVersion(): String?

Challenge flow

The ACS performs a TRA(Transaction Risk Analysis) to decide whether to authenticate the user or not. When the ACS have doubts about the TRA verdict it may ask for a challenge to take place. The requestor application may initiate a challenge by calling the doChallenge function with appropriate parameters (see Transaction operations for more details).

Challenge parameters

One of the parameters of the doChallenge function is an instance of the ChallengeParameters class. This class implements the ChallengeParameters contract. The class can be found in the 3DS SDK. Its constructor function looks as follows:

/**
 * The ChallengeParameters class shall hold the parameters that are required to conduct the challenge process.
 * Note: It is mandatory to set values for these parameters.
 *
 * @param threeDSServerTransactionID Transaction identifier assigned by the 3DS Server to uniquely identify a single transaction.
 * @param acsTransactionID Transaction ID assigned by the ACS to uniquely identify a single transaction.
 * @param acsRefNumber EMVCo assigns the ACS this identifier after running the EMV 3-D Secure Testing and Approvals process on the ACS.
 * @param acsSignedContent ACS signed content. This data includes the ACS URL, ACS ephemeral public key, and SDK ephemeral public key.
 * @param threeDSRequestorAppURL is the 3DS Requestor App URL. If the app sets the URL, then the SDK shall pass the URL in the CReq.
 */
@Parcelize
@Serializable
data class ChallengeParameters(
    @SerialName("threeDSServerTransactionID")
    private var threeDSServerTransactionID: String? = null,

    @SerialName("acsTransactionID")
    private var acsTransactionID: String? = null,

    @SerialName("acsRefNumber")
    private var acsRefNumber: String? = null,

    @SerialName("acsSignedContent")
    private var acsSignedContent: String? = null,

    @SerialName("threeDSRequestorAppURL")
    private var threeDSRequestorAppURL: String? = null
) : Parcelable, ChallengeParameters

Please note that the first four parameters may be found in the authentication response message while the last parameter is an optional one. The threeDSRequestorAppURL consists of the requestor application URL. It may be used in an Out-Of-Band (OOB) authentication. When set, the Authentication App will receive the value from the ACS. This will enable the authentication app to open the requestor merchant app again when authentication is complete. More information about how to set this parameter can be found in the spec EMV 3-D Secure - Protocol and Core Functions Specification version 2.2.0 and in technical guides about launching intents of other packages. Please note that the 3DS transaction ID has to be concatenated to it.

Challenge flow behaviour

When a challenge is initiated, the 3DS SDK will start a new Activity which displays the challenge screen. It is not guaranteed how many challenges will be required to complete the authentication process as this is a decision made by the ACS based on the TRA. At any point the user may cancel the challenge flow by pressing the cancel button in the top bar of the challenge screen. On the other hand the back button will not function during the challenge flow.

Challenge flow results

After invoking the doChallenge function, the Challenge Flow starts and the 3DS SDK takes control over the user interface. This means that the Activity provided via the doChallenge function, should not finish or replaced by another Activity. The doChallenge function receives a callback object of type ChallengeStatusReceiver. This contract defines all the possible ways in which a challenge flow may end. The challenge may terminate with one of the following outcomes:

– Completed - The challenge flow ended and a transaction status is available. – Cancellation - The user decides to cancel the challenge (by pressing the cancel button in the Challenge screen top-bar). – Time out - The challenge may end with a time out when its not finished during the predefined period, set by the application when calling the doChallenge(...) function. – Runtime error - The 3DS SDK has tackled a runtime error during the challenge process. – Protocol error - The 3DS SDK received an error message from the ACS and had to terminate the challenge.

When any of these are invoked, the Challenge is considered to be finished. As a result, the 3DS SDK dismisses the Challenge screen, closes the transaction, cleans up resources and returns control back to the application.

The ChallengeStatusReceiver interface needs to be implemented by the requestor app. You may find an example of how to implement this contract in the sample app.

Dark mode support

The Ravelin 3DS SDK supports a dark mode theme. The integrator may provide customisation for both light and dark modes. In case that you prefer not to provide an optional UiCustomisation object for customising the UI components, the 3DS SDK will use its default values for both the light and the dark modes.

Required permissions

As part of complying with The EMVCo. standard, the Ravelin 3DS SDK collects information about the user device, which helps the ACS to conduct its TRA. To do so, the integrator needs to request the user to grant several runtime permissions and set some installation time permissions as well. Nonetheless, except for few of them, requesting these permissions is not considered mandatory, and the user may still be able to authenticate without granting them. On the other hand, The more device information collected by the SDK, the lower the risk for a user to receive a challenge verdict as the ACS has less uncertainty when making a TRA. In case your app is targeting Android SDK 13 or higher, you may decide to revoke those permissions your app has no longer need for, after finishing the 3DS SDK initialization. To revoke permissions you can use the following API revokeSelfPermissionsOnKill(Collection). The following tables lists the permissions required by the SDK and may be added to the manifest file:

Internet

<uses-permission android:name="android.permission.INTERNET"></uses-permission>

Access Network State

<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"></uses-permission>

Change Network State

<uses-permission android:name="android.permission.CHANGE_NETWORK_STATE"></uses-permission>

ACCESS_FINE_LOCATION

<uses-permission
    android:name="com.google.android.gms.permission.ACCESS_FINE_LOCATION"></uses-permission>

ACCESS_COARSE_LOCATION

<uses-permission
    android:name="com.google.android.gms.permission.ACCESS_COARSE_LOCATION"></uses-permission>

READ_PHONE_STATE

<uses-permission
    android:name="com.google.android.gms.permission.READ_PHONE_STATE"></uses-permission>

READ_BASIC_PHONE_STATE

<uses-permission
    android:name="com.google.android.gms.permission.READ_BASIC_PHONE_STATE"></uses-permission>

SEND_SMS

<uses-permission android:name="com.google.android.gms.permission.SEND_SMS"></uses-permission>

READ_PHONE_NUMBERS

<uses-permission
    android:name="com.google.android.gms.permission.READ_PHONE_NUMBERS"></uses-permission>

ACCESS_WIFI_STATE

<uses-permission
    android:name="com.google.android.gms.permission.ACCESS_WIFI_STATE"></uses-permission>

BLUETOOTH

<uses-permission android:name="android.permission.BLUETOOTH"></uses-permission>

BLUETOOTH_CONNECT

<uses-permission android:name="android.permission.BLUETOOTH_CONNECT"></uses-permission>

REQUEST_INSTALL_PACKAGES

<uses-permission android:name="android.permission.REQUEST_INSTALL_PACKAGES"></uses-permission>

Security

PCI requirements

The Ravelin 3DS SDK was designed to meet the requirements set in PCI 3DS SDK - Security Standard 1.1v. Nevertheless, these requirements entail constant updates and improvements as security threats become more and more sophisticated.

ProGuard rules

This section is relevant to application providers that use the R8 compiler to optimise and obfuscate their source code and app resources. The Ravelin 3DS SDK source code is obfuscated with the help of the R8 compiler. To avoid additional obfuscation/optimisation/shrinking please add the following keep rules to your ProGuard configuration file ProGuard rules. Ignoring these keep rules may lead to potential errors.

Recommendations for the integrator

Apart from complying with the requirements indicated by the EMVCo and the PCI specifications (please refer to Supporting documentation), some additional measures can be taken by the integrator, in order to mitigate some potential security threats. A full list of risks and vulnerabilities and their potential mitigations is outside the scope of this guide. Yet few important measures may be taken to make it harder for attackers to exploit your app. The following list includes only suggestions and/or recommendations:

Gradle

The latest version of the Ravelin 3DS SDK is built with AGP 8.5.1, Gradle Wrapper version 8.7 and compiled with Kotlin plugin version 2.0.20.

Dependencies

Please see below a list of dependencies used by the Ravelin 3DS SDK:

Release Notes

v1.4.2 - September 23, 2024

Minor changes

• Some third party dependencies were updated.
• Migration to Kotlin 2.0.20.
• New logging events were added. These information helps us to monitor the SDK in production.

Bug fixes

• Some Samsung devices throw an error when trying to read telephony data even with granted permissions. This data is used to build the device fingerprint for an ACS TRA. We now bypass reading such information on these type of devices.
• Send a CreateTransaction event only after SDK initialization check to avoid a scenario where the requestor app calls createTransaction before the SDK is fully initialized.

v1.4.1 - August 16, 2024

Minor changes

• A retry mechanism, based on AndroidX WorkManager was added to the logging unit. If the device connectivity to the network is lost, it tries to retransmit the events, once the device connectivity is renewed. It will do so even if the application is moved to the background or the application process is killed by the OS.
• Runtime errors verbosity is revised where possible to provide additional information to the requestor application.
• A new config parameter named appVersion was added. This parameter is used to set the version of the requestor application.

Bug fixes

• We have retired the use of the AndroidX security-crypto library. The library suffered from occasional synchronization problems on write/read to/from the device KeyStore. This issue was causing initialization problems on some devices. Instead, the same functionality is now integrated into the SDK itself.

v1.4.0 - February 20, 2024

Minor changes

• The SDK been re-certified by EMVCo.
• Granting the AD_ID permission in the requestor app is not required anymore and was removed from the device information spec. v1.6.
• Migration to Kotlin 1.9.22.
• Migration of annotation/symbol processing from kapt to ksp.
• SDK device information collection migration from v1.4 to v1.6.
• Update dependencies and build tools (see list of dependencies above).
• Processing screen half transparent overlay background color changed to 0x60FFFFFF in light mode and 0x60000000 in dark mode, as required by the EMVCo. specification bulletins(SB204 v7 and SB214 v3).

v1.3.0 - December 1, 2023

Minor changes

• Design adjustments in Native UI challenges.

v1.2.0 - November 13, 2023

Minor changes

• Compatibility with Android 14.
• Extend the usage of AndroidX datastore to fragments by replacing usage of fragments arguments bundles with datastore to bypass bundles size limitation.
• Upgrade third party dependencies and the build tools.
• Migrate to Kotlin 1.9.10.
• Source code improvements such as making it more functional and use of context receivers where applicable.
• Replace usage of the deprecated coroutines function whenResumed with the improved repeatOnLifecycle.
• Update the SDK ProGuard rules (see ProGuard rules).

v1.1.0 - September 13, 2023

Minor changes

• Update the Kotlin coroutines library version to 1.7.3.
• When the soft key is visible, for instance when the user types an OTP code, the challenge layout resizes to fit the remaining space. This results with the user ability to scroll and interact with views that are not visible when the soft key is visible.
• UI customisation improvements: the UI now uses ScaleDrawable to scale the customized view. For more information see the UiCustomization section.

Feedback

Was this page helpful?

Thanks for the feedback. If you'd like to provide more detail, please email support@ravelin.com.