Mobile SDK Standalone

MSDK makes it easy to implement native 3D Secure 2 authentication in a mobile application.

NOTE: This guide is specific for the cases when Open Payment Platform (OPP) is not going to be used for some reason. Otherwise, refer to one of the integration types with MSDK.

Mobile SDK provides the following features:

• Collecting and encrypting user's device data
• Performing security checks
• Performing challenge process (including presenting UI and communication with ACS)

Features that are NOT included into the scope of SDK:

• Performing authentication request to the 3DS Server

iOSAndroid

Initialize the 3DS service

Initialization phase includes fetching actual config data from 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 MSDK.

Create 3DS transaction

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;
NSString *protocolVersion = @"2.2.0";
OPPThreeDSTransaction *transaction = [[OPPThreeDSService sharedInstance] createTransactionWithPaymentBrand:@"AMEX"
                                                                                           protocolVersion:protocolVersion
                                                                                                     error:&error];

let protocolVersion = "2.2.0"
let transaction = try OPPThreeDSService.sharedInstance.createTransaction(paymentBrand: "AMEX", 
                                                                      protocolVersion: protocolVersion)

String protocolVersion = "2.2.0";
OppThreeDSTransaction transaction = OppThreeDSService.getInstance().createTransaction("AMEX", protocolVersion);

val protocolVersion = "2.2.0"
val transaction: OppThreeDSTransaction = OppThreeDSService.getInstance().createTransaction("AMEX", protocolVersion)

NOTE: you need to provide valid 3D Secure 2 protocol version when creating transaction. Supported versions are 2.1.0 and 2.2.0.

Send authentication parameters

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 sent to the Server.

E.g. Platform expects it as threeDSecure.deviceInfo parameter in the payment submission request.

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

let authRequestParams = try transaction.getAuthRequestParams()

String authRequestParams = transaction.getAuthRequestParams();

val authRequestParams = transaction.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 = [transaction getProgressViewAndReturnError:&error];
[progressView show];

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

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

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

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

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

Handle authentication response

If card is enrolled for the 3D Secure 2, Server will return 3DS authentication status and client authentication response which is required for the challenge flow.

E.g. Platform parameters looks like:

<Result name="clientAuthResponse">{"messageType":"AuthResponse","messageVersion":"2.1.0",...}</Result>
<Result name="transactionStatus">C</Result>

Check authentication status

First, check the authentication status, it's one character string, see the meaning of possible values below:

Depending on status, start challenge or finish the checkout process:

if ([transactionStatus isEqualToString:@"C"]) {
    // start the challenge process to complete user authentication
} else {
    // authentication is complete
    // request payment status
}

if (transactionStatus == "C") {
    // start the challenge process to complete user authentication
} else {
    // authentication is complete
    // request payment status
}

if (transactionStatus.equals("C")) {
    // start the challenge process to complete user authentication
} else {
    // authentication is complete
    // request payment status
}

if (transactionStatus == "C") { 
    // start the challenge process to complete user authentication 
} else { 
    // authentication is complete 
    // request payment status 
}

Frictionless flow

Frictionless flow means that authentication is done. The payment will be completed or rejected depending on authentication result and system configuration. Request payment status to get the result of the transaction.

Challenge flow

For the challenge flow you will need to pass clientAuthResponse received from the Server to the MSDK 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;
[transaction doChallengeWithAuthResponse:clientAuthResponse
                    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 transaction.doChallenge(authResponse: clientAuthResponse,
                            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   
}

transaction.doChallenge(this, clientAuthResponse, 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
    }
});

transaction.doChallenge(this, clientAuthResponse, 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!