3DS SDK Standalone

3DS SDK 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.

3DS 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

Todo Java Script

iOS

Requirements

  • Xcode 11 and iOS 13 SDK
  • iOS 10.0+ deployment target

Import libraries

Import the following frameworks to the project:

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.

  1. Drap and drop ipworks3ds_sdk.xcframework & OPPWAMobile_ThreeDS.xcframework to the “Frameworks” folder of your project.Make sure “Copy items if needed” is checked.
  2. 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.
  3. 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 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.

We also recommend to look through the Customization Guide to check advanced features of the 3DS SDK.

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.

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.

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.

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:

StatusDescription
CIn-app challenge required; additional authentication is required using the CReq/CRes.
YAuthentication/account verification successful.
NNot authenticated/account not verified; transaction denied.
AAttempts processing performed; not authenticated/verified, but a proof of attempted authentication/verification is provided.
RAuthentication/account verification rejected; issuer is rejecting authentication/verification and request that authorization not be attempted.
UAuthentication/account verification could not be performed; technical or other problem as indicated in ARes or RReq.
DExternal challenge required; decoupled authentication confirmed.

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

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

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

Note: Android

Requirements

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

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.

We also recommend to look through the Customization guide to check advanced features of the 3DS SDK.

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.

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.

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.

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:

StatusDescription
CIn-app challenge required; additional authentication is required using the CReq/CRes.
YAuthentication/account verification successful.
NNot authenticated/account not verified; transaction denied.
AAttempts processing performed; not authenticated/verified, but a proof of attempted authentication/verification is provided.
RAuthentication/account verification rejected; issuer is rejecting authentication/verification and request that authorization not be attempted.
UAuthentication/account verification could not be performed; technical or other problem as indicated in ARes or RReq.
DExternal challenge required; decoupled authentication confirmed.

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

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

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