Android 3DS demo application guide

Contents

The demo application

A demo application is provided in addition to the Ravelin 3DS SDK. It has two main goals:

  1. To assist users integrating with Ravelin’s 3DS SDK.
  2. To demonstrate frictionless and challenge flows supported by Ravelin’s 3DS SDK.

System requirements

The Ravelin Android 3DS demo application supports a minimum Android version Android 5 (API Level 21).

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:

Application structure

The Ravelin 3DS demo application consists of several screens:

Login screen

The user is required to login to the application. In order to login, provide the cid you normally use in order to login to the Ravelin dashboard. for instance when you login to the Ravelin dashboard with SSO you normally see an address in the following format:

https://id.ravelin.com/?dest=https%3A%2F%2F<your-cid>-sandbox.ravelin.com%2F

or

https://id.liveus.ravelin.net/?dest=https%3A%2F%2F<your-cid>-sandbox.liveus.ravelin.net%2F

where <your-cid> is the CID of your organisation. In the login screen, you need to provide this value, i.e. <your-cid>. Now press the Login button and that will walk you through the normal Ravelin login process, where you can sign in with SSO. Each login (as long as the application is not reinstalled) should last for three days.

User login

On cold start, the application will ask the user to grant different runtime permissions. The exact permissions and their use is explained in Android 3DS SDK guide.

Initializing screen

The 3DS demo application uses this screen to initialise the Ravelin 3DS SDK. The initialization process should last for 800-1,600 milliseconds. Warnings discovered during the 3DS SDK initialisation process will be displayed for a short period of time (few seconds) before navigating to the landing page of the application.

Below is a list containing the possible warnings that may be displayed. These warnings are defined in the Supporting documentation section:

Code Description Severity Level
SW01 The device is jailbroken. HIGH
SW02 The integrity of the SDK has been tampered. HIGH
SW03 An emulator is being used to run the App. HIGH
SM04 A debugger is attached to the App. MEDIUM
SW05 The OS or the OS version is not supported. HIGH

The initialisation may also end with an error, for instance when a timeout occurs before the SDK finishes initialising. In that case please check your internet connection and try again. If that doesn’t help please contact Ravelin support.

Use cases selection screen

In this screen the user may choose between two types of use cases:

1. Demo

This use case should include test cases for demo purposes.

2. Integration

This use case should include test cases which are more relevant for integrators.

Nevertheless, you are encouraged to try both use cases.

Test scenarios screen

After selecting a use case, press the ‘Next’ button and the application should fetch the relevant test scenarios. The test cases are grouped into different categories. To run a test case:

  1. Open the relevant group. The first test scenario will be selected by default.
  2. Choose the test case you are interested in.
  3. Press the ‘Submit’ button to start running the test case.

In case that the test scenario includes an OTP (One Time Password) the user will be asked to insert the one time passcode in the OTP screen. For demo purposes, the pass code is always 1234.

Please note: The user may run a single test scenario at a time.

Test scenarios

Order confirmation screen

When the test case is over the application is redirected to the order confirmation screen. This screen is used to display the test case status. There are three possible statuses:

  1. Test case ended successfully (green image).
  2. Test case ended unsuccessfully with an expected error (yellow image) - This case is unique for ‘Errors and attempts’ test cases.
  3. Test case ended unsuccessfully with an error (red image) - The server ends the test case with an intended failure. But its also possible that a challenge was cancelled by the user or a timeout error has occurred since the challenge may not last more than 5 minutes. Red image may also get displayed when a real error happens in the system while running the test case.

The test case ending status is indicated by the test case name or by its group name in the case of ‘Errors and attempts’. The color of the image shown in this screen is an indication of the test case status: Order confirmation status

Settings screen

The settings screen is reachable from the Use case selection screen top-bar. It is used to configure the application. In this screen you may configure the following parameters:

1. Dark mode preference. The user may choose to use the device system default theme or customise it. In case you choose a theme different from the system default, it will also be automatically configured by the SDK to keep both the demo application and the SDK in sync. Nevertheless, it is up to the integrators decision whether to support this feature or not. To support this feature the integrator is required to set the theme in the Activity intent extras. The following snippet from the application is an example:

        private fun setAppUiTheme(useDarkTheme: Boolean) = when (useDarkTheme) {
            true -> this@MainActivity.intent.putExtra(APP_UI_MODE, DARK_MODE)
            false -> this@MainActivity.intent.putExtra(APP_UI_MODE, LIGHT_MODE)
        }

where:

    const val APP_UI_MODE = "uiMode"
    const val LIGHT_MODE = "light"
    const val DARK_MODE = "dark"

Since the application provides a reference of the Activity to the 3DS SDK, the SDK is able to access the value described above.

2. Set a token manually - The user may choose to set a unique token manually. The token is used to fetch the relevant test cases for the user. A default token is set automatically by the SDK during the initialisation process. Due to info security reasons, the application doesn’t store the token and it is lost when the application is closed.

Telemetry screen

The telemetry screen is reachable from the Test scenarios screen by clicking on the icon in the top-right corner. It is used to display the telemetry data collected by the SDK. This screen displays three charts:

1. SDK Initialisation duration

This chart displays the last 12 measurements taken and the mean and standard deviation of the entire dataset.

2. Executed tests - Success rate

This chart displays the success rate of executed tests. A failure means that a test card ended different than it was supposed to. The chart should display only after executing at least one test case.

3. Executed tests per topic

This chart displays the percentage of executed tests per topic out of all executed tests. The topics are:

  • Challenge flow.
  • Frictionless flow.
  • Errors and attempts.

