Menu

3DS Mobile SDK (Android)

Note: Native mobile support is a new feature of 3DS2, for responses that are 3DS1 a webview is required for the challenge.

On this page

Get started

Before you begin integration, you must:

  1. Contact your Worldpay Relationship Manager to request the use of 3DS Mobile SDK and 3DS Flex
  2. Receive confirmation from your Worldpay Relationship Manager that your account has been created
  3. Have received your Cardinal SDK credentials (Bintray and API Key) from your Worldpay Support Team

SDK integration overview

This guide takes elements from Cardinal (Mobile SDK) and Worldpay (3DS Flex) documentation to provide step by step instructions for Android integration.

Note: This content is updated periodically.
If you have questions, or require additional support, please contact your Worldpay support team.

Access the Cardinal SDK for Android

Mobile SDK for Android

Access the SDK using the Bintray username and API Key provided to you by Worldpay.

Note: You must update the Gradle Build properties to integrate the Mobile SDK.

In Android Studio, open the app directory (which can also be labeled Module: app) and then open the build.gradle file. Make sure that you only edit the Gradle file that is located in the app directory. Add the following contents to the Gradle file:

Copied!
repositories {
    ...
    maven {
        url  "https://cardinalcommerceprod.jfrog.io/artifactory/android"
        credentials {
            username ''//Artifactory username
            password ''//Artifactory user API Key
        }
    }
}
dependencies {
    ...
    //Cardinal Mobile SDK
    implementation 'org.jfrog.cardinalcommerce.gradle:cardinalmobilesdk:2.2.5-4'
}

Note: If your project uses Proguard, add the following lines into proguard-rules.pro file:

  1. keep class com.cardinalcommerce.dependencies.internal.bouncycastle.
  2. keep class com.cardinalcommerce.dependencies.internal.nimbusds.

Get the Cardinal object (Cardinal.getInstance)

Obtain the instance of the cardinal object using Cardinal.getInstance(). Mobile SDK offers multiple configuration options for you (if not specified, everything is set to default). For more details: CardinalConfigurationOptions. Use the code snippet below for completing the cardinal.configure().

Note: Call method <getWarnings> to get the list of all the warnings for the particular device. Take further action based on the warnings found. List of warnings can be accessed as follows: Listwarnings = cardinal.getWarnings(); Contact your Worldpay Support Team for further details.

Setup the initial call

Setup the initial call

Call Cardinal.init() to begin the communication process with Cardinal. To ensure your user's experience is seamless Cardinal authenticate your credentials (serverJwt) and complete the data collection process. The data collection process includes DDC (Device Data Collection). All necessary pre-processing is complete by the time the shopper is ready to checkout. Use the code snippet below for completing the cardinal session setup.

Send the initial request (WPG)

In the initial request you must include the sessionId returned in the setup call response, and submit it as the dfReferenceId in your XML payment request. An authentication request is submitted to Cardinal Commerce to determine if a challenge is required.

Note: If you use Split authentication from Worldpay, you must send the request with <paymentDetails action="AUTHENTICATE">. Refer to theSplit authentication guidefor details. If you require further assistance, please contact your Worldpay Relationship Manager or Worldpay Support team.

Receive the response (WPG)

In the response you receive the dfReferenceId and payload. The dfReferenceId and payload must be sent from your server to the Mobile SDK on the shopper's mobile device. The Mobile SDK controls the process on the mobile device. The information in the payload determines whether the shopper is presented with a success screen, or the challenge screen.

Ensure you can handle the WPG first response

WPG handles the cmpi_lookup request. Check the CMPI_Lookup_Response for the following fields :

ThreeDSVersion = 2.X ( 2.0, 2.1, etc) Enrolled = Y PAResStatus = C

Upon validating the above fields, you will call cardinal.cca_continue to hand control to SDK for performing the challenge between the user and the issuing bank. Use the code snippet below for completing the cardinal.continue().

Copied!
cardinal.cca_continue is updated to not passing the hardcoded directoryServerID anymore cardinal.cca_continue("[TRANSACTION ID ]", "[PAYLOAD]", this, new CardinalValidateReceiver() { }); ```

3DS2 challenge

The shopper completes the 3DS2 authentication challenge. To complete the authorisation process you must send asecond call to WPG.

Note: You must include the WPG sessionId included in the first request as the sessionId to WPG not as the dfReferenceId.

Copied!
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE paymentService PUBLIC "-//WorldPay//DTD WorldPay PaymentService v1//EN""http://dtd.worldpay.com/paymentService_v1.dtd"&gt;
<paymentService version="1.4" merchantCode="YOUR_MERCHANT_CODE">
 <submit>
   <order orderCode="YOUR_ORDER_CODE">
     <info3DSecure>
       <completedAuthentication/>
     </info3DSecure>
     <session id="ssn42abcd023">
   </order>
 </submit>
</paymentService>

Second request (WPG)

Use this request for the ReturnUrl to trigger the second request (remember to also set the machine cookie on the Cookie HTTP header):

Copied!
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE paymentService PUBLIC "-//Worldpay//DTD Worldpay PaymentService v1//EN" "http://dtd.worldpay.com/paymentService_v1.dtd" >
<paymentService version="1.4" merchantCode="YOUR_MERCHANT_CODE">  
  <submit>
    <order orderCode="YOUR_ORDER_CODE"> <!--The order code supplied in the first request-->
      <info3DSecure>
        <completedAuthentication/>
      </info3DSecure>
      <session id="SESSION_ID"/> <!--The session id supplied in the first request-->
    </order>
  </submit>
</paymentService>

Be sure sure to include the same orderCode and session id you used in the initial request. You must also include the Machine Cookie received in the header of the first response.

You receive a Worldpay response with the payment outcome. <!--## 3DS2 challenge

The shopper completes the 3DS2 authentication challenge and the Mobile SDK sends back the sessionId. To complete the authorisation process you must send a second call. As with the first call, the sessionId is entered as the dfReferenceId.-->

For additional support, and to request a full app example, contact your Worldpay support team.

JWT validation

Once the response JWT arrives in the onValidated, you will need to send the response JWT to your backend for verification and consumption. We recommend that any values sent to 3rd parties are sourced from the response JWT after it has been properly validated.

Warning: For security reasons, all JWT validation must be done on the server side.