Mobile SDK Advanced Options

Here you can find out how to:

iOSAndroid

Device data collection

Device information is gathered by the Mobile 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".

App permissions

Some device data requires specific permissions to be granted, see the table below.

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

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, I002A001, A002, and add this info to the 3DS config.

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

[OPPThreeDSService sharedInstance].config = config;

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

OPPThreeDSService.sharedInstance.config = config

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

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

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

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

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

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

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:

[OPPThreeDSService sharedInstance].initCallback = self;

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

OPPThreeDSService.sharedInstance.initCallback = self

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

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

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 OPPCheckoutProviderDelegate to listen checkout eventsthe broadcast receiver to listen the intents from CheckoutActivity. 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.

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

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

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.

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());

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:

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());

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

Out-of-Band (OOB) authentication

Starting from 3D Secure version 2.2.0 OOB authenticating application can use special URL to call your application after an OOB authentication occurs.

You can set the URL in threeDSRequestorAppURL in OPPThreeDSConfig class. This is your app's URL in {CUSTOM_SCHEME}://{CUSTOM_DOMAIN} format. In an OOB authentication, the authenticating application uses this URL to call your merchant application after an OOB authentication occurs.

You should add the URL to the application build settings. Refer Register a custom URL scheme for more details:.

OPPThreeDSConfig *config = [[OPPThreeDSConfig alloc] init];
config.threeDSRequestorAppURL = @"{CUSTOM_SCHEME}://{CUSTOM_DOMAIN}";
[OPPThreeDSService sharedInstance].config = config;

let config = OPPThreeDSConfig()
config.threeDSRequestorAppURL = "{CUSTOM_SCHEME}://{CUSTOM_DOMAIN}"
OPPThreeDSService.sharedInstance.config = config

We strongly suggest to use threeDSRequestorAppURL different from shopperResultURL in order to simplify integration.

After successful OOB authentication redirect from authenticating application to merchant application will happen automatically.

UI customization

Mobile 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:

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;

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

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());

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()

Challenge screens customization