The Cardinal Mobile SDK for Android makes it easy to activate and integrate Cardinal Consumer Authentication (CCA) into a mobile checkout flow.

Prerequisites

Within the Cardinal Mobile SDK ecosystem, authentication between the Merchant and Cardinal is handled via a JWT (JSON Web Token). To initialize the system for processing, a JWT must be generated server-side and passed into the first call in the chain.

Within the JWT, specify the Org Unit Id, API Key & API Identifier which are provided upon registration by an account manager at Cardinal.

For more information on generating a JWT, please see the Generating a Server JWT.

Cardinal’s Mobile SDK also requires Android API 21.

Flow

An authentication flow with Cardinal Mobile SDK

1 Prerequisites
2 Flow
3 Implementation

Implementation

Listed below are the seven steps to implement Cardinal’s Mobile SDK for Android.

Step 1 - Update the Gradle Build Properties to Integrate Cardinal Mobile SDK

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

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

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

-keep class com.cardinalcommerce.dependencies.internal.bouncycastle.**
-keep class com.cardinalcommerce.dependencies.internal.nimbusds.**

If you do not already have a Username and API Key for the JFrog Platform, please reach out to your CardinalCommerce Solution Engineer or account manager.

Step 2 - Configure Cardinal Mobile SDK

Get the instance of the Cardinal object by Cardinal.getInstance(). Listed below are code samples for Java and Kotlin.

private Cardinal cardinal = Cardinal.getInstance();
@Override
protected void onCreate(Bundle savedInstanceState) {

CardinalConfigurationParameters cardinalConfigurationParameters = new CardinalConfigurationParameters();
        cardinalConfigurationParameters.setEnvironment(CardinalEnvironment.STAGING);
        cardinalConfigurationParameters.setRequestTimeout(8000);
		cardinalConfigurationParameters.setChallengeTimeout(5);
        
		JSONArray rType = new JSONArray();
        rType.put(CardinalRenderType.OTP);
        rType.put(CardinalRenderType.SINGLE_SELECT);
        rType.put(CardinalRenderType.MULTI_SELECT);
        rType.put(CardinalRenderType.OOB);
        rType.put(CardinalRenderType.HTML);
        cardinalConfigurationParameters.setRenderType(rType);
        
        cardinalConfigurationParameters.setUiType(CardinalUiType.BOTH);
        cardinalConfigurationParameters.setLocationDataConsentGiven(true);
        UiCustomization yourUICustomizationObject = new UiCustomization();
        cardinalConfigurationParameters.setUICustomization(yourUICustomizationObject);

        cardinal.configure(this,cardinalConfigurationParameters);

}

Available Configurations

The SDK offers multiple configuration options, and anything not specified is set to default. Below are available configurations of this SDK.

Method	Description	Default Values	Possible Values

Method	Description	Default Values	Possible Values
setEnvironment(CardinalEnvironment environment)	Sets the environment the SDK has to connect to	`CardinalEnvironment.PRODUCTION`	`CardinalEnvironment.PRODUCTION` `CardinalEnvironment.STAGING`
setUiType(CardinalUiType uiType)	Sets all UI types that the device supports for displaying specific challenge user interfaces within the SDK. This setting interacts with renderType in important ways. See setRenderType(org.json.JSONArray renderType) below for more information.	`CardinalUiType.BOTH` It is recommended that you use `CardinalUiType.BOTH` to ensure your SDK integration can accept and render both the Native and HTML render types an issuer may use. Deviating from this default value could result in impacts to overall SDK transaction performance.	`CardinalUiType.BOTH` `CardinalUiType.Native` `CardinalUiType.HTML`
setRenderType(org.json.JSONArray renderType)	Sets render Lists all UI types that the device supports for displaying specific challenge user interfaces within the SDK. Note: When using `CardinalUiType.BOTH` or `CardinalUiType.HTML`, all renderType options must be set. When using `CardinalUiType.Native`, all renderType options except `CardinalRenderType.HTML` must be set. See setUiType(CardinalUiType uiType) above for more information on which uiType to use.	`CardinalRenderType.OTP` `CardinalRenderType.SINGLE_SELECT` `CardinalRenderType.MULTI_SELECT` `CardinalRenderType.OOB` `CardinalRenderType.HTML`	`CardinalRenderType.OTP` `CardinalRenderType.SINGLE_SELECT` `CardinalRenderType.MULTI_SELECT` `CardinalRenderType.OOB` `CardinalRenderType.HTML`
setProxyAddress(java.lang.String proxyAddress)	Sets the proxy the SDK has to connect to	`""` (empty string)	String Value
setRequestTimeout(int requestTimeout)	Sets the maximum amount of time (milliseconds) for all exchanges	8000	>=0 Milliseconds (Integer)
setChallengeTimeout(int challengeTimeout)	Sets the maximum amount of time (minutes) for challenge	5	>=5 minutes (Integer)
setUICustomization(UiCustomization UI Customization)	Sets UICustomization	Device Default Values	See article: Challenge User InterfaceCustomization Android
setEnableDFSync(boolean enableDFSync)	On setting true, onSetupCompleted in step 4, will be called after device data collected is sent to the server	true	Boolean
setThreeDSRequestorAppURL(String threeDSRequestorAppURL)	The setThreeDSRequestorAppURL method may set the 3DS Requestor App URL. If the app sets the URL, then the SDK shall pass the URL to the server.	`""` (empty string)	String Value
setEnableLogging(boolean enableEventLogging)	Enable cardinal logging	true	Boolean
setLocationDataConsentGiven()	Validates if the app has received consent to collect location data.	false	Boolean