The chart should display only after executing at least one test case.

How to access the demo application

The Android 3DS demo application can be accessed in two different ways, depending on the use case:

  1. For demos - Google Play Store.
  2. For technical audience - The Ravelin Dashboard.

Google Play Store

Provide a verified Google e-mail address to Ravelin support to be added to a distribution group. After being added to the distribution group you will receive an e-mail inviting you to join a close testing. Accept the invitation to download the app. Please make sure that the user logged into Google is the same as the e-mail address you have shared with Ravelin support.

The Ravelin dashboard

Please reach out to Ravelin support to receive access to the 3DS demo application on the Ravelin dashboard. With this option you can access the application source code. This option is aimed for developers who want to learn how to integrate the 3DS SDK into their own apps.

You can find the files in the dashboard under your organisation page. The shared files page on the Ravelin dashboard:

Files sharing

Before running the application

Prerequisites for demo users

There are no special requirements for demo users.

Prerequisites for integrators

1. Make sure you have a set of credentials to access the Ravelin private repository. This is required to import the Ravelin 3DS SDK into the application. 2. Create a new folder named properties in the project and in the folder add a new properties file and call it cloudRepo.properties. Add your credentials as shown below:

ravelinRepoUsername = username
ravelinRepoPassword = password

3. There are several build variants in the application. In case you want to build a live variant (EuLive or UsLive), you will need to provide a signing key in the build.gradle.kts file in the :app module.

You are ready to run the application!

Application initialisation

For integrators who have received the application through the dashboard only

When the splash screen loads, the Ravelin 3DS SDK is being initialised. When initialisation is done, the application may shortly display several warnings, acc. to the 3DS SDK findings. Since the demo application for integrators is not installed directly from the Google play store, you should expect the a SW02 warning, which means that The integrity of the SDK has been tampered. This is an expected behaviour. You may notice other warnings as well, depending on the mode of operation of the demo application (See also Initializing screen).

Test cards

Test cards for demo purposes

The demo application offers different types of show cases as summarised in the table below:

# Show Case Expected Result (depends on the test case) Comments
1. Frictionless flow Successful/failed authentication
2. One Time Passcode/Text challenge Successful/failed authentication Use the code ‘1234’ in the challenge
3. Single selection followed by an OTP challenge Successful/failed authentication Use the code ‘1234’ in the challenge
4. Knowledge Base Challenge - Multi selection challenge Successful/failed authentication
5. Out-Of-Band Challenge Successful/failed authentication
6. One Time Passcode/Text challenge - HTML Display Successful/failed authentication Use the code ‘1234’ in the challenge
7. Single selection followed by an OTP challenge - HTML Display Successful
8. Knowledge Base Challenge - Multi selection challenge - HTML Display Successful
9. Out-Of-Band Challenge - HTML Display Successful
10. One Time Passcode/Text challenge - HTML ‘Other’ UI Template Successful/failed authentication

Please note:

  • While running a challenge test case, the user may choose to cancel the challenge by pressing the Cancel button located in the top-bar. In that case, the expected outcome of the challenge should be Challenge Canceled.
  • When timeout is reached during a challenge, it ends automatically and a timeout error message is displayed. The default timeout is 5 minutes.
  • Pressing the back button while the application displays a challenge screen has no impact. Please check out the Supporting documentation for more information.
  • When running the OTP challenge, you will see a message which says that an SMS is being sent to a phone number ending in ‘5329’. This is a generic number used for demo purposes and an SMS will not actually be sent. Please refer to the one-time password to be used in this case.
  • You may find more information about the test cards in 3DS test cards.

Running test cases

The next sections are relevant only for integrators.

Test cases are used for demo purposes only, hence to run them you need to use mocked directory server schemes rather than real directory server schemes such as Visa, Mastercard, Amex etc. The demo application uses the following mocked directory server schemes:

# Directory server Id Directory server name Comments
1. M000000003 mocked directory server A Will display a VISA logo
2. M000000004 mocked directory server B Will display a Mastercard logo
3. M000000025 mocked directory server C Will display an Amex logo

How to access mock directory server schemes

When initialising the SDK, the SDK fetches meta data from Ravelin. Part of the meta data are the mock directory servers. Before calling the 3DS SDK function createTransaction(directoryServerId, messageVersion), the application uses the testcard PAN to detect the relevant directory server ID. The PAN also enables the app to fetch the message version relevant to the directory server which is identified by the PAN and the directory server ID. Only after these values are fetched may the application call the createTransaction function and generate an authentication request (AReq) message.

View test cases logs in the dashboard

After you run a test case, you can view the logs of the authentication request in the Ravelin dashboard. To view the logs, go to your CID page in Ravelin dashboard and pick the sandbox environment. In the left corner menu select Explore > Authentications.

Authentications

Error messages: codes and descriptions

Authentication Request (AReq)

Internal Error Code Error Error Description transStatus EMVCo code
102 Authentication Failed Authentication Denied N
103 Authentication Failed Verification attempt failed A
104 Authentication Failed Verification attempt rejected R
105 Authentication Failed Verification account error U

Challenge Request (CReq)

Internal Error Code Error Error Description EMVCo Challenge Event State transStatus EMVCo code
200 Challenge Failed Challenge Denied - N
201 Challenge Failed Challenge Cancelled Cancelled N
202 Challenge Failed Challenge Timeout Timeout N
203 Challenge Failed Challenge Protocol Error Protocol Error N
204 Challenge Failed Challenge Runtime Error Runtime Error N

Feedback

© Ravelin Technology Ltd. All rights reserved