3D Secure 2

Keep your transactions compliant with Strong Customer Authentication (SCA) requirements and bring more friendly user experience to your customers with a 3D Secure 2, also known as EMV 3D Secure, a brand new secure authentication protocol which supports app-based authentication. Mobile SDK makes it easy to integrate all new 3DS features into your e-commerce app.

App-based authentication

In the app-based flow, a cardholder initiates a transaction on a mobile device (Android or iOS) from a 3DS-enabled app. Mobile SDK collects and encrypts data from the mobile device, and sends it to the issuer bank. Based on the data, the bank decides whether additional cardholder interaction is required.

Frictionless flow

The authentication is achieved without cardholder interaction.

Challenge flow

Cardholder interaction is required to authenticate the payment. With Mobile SDK, the authentication is embedded natively in app, i.e no redirects to a browser. There are a variety of authentication options which the bank can initiate. It can be a simple password input in a native UI, an OTP, or an "out-of-band authentication", where the authentication happens via fingerprint or facial recognication in the banking app. Check Advanced Options for more details.

Integration types

The Mobile SDK (MSDK) provides seamless integration with 3D Secure 2 payments.

Integration steps differs depending on how MSDK is used in your app. In these guides we assume that you already integrated base MSDK to make payments with one of the following ways:

• Ready-to-Use UI - using our checkouts screen;
• Your Custom UI - using MSDK just for sending transactions.

Where do I start?

3D Secure 2 should work out of the box with the MSDK. Just configure 3DS 2 in the Administration Portal, import 3DS library to your project, and you are ready to run first 3DS 2 transaction.

Import the library

If you followed Install the SDK guide, then the library ipworks3ds_sdk is already installed. No extra imports is required.

There are two versions of the ipworks3ds_sdk: one to be used for development and one for production. The production version includes more strict security measures that would not allow for common development processes to occur, including running with attached debuggers or using simulators/emulators. In particular, the production version does not work with apps outside the official app/play store. The production version includes _deploy in the filename.

Ready-to-use UI

We assume that you already went through the base MSDK integration guide and can submit payments. If yes, proceed with the following instructions to enhance payments with the 3D Secure 2 verification.

NOTE: First of all, proper configuration in the Administration Portal should be done to enable 3DS 2 for the specific card brands.

There are no mandatory steps for 3D Secure 2 integration, everything is working out of the box. However, we strongly recommend to look through the Advanced Options. Use the threeDSConfig property of the OPPCheckoutSettings instance to apply customizations.

OPPThreeDSConfig *config = [[OPPThreeDSConfig alloc] init];
checkoutSettings.threeDSConfig = config;

let config = OPPThreeDSConfig()
checkoutSettings.threeDSConfig = config

CheckoutSettings checkoutSettings = new CheckoutSettings(checkoutId, paymentBrands, providerMode);
ThreeDSConfig.Builder configBuilder = new ThreeDSConfig.Builder();
checkoutSettings.setThreeDS2Config(configBuilder.build());

val checkoutSettings = CheckoutSettings(checkoutId, paymentBrands, providerMode) 
val configBuilder =ThreeDSConfig.Builder() 
checkoutSettings.setThreeDS2Config(configBuilder.build())

Your Custom UI

We assume that you already went through base MSDK integration guide and can submit payments. If yes, proceed with the following instructions to enhance payments with the 3D Secure 2 verification.

NOTE: First of all, proper configuration in the Administration Portal should be done to enable 3DS 2 for the specific card brands.

Implement challenge callback

ThreeDSWorkflowListener threeDSWorkflowListener = new ThreeDSWorkflowListener() {
    @Override
    public Activity onThreeDSChallengeRequired() {
        // provide your Activity
        return activity;
    }

    @Override
    public ThreeDSConfig onThreeDSConfigRequired() {
        // provide your ThreeDSConfig
        return threeDSConfig;
    }
};

val threeDSWorkflowListener: ThreeDSWorkflowListener = object : ThreeDSWorkflowListener {
    override fun onThreeDSChallengeRequired(): Activity {
        // provide your Activity
        return activity
    }

    override fun onThreeDSConfigRequired(): ThreeDSConfig {
        // provide your ThreeDSConfig
        return threeDSConfig
    }
}

paymentProvider.setThreeDSWorkflowListener(threeDSWorkflowListener);

paymentProvider!!.setThreeDSWorkflowListener(threeDSWorkflowListener)

@interface MyCardViewController() <OPPThreeDSWorkflowListener>
    @property (nonatomic) OPPPaymentProvider *paymentProvider;
    //...
@end

class MyCardViewController: OPPThreeDSWorkflowListener {
    var provider: OPPPaymentProvider?
    ///
}

self.paymentProvider.threeDSEventListener = self;

self.provider?.threeDSEventListener = self

