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

You can now import frameworks with:

@import OPPWAMobile_ThreeDS;
@import ipworks3ds_sdk;

@import OPPWAMobile_ThreeDS
@import ipworks3ds_sdk

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.

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

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

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

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.

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

let threeDSTransaction = try OPPThreeDSService.sharedInstance.createTransaction(paymentBrand: "AMEX")

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

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.

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

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

let authRequestParams = try threeDSTransaction.getAuthRequestParams()

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

String authRequestParams = threeDSTransaction.getAuthRequestParams();

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

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.

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

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

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.

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
}

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   
}

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

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!