The Cardinal Mobile SDK for Android makes it easy to activate and integrate Cardinal Consumer Authentication (CCA) into a mobile checkout flow.
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.gradlefile. 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.
Code Block |
---|
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:
Code Block |
---|
-keep class com.cardinalcommerce.dependencies.internal.bouncycastle.** -keep class com.cardinalcommerce.dependencies.internal.nimbusds.** |
Info |
---|
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.
Expand | |||||
---|---|---|---|---|---|
| |||||
|
Expand | |||||
---|---|---|---|---|---|
| |||||
|
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 | ||
---|---|---|---|---|---|
setEnvironment(CardinalEnvironment environment) | Sets the environment the SDK has to connect to |
|
| ||
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. |
|
| ||
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:
See setUiType(CardinalUiType uiType) above for more information on which uiType to use.
|
|
| ||
setProxyAddress(java.lang.String proxyAddress) | Sets the proxy the SDK has to connect to |
| 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) | 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. |
| 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()
.
Expand | |||||
---|---|---|---|---|---|
| |||||
|
Expand | |||||
---|---|---|---|---|---|
| |||||
|
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
Note |
---|
Required Field for identifying as an SDK transaction:
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:
Code Block | ||
---|---|---|
| ||
//Step 1: Implement this in Activity's onCreate() method CardinalChallengeObserver challengeObserver; challengeObserver = new CardinalChallengeObserver(this, new CardinalValidateReceiver() { @Override public void onValidated(Context context, ValidateResponse validateResponse, String s) { //your code here to handle onValidate result } }); //Step 2: Call cca_continue() to perform a challenge /** * Cca continue * * @param transactionId the transaction id * @param payload the payload * @param challengeObserver Instance of CardinalChallengeObserver * @throws InvalidInputException the invalid input exception * @throws JSONException the json exception * @throws UnsupportedEncodingException the unsupported encoding exception */ try { cardinal.cca_continue("[TRANSACTION ID ]", "[PAYLOAD]", challengeObserver); } catch (Exception e) { // Handle exception } |
Kotlin CCA Continue
Code Block | ||
---|---|---|
| ||
// Step 1: Implement this in Activity's onCreate() method val challengeObserver = CardinalChallengeObserver(this, object: CardinalValidateReceiver { override fun onValidated(context: Context?, validateResponse: ValidateResponse, responseString: String?) { when(validateResponse.getActionCode()!!) { CardinalActionCode.SUCCESS -> { // handle logic for Action code SUCCESS } CardinalActionCode.CANCEL -> { // handle logic for Action code CANCEL } CardinalActionCode.NOACTION -> { // handle logic for Action code NOACTION } CardinalActionCode.FAILURE -> { // handle logic for Action code FAILURE } CardinalActionCode.ERROR -> { // handle logic for Action code ERROR } CardinalActionCode.TIMEOUT -> { // handle logic for Action code TIMEOUT } } } }) // Step 2: Call cca_continue() to perform a challenge /** * Cca continue * @param transactionId the transaction id * @param payload the payload * @param challengeObserver Instance of CardinalChallengeObserver * @throws InvalidInputException the invalid input exception */ try { cardinal.cca_continue("transactionID", "payload", this.challengeObserver) } catch (e: Exception) { // Handle exception } |
In the snippet below are the required parameters for the CCA continue() method:
Code Block |
---|
public void cca_continue(String transactionId, String payload, CardinalChallengeObserver challengeObserver) throws InvalidInputExceptio |
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.
Note |
---|
Security Warning For security reasons, all JWT validation must be done on the server side. |
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 |
---|---|
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 |
Info |
---|
Each Claim key is case sensitive. |
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.
|