3DS SDK Advanced Options

Here you can find out how to:

Improve device data collection
Make authentication more secure
Customize challenge screens
Handle decoupled authentication

Todo Java Script

iOS

Device data collection

Device information is gathered by the 3DS SDK from a shopper device during 3DS Service initialization. By default, SDK collects as many parameters as it can. The full list of device info can be found in the EMVCo Specifications, check the file called “EMV® 3-D Secure SDK—Device Information”.

Device data blacklist

You can set a list of parameters which should not be pulled from the device because of some market or regional restrictions. Use identifiers from the “EMV® 3-D Secure SDK—Device Information” file, e.g. I001, I002, and add this info to the 3DS config.

Objective -C

Swift

Objective -C

OPPThreeDSConfig *config = [[OPPThreeDSConfig alloc] init];
NSArray<NSString *> *blacklist = @[@"I001", @"I002"];
config.deviceParameterBlacklist = blacklist;

[OPPThreeDSService sharedInstance].config = config;

Swift

let config = OPPThreeDSConfig()
let blacklist = ["I001", "I002"]
config.deviceParameterBlacklist = blacklist

OPPThreeDSService.sharedInstance.config = config

Security

As soon as 3DS Service is initialized, you may want to verify security warnings and abort the transaction in case of high risk. Here is the list of possible security warnings to be detected:

Security warning ID	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
SW04	A debugger is attached to the app.	Medium
SW05	The OS or the OS version is not supported.	High

Objective -C

Swift

Objective -C

NSError *error;
NSArray<Warning *> *warnings = [[OPPThreeDSService sharedInstance] getWarningsAndReturnError:&error];
if (warnings != nil && [warnings count] > 0) {
    // handle warnings
}

Swift

let warnings = try OPPThreeDSService.sharedInstance.getWarnings()
if warnings.count > 0 {
    // handle warnings
}

There are two places where you can check detected warnings:

Init callback
If you initialized 3DS Service yourself, you may check warnings right after the initialization is done. The service provides a callback for this:

Objective -C

Swift

Objective -C

[OPPThreeDSService sharedInstance].initCallback = self;

// OPPThreeDSServiceCallback protocol method
- (void)initializedWithError:(NSError * _Nullable)error {
    if (error == nil) {
        // check warnings here
    }
}

Swift

OPPThreeDSService.sharedInstance.initCallback = self

// OPPThreeDSServiceCallback protocol method
func initialized(error: Error?) {
    if error == nil {
        // check warnings here
    }
}

Before submit callback
If you use our Ready-to-use UI and let MSDK to do the initialization, the right place to check warnings is a callback which is called before submitting the transaction. For this purpose, you should implement OPPCheckoutProviderDelegate to listen checkout events. See details in the MSDK guide.

App bundle identifier

The expected bundle identifier for the application. This should match the Bundle Identifier identity setting specified when building the application. A security warning (SW02) is raised if this value does not match the Bundle ID of the application at runtime.

Note that this value should not be hardcoded in the app for security reasons. You should store it on your server and retrieve it in runtime.

Objective -C

Swift

Objective -C

OPPThreeDSConfig *config = [[OPPThreeDSConfig alloc] init];
config.appBundleID = @"com.companyname.appname";
[OPPThreeDSService sharedInstance].config = config;

Swift

let config = OPPThreeDSConfig()
config.appBundleID = "com.companyname.appname"
OPPThreeDSService.sharedInstance.config = config

UI customization

3DS SDK allows to customize challenge screens to match your app’s look-and-feel. API provides the following classes to customize specific elements on the screen:

Class	Description
`ToolbarCustomization`	Background color of the toolbar + header label customization
`LabelCustomization`	Heading text customization
`TextCustomization`	Non-heading text cusomization
`TextBoxCustomization`	Corner radius of input fields + label customization
`ButtonCustomization`	Button background color, corner radius and font customization. Make sure you set appropriate style for each type of buttons: `CANCEL` – Button placed in the right corner of Toolbar `SUBMIT` – Main action on the screen `RESEND` – Secondary action `CONTINUE` – Main action in case of authentication in the external app `NEXT` – Main action in case of authentication consists of several steps

See the sample code how UI customization can be applied in your app:

Objective -C

Swift

Objective -C

OPPThreeDSConfig *config = [[OPPThreeDSConfig alloc] init];
    
