This guide describes how to use 3DS SDK in combination with the Mobile SDK (MSDK) and 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.
iOSAndroid
Requirements
MSDK 2.62.0 or higher
Xcode 12 and iOS 14 SDK
iOS 10.0+ deployment target
Android 4.4 (API Level 19) or higher
Import libraries
Import the following frameworks to the project:
ipworks3ds_sdk.xcframework // certified 3DS SDK
OPPWAMobile_ThreeDS.xcframework // wrapper SDK to simplify the integration
Drap and drop ipworks3ds_sdk.xcframework & OPPWAMobile_ThreeDS.xcframework to the "Frameworks" folder of your project. Make sure "Copy items if needed" is checked.
Embed the frameworks
Go to the app target’s General configuration page.
Add the frameworks target to the Frameworks, Libraries, and Embedded Content section by clicking the Add icon.
Review your Build Phases:
ipworks3ds_sdk.xcframework & OPPWAMobile_ThreeDS.xcframework are added to the "Link Binary With Libraries".
Import the following two libraries in your project in addition to the base Mobile SDK (File > New > New Module > Import .JAR/.AAR Package).
ipworks3ds_sdk.aar // certified 3DS SDK
oppwa.mobile.threeds.aar // wrapper SDK to simplify the integration
Add the module and required dependencies to the build.gradle:
// this name must match the library name defined with an include: in your settings.gradle file
implementation project(":ipworks3ds_sdk")
implementation project(":oppwa.mobile.threeds")
implementation "androidx.constraintlayout:constraintlayout:x.x.x"
Add the following rules into your project's proguard file:
-keep class com.oppwa.mobile.connect.threeds.OppThreeDSService { *; }
-keep class com.nsoftware.ipworks3ds.sdk.ThreeDS2Service { *; }
Initialize the 3DS service
Initialization phase includes pulling actual config data form the Server, collecting device data and performing security checks. All these actions are done in background thread, so start it whenever you want, it won't affect UI thread. It’s recommended to run initialization on checkout process start or even on application start.
val paymentBrands = listOf("AMEX", "VISA")
OppThreeDSService.getInstance().initialize(
applicationContext,
TransactionMode.LIVE,
paymentBrands)
We also recommend to look through the Customization guide to check advanced features of the 3DS SDK.
Send authentication params to the Server
After shopper entered card details and clicked Pay, use 3DS service to create 3DS transaction for the specific payment brand. Store a reference to the transaction, it will be needed later to initiate challenge process.
val threeDSTransaction: OppThreeDSTransaction = OppThreeDSService.getInstance().createTransaction("AMEX")
Getting authRequestParams will encrypt shopper device data and other important information needed for the 3DS Server to authenticate a transaction. It will return JSON string which should be added to the OPPCardPaymentParams class with collected card details (or OPPTokenPaymentParams class if you pay with the stored card). Then proceed with the Submit Transaction step of MSDK integration guide.
let progressView = try threeDSTransaction.getProgressView()
progressView.show()
// Later, to hide/close:
progressView.close()
ProgressDialog progressDialog = threeDSTransaction.getProgressView(activity);
progressDialog.show();
// Later, to hide/dismiss:
progressDialog.dismiss();
val progressDialog = threeDSTransaction.getProgressView(activity)
progressDialog.show()
// Later, to hide/dismiss:
progressDialog.dismiss()
Handle authentication response
If shopper's card is enrolled for the 3D Secure 2, Server will return 3DS specific information in the threeDS2Info property of the OPPTransaction object. Here you should check if challenge is required or authentication is already done (frictionless flow).
[paymentProvider submitTransaction:transaction
completionHandler:^(OPPTransaction * _Nonnull transaction,
NSError * _Nullable error) {
if (transaction.threeDS2Info.isChallengeRequired) {
// start the challenge process to complete user authentication
} else {
// proceed as for common transaction based on transaction.getTransactionType() value
}
}];
paymentProvider.submitTransaction(transaction) { (transaction, error) in
if (transaction.threeDS2Info.isChallengeRequired()) {
// start the challenge process to complete user authentication
} else {
// proceed as for common transaction based on transaction.type value
}
}
@Override
public void transactionCompleted(Transaction transaction) {
ThreeDS2Info threeDS2Info = transaction.getThreeDS2Info();
if (threeDS2Info != null && threeDS2Info.isChallengeRequired()) {
// start the challenge process to complete user authentication
} else {
// proceed as for common transaction based on transaction.type value
}
}
override fun transactionCompleted(transaction: Transaction) {
val threeDS2Info = transaction.threeDS2Info
if (threeDS2Info != null && threeDS2Info.isChallengeRequired) {
// start the challenge process to complete user authentication
} else {
// proceed as for common transaction based on transaction.type value
}
}
Challenge flow
For the challenge flow you will need to pass authentication response to the 3SD SDK and start the challenge. The SDK will take care of all communication with the ACS while performing the challenge, as well as prompting the shopper as needed for the required input. When the challenge process is complete, control returns to the app in the one of the OppThreeDSChallengeCallback events. See how it can be implemented in the sample code below.