Step 3- Call Cardinal.init

Calling Cardinal.init() will begin the communication process to ensure user experience is seamless, by authenticating your credentials (serverJwt) and completing the data collection process. By the time they are ready to checkout, all necessary pre-processing will be completed. Use the code snippet below for completing the Cardinal.init().

Step 4 - Create Lookup Request and Response

Create an API call to your backend server in order to send a Lookup Request (cmpi_lookup) to Cardinal's Centinel platform for initiating the Consumer Authentication transaction. The Centinel platform manages all of the routing and connectivity, as well as the rules engine for all of the various 3-D Secure protocols and versions. Please follow the Getting Started and Lookup Request/Response sections for completing your backend integration: Cardinal (cmpi) Messages

Required Field for identifying as an SDK transaction:

<DeviceChannel>SDK</DeviceChannel>
<DFReferenceId>ReferenceId</DFReferenceId>

ReferenceId is consumerSessionId returned on init completion, if no referenceID is passed in serverJwt. Else you can use that referenceID as DFReferenceId.

Step 5 - Validate CMPI Lookup Response to Create an Authentication Session

Check the CMPI_Lookup_Response for the following fields:

ThreeDSVersion = 2.X ( 2.0, 2.1, etc)
Enrolled = Y
PAResStatus = C
- If the PAResStatus is not C then you do not need to create an Authentication Session.

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

To display the challenge screen, use the following parameters for ccacontinue():

String: transactionId
String: payload
CardinalChallengeObserver: challengeObserver
- This is a new class that the App will have to instantiate in their onCreate() method and pass on the new cca_continue method.
- The CardinalChallengeObserver takes in two parameters:
  - FragmentActivity
  - CardinalValidateReceiver: this was previously passed in the old cca_continue method directly.

Java CCA Continue

In the snippet below are the steps for a Challenge response:

Kotlin CCA Continue

In the snippet below are the required parameters for the CCA continue() method:

Step 6 - JWT Validation

Once the response JWT arrives in the onValidated, send the response JWT to the merchant's 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.

For more in-depth information on JWT validation including code samples in a few languages, check out the JWT Validation page.

JWT Validation

This table includes cases sensitive claim keys and descriptions.

Claim	Description

Claim	Description
aud	Merchant jti Id - This is the 'jti' field from your request JWT echoed back. This field allows you to match up your request JWT with Cardinals response JWT.
jti	JWT Id - A unique identifier for this response JWT. This value is generated by Cardinal.
iat	Issued At Time - This is a timestamp of when the JWT was created.
iss	Issuer - The request JWT's iss field echoed back.
ConsumerSessionId	The unique session Id for the current user.
Payload	The response object for your request. This field will contain any actual state information on the transaction. This is the decoded data object that is passed into the `payments.validated` event as the first argument.

JWT Payload Example

Below is an example of the JSON content of a basic response JWT Payload where we are passing an object within the Payload claim:

Raw JWT Sample

Below is an example of the JSON content of a basic response JWT Payload where we are passing a string within the Payload claim. This would occur when the request JWT included a ObjectifyPayload flag set to false:

Stringified JWT Sample

Step 7 - Cleanup

The cleanup method is called after the transaction has completed. This clears Cardinal.java’s current instance so when Cardinal.getInstance() is called again, a new instance is created. This can be called from any location within your application.