UiCustomization *uiCustomization = [[UiCustomization alloc] init];
ButtonCustomization *customButton = [uiCustomization getButtonCustomizationWithButtonType:ButtonTypeSUBMIT];
[customButton setTextColorWithColor:[UIColor whiteColor]];
[customButton setBackgroundColorWithColor:[UIColor redColor]];

config.uiCustomization = uiCustomization;
    
[OPPThreeDSService sharedInstance].config = config;

Swift

let config = OPPThreeDSConfig()
        
let uiCustomization = UiCustomization()
let customButton = uiCustomization.getButtonCustomization(buttonType: .SUBMIT)
customButton.setTextColor(color: UIColor.white)
customButton.setBackgroundColor(color: UIColor.red)

config.uiCustomization = uiCustomization

OPPThreeDSService.sharedInstance.config = config

Decoupled authentication

Some issuers may want to reach out to authenticate their cardholder outside of the EMV 3DS message flows. If decoupled authentication is supported, it’s recommended to add one more check for 3D Secure transaction status. If MSDK returns ‘decoupled’ status, then make sure that you add appropriate message on your order confirmation screen to let shopper know that external authentication is required. Provide all necessary recognizable data (merchant name, incremental transaction amount, reasons for additional authentication) that will allow shopper to go through authentication process seamlessly.

Objective -C

Swift

Objective -C

if (transaction.threeDS2Info.authStatus == OPPThreeDS2StatusDecoupledConfirmed) {
    // show confirmation screen with required information
}

Swift

if let status = transaction.threeDS2Info?.authStatus, status == .decoupledConfirmed {
    // show confirmation screen with required information
}

Note: Android

Android

Device data collection

Data source	Permission type	Required permissions
Telephony Manager	Run-time permissions	This group of parameters requires the following permissions: android.permission.SEND_SMS android.permission.READ_PHONE_STATE android.permission.READ_PHONE_NUMBERS User approval is not required for API 22 and earlier because these permissions are granted during installation.
Wifi Manager	Installation-time permissions	android.permission.ACCESS_WIFI_STATE
Bluetooth Manager	Installation-time permissions	android.permission.BLUETOOTH

Device data blacklist

Java

Kotlin

Java

OppThreeDSConfig.Builder configBuilder = new OppThreeDSConfig.Builder();
String[] blacklist = {"A001", "A002"};
configBuilder.setDeviceParameterBlacklist(blacklist);

OppThreeDSService.getInstance().setConfig(configBuilder.build());

Kotlin

val configBuilder = OppThreeDSConfig.Builder() 
val blacklist = arrayOf("A001", "A002") 
configBuilder.setDeviceParameterBlacklist(blacklist) 
 
OppThreeDSService.getInstance().config = configBuilder.build()

Security

As soon as 3DS Service is initialized, you may want to verify security warnings and abort the transaction in case of high risk. Here is the list of possible security warnings to be detected:

Security warning ID	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
SW04	A debugger is attached to the app.	Medium
SW05	The OS or the OS version is not supported.	High

Java

Kotlin

Java

List<Warning> warnings = OppThreeDSService.getInstance().getWarnings();
if (warnings.size() > 0) {
    // handle warnings
}

Kotlin

val warnings = OppThreeDSService.getInstance().warnings 
if (warnings.isNotEmpty()) { 
    // handle warnings 
}

There are two places where you can check detected warnings:

Init callback
If you initialized 3DS Service yourself, you may check warnings right after the initialization is done. The service provides a callback for this:

Java

Kotlin

Java

OppThreeDSService.getInstance().setInitCallback(new OppThreeDSService.Callback() {
    @Override
    public void onInitialized() {
        // check warnings here
    }
});

Kotlin

OppThreeDSService.getInstance().setInitCallback(object : OppThreeDSService.Callback() { 
    override fun onInitialized() { 
        // check warnings here 
    } 
})

Before submit callback
If you use our Ready-to-use UI and let MSDK to do the initialization, the right place to check warnings is a callback which is called before submitting the transaction. For this purpose, you should implement the broadcast receiver to listen the intents from CheckoutActivity. See details in the MSDK guide.

App signature

App signature is used to verify that application wasn’t tampered before installation. SDK expects the value as the SHA256 fingerprint of the certificate used to sign the app. A security warning (SW02) is raised if this value does not match the real app signature.

Note that app signature should not be hardcoded in the app for security reasons. You should store it on your server and retrieve it in runtime.

Java

Kotlin

Java

