3DS SDK + MSDK + Your Custom UI

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

Todo Java Script

iOS

Requirements

MSDK 2.62.0 or higher
Xcode 12 and iOS 14 SDK
iOS 10.0+ deployment target

Import libraries

ipworks3ds_sdk.xcframework // certified 3DS SDK
OPPWAMobile_ThreeDS.xcframework // wrapper SDK to simplify the integration

There are two versions of the ipworks3ds_sdk.xcframework included: 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. The deployment version includes _deploy in the filename.

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

You can now import frameworks with:

@import OPPWAMobile_ThreeDS;
@import ipworks3ds_sdk;

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.

Objective -C

Swift

Objective -C

NSArray<NSString *> *paymentBrands = @[@"AMEX", @"VISA"];
[[OPPThreeDSService sharedInstance] initializeWithTransactionMode:OPPThreeDSTransactionModeLive
                                                    paymentBrands:paymentBrands];

Swift

let paymentBrands = ["AMEX", "VISA"]
OPPThreeDSService.sharedInstance.initialize(transactionMode: .live, paymentBrands: paymentBrands)

We also recommend to look through the Customization Guide 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.

Objective -C

Swift

Objective -C

NSError *error;
OPPThreeDSTransaction *threeDSTransaction
    = [[OPPThreeDSService sharedInstance] createTransactionWithPaymentBrand:@"AMEX"
                                                                      error:&error];

Swift

let threeDSTransaction = try OPPThreeDSService.sharedInstance.createTransaction(paymentBrand: "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.

Objective -C

Swift

Objective -C

NSError *error;
NSString *authRequestParams = [threeDSTransaction getAuthRequestParamsAndReturnError:&error];

OPPCardPaymentParams *params = [OPPCardPaymentParams ...];
params.threeDS2AuthParams = authRequestParams;

Swift

let authRequestParams = try threeDSTransaction.getAuthRequestParams()

let params = try OPPCardPaymentParams(...)
params.threeDS2AuthParams = authRequestParams

Display processing view

It’s also required to show appropriate processing view while communicating with the Server. You can use processing view provided by the SDK.

Objective -C

Swift

Objective -C

NSError *error;
ProgressView *progressView = [threeDSTransaction getProgressViewAndReturnError:&error];
[progressView show];

// Later, to hide/close:
[progressView close];

Swift

let progressView = try threeDSTransaction.getProgressView()
progressView.show()

// Later, to hide/close:
progressView.close()

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

Objective -C

Swift

Objective -C

[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
    }
}];

Swift

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
    }
}

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.

Objective -C

Swift

Objective -C

NSError *error;
[threeDSTransaction doChallengeWithAuthResponse:transaction.threeDS2Info.authResponse
                           navigationController:self.navigationController
                              challengeCallback:self
                                          error:&error];

// OPPThreeDSChallengeCallback protocol methods
- (void)completedWithCompletionEvent:(OPPThreeDSCompletionEvent * _Nonnull)completionEvent {
    // 3DS authentication completed
}

- (void)failedWithErrorEvent:(OPPThreeDSErrorEvent * _Nonnull)errorEvent {
    // some unexpected error happened
}

- (void)cancelled {
   // shopper aborted 3DS authentication
}

Swift

try threeDSTransaction.doChallenge(authResponse: transaction.threeDS2Info.authResponse,
                                   navigationController: self.navigationController,
                                   challengeCallback: self)
 
// OPPThreeDSChallengeCallback protocol methods
func completed(completionEvent: OPPThreeDSCompletionEvent) {
    // 3DS authentication completed
}

func failed(errorEvent: OPPThreeDSErrorEvent) {
    // some unexpected error happened
}  

func cancelled() {
    // shopper aborted 3DS authentication   
}

At last, request payment status to finalize the checkout process, and you’re done!

Note: Android

Android

Requirements

MSDK 2.62.0 or higher
Android 4.4 (API Level 19) or higher

Import libraries

ipworks3ds_sdk.aar // certified 3DS SDK
oppwa.mobile.threeds.aar // wrapper SDK to simplify the integration

There are two versions of the ipworks3ds_sdk.aar included: 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. The deployment version includes _deploy in the filename.

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

Initialize the 3DS service

Java

Kotlin

Java

List<String> paymentBrands = Arrays.asList("AMEX", "VISA");
OppThreeDSService.getInstance().initialize(
          getApplicationContext(),
          TransactionMode.LIVE,
          paymentBrands);

Kotlin

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

Java

Kotlin

Java

OppThreeDSTransaction threeDSTransaction = OppThreeDSService.getInstance().createTransaction("AMEX");

Kotlin

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 CardPaymentParams class with collected card details (or TokenPaymentParams class if you pay with the stored card). Then proceed with the Submit Transaction step of MSDK integration guide.

Java

Kotlin

Java

String authRequestParams = threeDSTransaction.getAuthRequestParams();

CardPaymentParams params = new CardPaymentParams(...);
params.setThreeDS2AuthParams(authRequestParams);

Kotlin

val authRequestParams = threeDSTransaction.authRequestParams 
 
val params = CardPaymentParams(...) 
params.threeDS2AuthParams = authRequestParams

Display processing view

It’s also required to show appropriate processing view while communicating with the Server. You can use processing view provided by the SDK.

Java

Kotlin

Java

ProgressDialog progressDialog = threeDSTransaction.getProgressView(activity);
progressDialog.show();
 
// Later, to hide/dismiss:
progressDialog.dismiss();

Kotlin

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 Transaction object. Here you should check if challenge is required or authentication is already done (frictionless flow).

Java

Kotlin

Java

@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
    }
}

Kotlin

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 ChallengeCallback events. See how it can be implemented in the sample code below.

Java

Kotlin

Java

threeDSTransaction.doChallenge(this, threeDS2Info.getAuthResponse(), new ChallengeCallback() {
    
    @Override
    public void onComplete(CompletionEvent completionEvent) {
        // 3DS authentication completed
    }
 
    @Override
    public void onFailure(ErrorEvent errorEvent) {
        // some unexpected error happened
    }
 
    @Override
    public void onCancel() {
        // shopper aborted 3DS authentication
    }
});

Kotlin

threeDSTransaction.doChallenge(this, threeDS2Info.authResponse!!, object : ChallengeCallback { 
    override fun onComplete(completionEvent: ChallengeCallback.CompletionEvent) { 
        // 3DS authentication completed 
    } 
 
    override fun onFailure(errorEvent: ChallengeCallback.ErrorEvent) { 
        // some unexpected error happened 
    } 
 
    override fun onCancel() { 
        // shopper aborted 3DS authentication 
    } 
})

At last, request payment status to finalize the checkout process, and you’re done!