Cardinal Mobile SDK Android Integration

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


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.


An authentication flow with Cardinal Mobile SDK



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



Default Values

Possible Values



Default Values

Possible Values

setEnvironment(CardinalEnvironment environment)

Sets the environment the SDK has to connect to


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


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.


  • 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


>=0 Milliseconds (Integer)

setChallengeTimeout(int challengeTimeout)

Sets the maximum amount of time (minutes) for challenge


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



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




Validates if the app has received consent to collect location data.



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.






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.


JWT Id - A unique identifier for this response JWT. This value is generated by Cardinal.


Issued At Time - This is a timestamp of when the JWT was created.


Issuer - The request JWT's iss field echoed back.


The unique session Id for the current user.


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