OppThreeDSConfig.Builder configBuilder = new OppThreeDSConfig.Builder();
configBuilder.setAppSignature("85:05:D8:B8:26:C6:AB:C6:AB:0B:49:08:F8:6E:5D:DF:CD:FF:16:69:DD:B2:93:3B:78:9D:64:6A:DE:FC:7A:9F");

OppThreeDSService.getInstance().setConfig(configBuilder.build());

Kotlin

val configBuilder = OppThreeDSConfig.Builder() 
configBuilder.setAppSignature("85:05:D8:B8:26:C6:AB:C6:AB:0B:49:08:F8:6E:5D:DF:CD:FF:16:69:DD:B2:93:3B:78:9D:64:6A:DE:FC:7A:9F") 
 
OppThreeDSService.getInstance().config = configBuilder.build()

Apps filter

3DS Service checks the list of installed apps on the shopper device. If it finds any suspicious applications or those that are not installed from the trusted app stores, a security warning (SW02) will be raised.

By default, trusted store is

Google Play store (com.android.vending)

and malicious apps are:

de.robv.android.xposed
de.robv.android.xposed.installer
com.saurik.substrate

You are welcome to complete these lists with your values using config properties:

Java

Kotlin

Java

OppThreeDSConfig.Builder configBuilder = new OppThreeDSConfig.Builder();
configBuilder.setTrustedAppStores(new String[]{"com.xiaomi.market"})
             .setMaliciousApps(new String[]{"de.robv.android.xposed"});

OppThreeDSService.getInstance().setConfig(configBuilder.build());

Kotlin

val configBuilder = OppThreeDSConfig.Builder() 
configBuilder.setTrustedAppStores(arrayOf("com.xiaomi.market")) 
             .setMaliciousApps(arrayOf("de.robv.android.xposed")) 
 
OppThreeDSService.getInstance().config = configBuilder.build()

UI customization

3DS SDK allows to customize challenge screens to match your app’s look-and-feel. API provides the following classes to customize specific elements on the screen:

Class	Description
`ToolbarCustomization`	Background color of the toolbar + header label customization
`LabelCustomization`	Heading text customization
`TextCustomization`	Non-heading text cusomization
`TextBoxCustomization`	Corner radius of input fields + label customization
`ButtonCustomization`	Button background color, corner radius and font customization. Make sure you set appropriate style for each type of buttons: `CANCEL` – Button placed in the right corner of Toolbar `SUBMIT` – Main action on the screen `RESEND` – Secondary action `CONTINUE` – Main action in case of authentication in the external app `NEXT` – Main action in case of authentication consists of several steps

See the sample code how UI customization can be applied in your app:

Java

Kotlin

Java

OppThreeDSConfig.Builder configBuilder = new OppThreeDSConfig.Builder();
        
UiCustomization uiCustomization = new UiCustomization();
ButtonCustomization customButton = new ButtonCustomization();
customButton.setTextColor("#FFFFFF"); // White
customButton.setBackgroundColor("#951728"); // Dark red
uiCustomization.setButtonCustomization(customButton, UiCustomization.ButtonType.SUBMIT);

configBuilder.setUiCustomization(uiCustomization);

OppThreeDSService.getInstance().setConfig(configBuilder.build());

Kotlin

val configBuilder = OppThreeDSConfig.Builder() 
 
val uiCustomization = UiCustomization() 
val customButton = ButtonCustomization() 
customButton.textColor = "#FFFFFF" // White 
customButton.backgroundColor = "#951728" // Dark red 
uiCustomization.setButtonCustomization(customButton, UiCustomization.ButtonType.SUBMIT) 
 
configBuilder.setUiCustomization(uiCustomization) 
 
OppThreeDSService.getInstance().config = configBuilder.build()

Decoupled authentication

Java

Kotlin

Java

ThreeDS2Info threeDS2Info = transaction.getThreeDS2Info();
if (threeDS2Info != null && threeDS2Info.getAuthStatus() == ThreeDS2Info.AuthStatus.DECOUPLED_CONFIRMED) {
    // show confirmation screen with required information
}

Kotlin

val threeDS2Info = transaction.threeDS2Info 
if (threeDS2Info != null && threeDS2Info.authStatus == ThreeDS2Info.AuthStatus.DECOUPLED_CONFIRMED) { 
    // show confirmation screen with required information 
}

3DS SDK Advanced Options

iOS

Device data collection

Device data blacklist

Security

App bundle identifier

UI customization

Decoupled authentication

Android

Device data collection

App permissions

Device data blacklist

Security

App signature

Apps filter

UI customization

Decoupled authentication