//OPPThreeDSEventListener protocol methods
- (void)onThreeDSConfigRequiredWithCompletion:(void (^)(OPPThreeDSConfig * _Nonnull))completion {
    OPPThreeDSConfig *config = [[OPPThreeDSConfig alloc] init];
    //return config
    completion(config);
}

- (void)onThreeDSChallengeRequiredWithCompletion:(void (^)(UINavigationController * _Nonnull))completion {
    //return Navigation Controller
    completion(self.navController);
}

//OPPThreeDSEventListener protocol methods
    func onThreeDSChallengeRequired(completion: @escaping (UINavigationController) -> Void) {
        completion(self.navigationController!)
    }
    
    func onThreeDSConfigRequired(completion: @escaping (OPPThreeDSConfig) -> Void) {
        let config = OPPThreeDSConfig()
        completion(config)
    }

Submit transaction call

From now just follow with Submit Transaction step of MSDK Custom UI integration guide. All 3D secure 2 actions are integrated within payment request.

if (ThreeDS2Service.wasTransactionKilled()) {
    // request payment status
}

if (ThreeDS2Service.wasTransactionKilled()) {
    // request payment status
}

Advanced Options

Here you can find out how to:

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".

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;

checkoutSettings.threeDSConfig = config;

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

checkoutSettings.threeDSConfig = config

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

checkoutSettings.setThreeDS2Config(configBuilder.build());

val configBuilder = ThreeDSConfig.Builder() 
val blacklist = arrayOf("A001", "A002") 
configBuilder.setDeviceParameterBlacklist(blacklist) 

checkoutSettings.setThreeDS2Config(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:

[paymentProvider securityWarningsWithCompletionHandler:^(NSArray * _Nullable warnings, NSError * _Nullable error) {
    if (warnings != nil && [warnings count] > 0) {
        // handle warnings
    }];
}

paymentProvider!.securityWarnings { (warnings, error) in
    if warnings.count > 0 {
        // handle warnings
    }            
}

• If you use our Ready-to-use UI 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.

public class CheckoutBroadcastReceiver extends BroadcastReceiver {

    @Override
    public void onReceive(Context context, Intent intent) {
        String action = intent.getAction();

        if (CheckoutActivity.ACTION_ON_BEFORE_SUBMIT.equals(action)) {
            if (intent.hasExtra(CheckoutActivity.EXTRA_THREEDS_WARNINGS)) {
	        List<Warning> threeDS2Warnings = intent
		    .getParcelableArrayListExtra(CheckoutActivity.EXTRA_THREEDS_WARNINGS);

		    // handle warnings
	    }
        }
    }
}

class CheckoutBroadcastReceiver : BroadcastReceiver() {

    override fun onReceive(context: Context?, oldIntent: Intent?) {
        val action = oldIntent?.action

        if (CheckoutActivity.ACTION_ON_BEFORE_SUBMIT == action) {
            if (intent.hasExtra(CheckoutActivity.EXTRA_THREEDS_WARNINGS)) {
                val threeDS2Warnings: List<Warning> = intent
                        .getParcelableArrayListExtra(CheckoutActivity.EXTRA_THREEDS_WARNINGS)

                // handle warnings
            }
        }
    }
}

• If you use Mobile SDK and Your Custom UI you can invoke this method anywhere in your code.

List<Warning> threeDS2Warnings = paymentProvider.getThreeDS2Warnings();

val threeDS2Warnings: List<Warning> = paymentProvider!!.threeDS2Warnings

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

let config = OPPThreeDSConfig()
config.appBundleID = "com.companyname.appname"
checkoutSettings.threeDSConfig = config

ThreeDSConfig.Builder configBuilder = new ThreeDSConfig.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");

checkoutSettings.setThreeDS2Config(configBuilder.build());

val configBuilder = ThreeDSConfig.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") 
 
checkoutSettings.setThreeDS2Config(configBuilder.build())

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

checkoutSettings.setThreeDS2Config(configBuilder.build());

val configBuilder = ThreeDSConfig.Builder() 
configBuilder.setTrustedAppStores(arrayOf("com.xiaomi.market")) 
             .setMaliciousApps(arrayOf("de.robv.android.xposed")) 
 
checkoutSettings.setThreeDS2Config(configBuilder.build())

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

let config = OPPThreeDSConfig()
config.threeDSRequestorAppURL = "{CUSTOM_SCHEME}://{CUSTOM_DOMAIN}"
checkoutSettings.threeDSConfig = config

ThreeDSConfig threeDSConfig = new ThreeDSConfig.Builder()
        .setThreeDSRequestorAppUrlUsed(true)
        .build();
checkoutSettings.setThreeDS2Config(threeDSConfig);

val threeDSConfig: ThreeDSConfig = ThreeDSConfig.Builder()
        .setThreeDSRequestorAppUrlUsed(true)
        .build()
checkoutSettings.threeDS2Config = threeDSConfig