Skip to content

3D Secure Authentication

Jump to bottom
Al Kent edited this page Sep 27, 2018 · 9 revisions

3-D Secure Authentication

Basic 3-D Secure Transaction Lifecycle

3DS Flow

Components

  • Merchant Mobile App: A mobile app integrated with the Gateway Mobile SDK
  • Merchant Web Service: A web service, hosted and maintained on the merchant's servers, which will handle sending authenticated requests to the Gateway.
  • Gateway: An instance of your Gateway provider.
  • Gateway SDK 3DS Web View: A component of the SDK that help render web pages required during the 3DS authentication flow.
  • Issuer Authentication Page: A web page, hosted by the issuing bank of the card being processed. This page will prompt a card holder for additional authentication information then redirect the response to a page hosted on the merchant's servers.
  • Merchant Redirect Page: A landing page that accepts the Issuer's ACS response data and processes it with the Gateway. The resulting information is then sent back to the mobile app by appending it to a custom URL and redirecting the browser. See Merchant Redirect Page below for more information.

Steps

  1. The mobile app requests a new Session from the merchant service. This is an authenticated call, meaning it requires a private API password, which is why it needs to be carried out on a secure server, rather than the mobile device.
  2. The merchant service calls Create a Session on the Gateway.
  3. Information about the newly created session is returned to the merchant service, including the Session Id.
  4. The Session Id + the version of the API used to create it is returned back to the mobile app. Updating the session with card details must use the same Gateway API version number that created it.
  5. Card information is collected from the card holder and sent directly to the Gateway using the SDK method provided.
  6. A success / fail message is returned to the app in the appropriate callback method.
  7. The mobile app requests the merchant server check for 3DS enrollment using the Session Id containing the new card details.
  8. The merchant service calls Check 3DS Enrollment on the Gateway, including the redirect URL that will be used during the 3DS operation.
  9. An enrollment status message is returned to the merchant service, including HTML needed in the mobile SDK web view. (There are 2 methods of generating this initial 3DS page. For simplicity, we are illustrating a solution using pageGenerationMode = 'SIMPLE')
  10. The enrollment status and HTML is then returned to the mobile app.
  11. If enrolled, the mobile app passes the HTML (and an optional page title) to the SDK-provided 3DS web view, where the card holder carries out authentication with their Issuer. If not enrolled, skip to step 13.
  12. After authentication, the Issuer redirects response data to a Merchant Redirect Page. That page process this data and passes back the full acsResult JSON payload to the app using a custom URL scheme.
  13. The app then requests to complete the transaction by sending the 3DSecureId to the merchant service.
  14. The merchant service performs the appropriate transaction operation with the Gateway.
  15. The Gateway returns the summary of the transaction attempt to the merchant service.
  16. The success / fail status is returned to the mobile app.

Configuration

To support 3-D Secure 1.0 transactions, the Gateway Android SDK provides an activity you may include in your app to help display HTML content and handle web-page redirects. You must first add the activity to your AndroidManifest.xml file:

<activity
    android:name="com.mastercard.gateway.android.sdk.Gateway3DSecureActivity"
    android:label="@string/gateway_3d_secure_authentication" />

Implementation

There are 2 options for implementing the custom activity into your app.
*Refer to the Basic Transaction Lifecycle wiki page for information on how to collect card information with the SDK.

Option 1

After checking if the card is enrolled in 3DS, you should provide the activity with the HTML returned in the 3DSecure.authenticationRedirect.simple.htmlBodyContent field. You may also optionally provide a custom title to display in the toolbar:

Intent intent = new Intent(this, Gateway3DSecureActivity.class);
intent.putExtra(Gateway3DSecureActivity.EXTRA_HTML, html);
intent.putExtra(Gateway3DSecureActivity.EXTRA_TITLE, title); // optional

startActivityForResult(intent, YOUR_3DS_REQUEST_CODE);

The authentication lifecycle will take place within the WebView contained in this activity and a status message (or error) will be returned to the calling activity. To capture this return data, you should override the onActivityResult() method within your activity:

@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
    if (requestCode == YOUR_3DS_REQUEST_CODE) {
        if (resultCode == Activity.RESULT_OK) {
            // check for error
            String errorMessage = data.getStringExtra(Gateway3DSecureActivity.EXTRA_ERROR);
            if (errorMessage != null) {
                // TODO handle 3DS error
                return;
            }

            // get the acs result
            String acsResultJson = data.getStringExtra(Gateway3DSecureActivity.EXTRA_ACS_RESULT);
            GatewayMap acsResult = new GatewayMap(acsResultJson);

            // TODO handle 3DS complete
        } else {
            // TODO handle 3DS cancel
        }
    } else {
        super.onActivityResult(requestCode, resultCode, data);
    }
}

Option 2

For added convenience, you may instead use the 2 static helper methods provided by the Gateway class to manage the lifecycle of the activity:

String html = "<html>HTML returned from Gateway Check 3DS Enrollment method</html>";
String title = "Title shown in toolbar"; // optional

Gateway.start3DSecureActivity(activity, html, title);

To simplify handling the callback lifecycle of the activity, you should also implement the Gateway3DSecureCallback interface and use the following handler method during onActivityResult():

public class YourActivity extends AppCompatActivity implements Gateway3DSecureCallback {

    @Override
    protected void onActivityResult(int requestCode, int resultCode, Intent data) {
        if (Gateway.handle3DSecureResult(requestCode, resultCode, data, this)) {
            return;
        }

        super.onActivityResult(requestCode, resultCode, data);
    }

    @Override
    public void on3DSecureComplete(GatewayMap acsResult) {
        // TODO handle 3DS complete
    }

    @Override
    public void on3DSecureCancel() {
        // TODO handle 3DS cancel
    }
}

Merchant Redirect Page

When 3-D Secure authentication completes, the Issuer's ACS will redirect the phone's browser to the URL provided during Check Enrollment Status. For apps using the Gateway SDK, this is expected to be a URL to a page hosted by your merchant service. That page should accept the PaRes data from the redirect and process it with the Gateway using the Process ACS Result method. The response data from this call should be placed in a mobile-specific redirect URL containing acsResult as a query parameter. The structure of that URL should be gatewaysdk://3dsecure?acsResult={full-ACS-Result-json}. Redirecting to this URL signals to the SDK that 3-D Secure authentication is complete and the result has been processed. The SDK will recognize the redirect and deliver the ACS result back to the app thru the appropriate callback method.

Clone this wiki locally