Android SDK Setup

A mobile SDK is available for integrating payer authentication services into mobile applications running on the Android platform.

Generate Your API Key

Create Credentials

Before you can implement payer authentication services, your business team must contact your acquirer and to establish the service. Your software development team should become familiar with the API fields and technical details of this service.

Creating a mobile application with the SDK implementation requires that you perform some preliminary procedures before starting the actual payer authentication implementation process. This section describes the processes involving JWTs.

API keys are required to create the JSON Web Token (JWT). For further information, contact customer support.

You receive an email with your username and a temporary password. Your username is in this format:

companyname_merchant name_contact name

For example:

mycompany_petairways_peter

Generate API Key

After you receive your credentials, log in to your JFrog account and update your temporary password. Complete these steps to generate your API key.

Log in to your JFrog account.
In the top-right of the JFrog Platform, select the Welcome drop-down menu and select Edit Profile
Enter your password and select Unlock
Under Authentication Settings, select Generate API Key

Update the Gradle Build Properties

In Android Studio, open the app directory (which can also be labeled Module: app) and open the build.gradle file. Edit the Gradle file located in the app directory. Add the contents shown in these example to the Gradle file.

repositories {   ...   maven {           url  "https://cardinalcommerceprod.jfrog.io/artifactory/android"           credentials {                   username Artifactory username                   password Artifactory user API Key            }    }}dependencies {    ...    //Cardinal Mobile SDK    implementation 2.5-1}

If your project uses Proguard, add these lines to the proguard-rules.pro file.

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

Configure the Android SDK

Get the instance of the Cardinal object by running the Cardinal.getInstance() process. Use the default configuration options. See these examples to understand how to run the Cardinal.configure() process.

For more details on configuration, refer to the configuration options table after the example.

private Cardinal cardinal = Cardinal.getInstance();@Overrideprotected void onCreate(Bundle savedInstanceState) {CardinalConfigurationParameters cardinalConfigurationParameters = new CardinalConfigurationParameters();        cardinalConfigurationParameters.setEnvironment(CardinalEnvironment.STAGING);        cardinalConfigurationParameters.setTimeout(8000);        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);        UiCustomization yourUICustomizationObject = new UiCustomization();cardinalConfigurationParameters.setUICustomization(yourUICustomizationObject);        cardinal.configure(this,cardinalConfigurationParameters);}

Android Configuration Options

Method	Description	Default Values
`setEnableDFSync(boolean enableDFSync)`	On setting true, `onSetupCompleted` is called after the collected device data is sent to the server.	`false`
`setEnableQuickAuth(boolean enableQuickAuth)`	Sets enable quick auth false.	`false`
`setEnvironment(CardinalEnvironment environment)`	Sets the environment to which the SDK must connect.	`CardinalEnvironment.PRODUCTION`
`setProxyAddress(java.lang.String proxyAddress)`	Sets the proxy to which the SDK must connect.	`" "`
`setRenderType(org.json.JSONArray renderType)`	Lists all user interface types that the device supports for displaying specific challenge user interfaces within the SDK.	`CardinalRenderType.OTP`, `CardinalRenderType.SINGLE_SELECT`, `CardinalRenderType.MULTI_SELECT`, `CardinalRenderType.OOB`, `CardinalRenderType.HTML`
`setTimeout(int timeout)`	Sets the maximum amount of time (in milliseconds) for all exchanges.	`8000`
`setUICustomization(UiCustomization uiCustomization)`	Sets `UICustomization`.	Device Default Values
`setUiType(CardinalUiType uiType)`	Sets all user interface types that the device supports for displaying specific challenge user interfaces within the SDK.	`CardinalUiType.BOTH`

Set Up the Initial Request

Run the Cardinal.init() process to:

Begin the communication process with Cardinal.
Authenticate your credentials (server JWT).
Complete the data collection process.

By the time the customer is ready to check out, all necessary preprocessing is complete.

Each time a user begins a mobile transaction, Cardinal assigns a unique identifier to the consumer session called a consumerSessionId. This consumerSessionId ensures that Cardinal matches the correct device data collection results to a request. calls this session identifier payerAuthEnrollService_referenceID. You must assign the value of the consumerSessionId field to the payerAuthEnrollService_referenceID field so that can also track the requests for each user session.

Study these code examples for completing the cardinal.init() process.

cardinal = Cardinal.getInstance();String serverJwt = "INSERT_YOUR_JWT_HERE";cardinal.init(serverJwt ,new CardinalInitService() {    /**    * You may have your Submit button disabled on page load. Once you are    * set up for CCA, you may then enable it. This will prevent users    * from submitting their order before CCA is ready.    */    @Override    public void onSetupCompleted(String consumerSessionId) {    }    /**    * If there was an error with set up, Cardinal will call this function    * with validate response and empty serverJWT    * @param validateResponse    * @param serverJwt will be an empty    */    @Override    public void onValidated(ValidateResponse validateResponse, String serverJwt) {    }});

Next Steps

See Implementing Payer Authentication with the SDK.

Was this page helpful?

Last published: September 29, 2026