V 2.2.2 : Cardinal Mobile SDK Android Documentation Overview

Overview

The Cardinal Mobile SDK for Android makes it easy for you to activate and integrate Cardinal Consumer Authentication (CCA) into your checkout flow. In just a few simple steps, you will be able to create a great user experience for your consumers, while utilizing the benefits of CCA.

Minimum Requirements

Requires Android API 19

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, you will need to specify your Org Unit Id, API Key & API Identifier. If you weren't given these values upon registration, please contact your account manager.

For more information on generating a JWT, please see the following instructions:

Generating a Server JWT

API Documentation

We have two implementation options:

1. Cardinal Implementation

This is a simple 6-Step process to get your application up and running 3DS 2.0 transactions, with the option to customize challenge screens using UI Customization.

Link to documentation: Cardinal implementation with optional UI Customization

2. Quick Auth Flow

This is a 7-Step process to get your application up and running our Quick Auth frictionless flow based on 3DS 1.0 transactions.

Link to documentation: Cardinal Mobile SDK Android Documentation for Quick Auth

Tutorial and Examples

A Quick Start guide is available to help you set up your build environment and get started with the Cardinal Mobile SDK by leading you through the creation of a simple application that connects to Cardinal. Within the download package, you will also find a demo app with full source code to help get you started.

Links to our demo application can be obtained by reaching out to your Client Manager or Implementation Manager.

Issues

Please report bugs, comments, or concerns to your Cardinal Implementation Manager

Frequently Asked Questions

Android Frequently Asked Questions

General FAQs

Does the SDK support JAVA/Kotlin?

Yes, CardinalMobileSDK supports both JAVA as well as Kotlin. Code snippets of each programming language can be found in the documentation.

What is the minimum supported version?

As of 2.2.4 Cardinal Mobile SDK - Android support API level 21 and up.

Does the SDK have any third party SDK/Library dependencies?

Yes, CardinalMobileSDK uses Nimbus JOSE+JWT for encryption/ decryption. These need to add in your Gradel dependencies.

What is the size of the 2.2.6-1 SDK Version ?

The downloaded framework file size is 2.2 MB. Once integrated with the app, it adds 800 KB to the total size.

Can I download the SDK into my project manually ?

You can also download the .aar file directly from Jfrog by navigating into the package and clicking cardinalmobilesdk-*.*.*-*.aar file under the Direct Downloads section as shown below.

Errors on updating the SDK to 2.1.4

Change the import statements as follows :

~~import com.cardinalcommerce.cardinalmobilesdk.models.response.CardinalActionCode~~
~~import com.cardinalcommerce.cardinalmobilesdk.models.response.ValidateResponse~~

~~import com.cardinalcommerce.shared.models.parameters.CardinalConfigurationParameters~~
~~import com.cardinalcommerce.shared.models.parameters.CardinalEnvironment~~
~~import com.cardinalcommerce.shared.models.parameters.CardinalRenderType~~
~~import com.cardinalcommerce.shared.models.parameters.CardinalUiType~~

to

mport com.cardinalcommerce.cardinalmobilesdk.enums.CardinalEnvironment
import com.cardinalcommerce.cardinalmobilesdk.enums.CardinalRenderType
import com.cardinalcommerce.cardinalmobilesdk.enums.CardinalUiType
import com.cardinalcommerce.cardinalmobilesdk.models.CardinalActionCode
import com.cardinalcommerce.cardinalmobilesdk.models.CardinalConfigurationParameters
import com.cardinalcommerce.cardinalmobilesdk.models.ValidateResponse

What are the rules added in ProGuard to support BouncyCastle and Nimbus?

Following rules added to ProGuard in the 2.2.3 release of the SDK

-keep class com.cardinalcommerce.dependencies.internal.bouncycastle.asn1.pkcs.PrivateKeyInfo
-keep class com.cardinalcommerce.dependencies.internal.bouncycastle.asn1.x509.SubjectPublicKeyInfo
-keep class com.cardinalcommerce.dependencies.internal.bouncycastle.asn1.ASN1ObjectIdentifier

-keep class com.cardinalcommerce.dependencies.internal.bouncycastle.jcajce.provider.asymmetric.**

-keep class com.cardinalcommerce.dependencies.internal.bouncycastle.openssl.PEMParser
-keep class com.cardinalcommerce.dependencies.internal.bouncycastle.jcajce.provider.symmetric
-keep class com.cardinalcommerce.dependencies.internal.bouncycastle.jcajce.provider.asymmetric
-keep class com.cardinalcommerce.dependencies.internal.bouncycastle.jcajce.provider.digest
-keep class com.cardinalcommerce.dependencies.internal.bouncycastle.jcajce.provider.keystore
-keep class com.cardinalcommerce.dependencies.internal.bouncycastle.jcajce.provider.drbg
-keep class com.cardinalcommerce.dependencies.internal.bouncycastle.jcajce.provider.symmetric.util.ClassUtil
-keep class com.cardinalcommerce.dependencies.internal.bouncycastle.jcajce.provider.util.AlgorithmProvider
-keep class com.cardinalcommerce.dependencies.internal.bouncycastle.jcajce.provider.util.AsymmetricKeyInfoConverter

-keep class com.cardinalcommerce.dependencies.internal.bouncycastle.pqc.asn1.PQCObjectIdentifiers
-keep class com.cardinalcommerce.dependencies.internal.bouncycastle.pqc.jcajce.provider.mceliece.McElieceCCA2KeyFactorySpi
-keep class com.cardinalcommerce.dependencies.internal.bouncycastle.pqc.jcajce.provider.mceliece.McElieceKeyFactorySpi
-keep class com.cardinalcommerce.dependencies.internal.bouncycastle.pqc.jcajce.provider.newhope.NHKeyFactorySpi
-keep class com.cardinalcommerce.dependencies.internal.bouncycastle.pqc.jcajce.provider.qtesla.QTESLAKeyFactorySpi
-keep class com.cardinalcommerce.dependencies.internal.bouncycastle.pqc.jcajce.provider.rainbow.RainbowKeyFactorySpi
-keep class com.cardinalcommerce.dependencies.internal.bouncycastle.pqc.jcajce.provider.sphincs.Sphincs256KeyFactorySpi
-keep class com.cardinalcommerce.dependencies.internal.bouncycastle.pqc.jcajce.provider.xmss.XMSSKeyFactorySpi
-keep class com.cardinalcommerce.dependencies.internal.bouncycastle.pqc.jcajce.provider.xmss.XMSSMTKeyFactorySpi


-keep class com.cardinalcommerce.dependencies.internal.bouncycastle.util.io.pem.PemObject
-keep class com.cardinalcommerce.dependencies.internal.bouncycastle.util.io.pem.PemReader

-keep class com.cardinalcommerce.dependencies.internal.nimbusds.jose.JOSEException
-keep class com.cardinalcommerce.dependencies.internal.nimbusds.jose.EncryptionMethod
-keep class com.cardinalcommerce.dependencies.internal.nimbusds.jose.JWEAlgorithm
-keep class com.cardinalcommerce.dependencies.internal.nimbusds.jose.JWECryptoParts
-keep class com.cardinalcommerce.dependencies.internal.nimbusds.jose.JWEHeader
-keep class com.cardinalcommerce.dependencies.internal.nimbusds.jose.JWSAlgorithm
-keep class com.cardinalcommerce.dependencies.internal.nimbusds.jose.JWSObject
-keep class com.cardinalcommerce.dependencies.internal.nimbusds.jose.JWSVerifier
-keep class com.cardinalcommerce.dependencies.internal.nimbusds.jose.KeyLengthException
-keep class com.cardinalcommerce.dependencies.internal.nimbusds.jose.Payload
-keep class com.cardinalcommerce.dependencies.internal.nimbusds.jose.JWEObject
-keep class com.cardinalcommerce.dependencies.internal.nimbusds.jose.crypto.RSAEncrypter

-keep class com.cardinalcommerce.dependencies.internal.nimbusds.jose.crypto.ECDSAVerifier
-keep class com.cardinalcommerce.dependencies.internal.nimbusds.jose.crypto.RSASSAVerifier
-keep class com.cardinalcommerce.dependencies.internal.nimbusds.jose.crypto.impl.ConcatKDF
-keep class com.cardinalcommerce.dependencies.internal.nimbusds.jose.crypto.impl.ECDH
-keep class com.cardinalcommerce.dependencies.internal.nimbusds.jose.crypto.impl.AAD
-keep class com.cardinalcommerce.dependencies.internal.nimbusds.jose.crypto.impl.AESCBC
-keep class com.cardinalcommerce.dependencies.internal.nimbusds.jose.crypto.impl.AESGCM
-keep class com.cardinalcommerce.dependencies.internal.nimbusds.jose.crypto.impl.AlgorithmSupportMessage
-keep class com.cardinalcommerce.dependencies.internal.nimbusds.jose.crypto.impl.AuthenticatedCipherText
-keep class com.cardinalcommerce.dependencies.internal.nimbusds.jose.crypto.impl.DeflateHelper
-keep class com.cardinalcommerce.dependencies.internal.nimbusds.jose.crypto.DirectEncrypter
-keep class com.cardinalcommerce.dependencies.internal.nimbusds.jose.crypto.DirectDecrypter

-keep class com.cardinalcommerce.dependencies.internal.nimbusds.jose.util.Base64URL
-keep class com.cardinalcommerce.dependencies.internal.nimbusds.jose.util.Base64
-keep class com.cardinalcommerce.dependencies.internal.nimbusds.jose.util.X509CertUtils
-keep class com.cardinalcommerce.dependencies.internal.nimbusds.jose.util.ByteUtils
-keep class com.cardinalcommerce.dependencies.internal.nimbusds.jose.util.Container

-keep class com.cardinalcommerce.dependencies.internal.nimbusds.jose.jwk.Curve
-keep class com.cardinalcommerce.dependencies.internal.nimbusds.jose.jwk.ECKey
-keep class com.cardinalcommerce.dependencies.internal.nimbusds.jose.jwk.JWK
-keep class com.cardinalcommerce.dependencies.internal.nimbusds.jose.jwk.PEMEncodedKeyParser

-keep class com.cardinalcommerce.dependencies.internal.nimbusds.jwt.EncryptedJWT
-keep class com.cardinalcommerce.dependencies.internal.nimbusds.jwt.JWTClaimsSet
-keep class com.cardinalcommerce.dependencies.internal.minidev.asm.FieldFilter

-ignorewarnings
-keep class com.cardinalcommerce.dependencies.internal.minidev.json.* {
    public private *;
}

Following rules added to ProGuard in the 2.2.2 release of the SDK

-keep class org.bouncycastle.asn1.pkcs.PrivateKeyInfo
-keep class org.bouncycastle.asn1.x509.SubjectPublicKeyInfo
-keep class org.bouncycastle.asn1.ASN1ObjectIdentifier

-keep class org.bouncycastle.jcajce.provider.asymmetric.**

-keep class org.bouncycastle.openssl.PEMParser
-keep class org.bouncycastle.jcajce.provider.symmetric
-keep class org.bouncycastle.jcajce.provider.asymmetric
-keep class org.bouncycastle.jcajce.provider.digest
-keep class org.bouncycastle.jcajce.provider.keystore
-keep class org.bouncycastle.jcajce.provider.drbg
-keep class org.bouncycastle.jcajce.provider.symmetric.util.ClassUtil
-keep class org.bouncycastle.jcajce.provider.util.AlgorithmProvider
-keep class org.bouncycastle.jcajce.provider.util.AsymmetricKeyInfoConverter

-keep class org.bouncycastle.pqc.asn1.PQCObjectIdentifiers
-keep class org.bouncycastle.pqc.jcajce.provider.mceliece.McElieceCCA2KeyFactorySpi
-keep class org.bouncycastle.pqc.jcajce.provider.mceliece.McElieceKeyFactorySpi
-keep class org.bouncycastle.pqc.jcajce.provider.newhope.NHKeyFactorySpi
-keep class org.bouncycastle.pqc.jcajce.provider.qtesla.QTESLAKeyFactorySpi
-keep class org.bouncycastle.pqc.jcajce.provider.rainbow.RainbowKeyFactorySpi
-keep class org.bouncycastle.pqc.jcajce.provider.sphincs.Sphincs256KeyFactorySpi
-keep class org.bouncycastle.pqc.jcajce.provider.xmss.XMSSKeyFactorySpi
-keep class org.bouncycastle.pqc.jcajce.provider.xmss.XMSSMTKeyFactorySpi


-keep class org.bouncycastle.util.io.pem.PemObject
-keep class org.bouncycastle.util.io.pem.PemReader

-keep class com.nimbusds.jose.JOSEException
-keep class com.nimbusds.jose.EncryptionMethod
-keep class com.nimbusds.jose.JWEAlgorithm
-keep class com.nimbusds.jose.JWECryptoParts
-keep class com.nimbusds.jose.JWEHeader
-keep class com.nimbusds.jose.JWSAlgorithm
-keep class com.nimbusds.jose.JWSObject
-keep class com.nimbusds.jose.JWSVerifier
-keep class com.nimbusds.jose.KeyLengthException
-keep class com.nimbusds.jose.Payload
-keep class com.nimbusds.jose.JWEObject
-keep class com.nimbusds.jose.crypto.RSAEncrypter

-keep class com.nimbusds.jose.crypto.ECDSAVerifier
-keep class com.nimbusds.jose.crypto.RSASSAVerifier
-keep class com.nimbusds.jose.crypto.impl.ConcatKDF
-keep class com.nimbusds.jose.crypto.impl.ECDH
-keep class com.nimbusds.jose.crypto.impl.AAD
-keep class com.nimbusds.jose.crypto.impl.AESCBC
-keep class com.nimbusds.jose.crypto.impl.AESGCM
-keep class com.nimbusds.jose.crypto.impl.AlgorithmSupportMessage
-keep class com.nimbusds.jose.crypto.impl.AuthenticatedCipherText
-keep class com.nimbusds.jose.crypto.impl.DeflateHelper
-keep class com.nimbusds.jose.crypto.DirectEncrypter
-keep class com.nimbusds.jose.crypto.DirectDecrypter

-keep class com.nimbusds.jose.util.Base64URL
-keep class com.nimbusds.jose.util.Base64
-keep class com.nimbusds.jose.util.X509CertUtils
-keep class com.nimbusds.jose.util.ByteUtils
-keep class com.nimbusds.jose.util.Container

-keep class com.nimbusds.jose.jwk.Curve
-keep class com.nimbusds.jose.jwk.ECKey
-keep class com.nimbusds.jose.jwk.JWK
-keep class com.nimbusds.jose.jwk.PEMEncodedKeyParser

-keep class com.nimbusds.jwt.EncryptedJWT
-keep class com.nimbusds.jwt.JWTClaimsSet
-keep class net.minidev.asm.FieldFilter
-keep class net.minidev.json.* { 
    public private *;
}

Why is the SDK size increased?

With the latest version of SDK, we removed integration on third party dependency through gradle imports, and this will increase SDK size but will decrease your entire app size when compared to older versions.

Why I'm seeing unresolved references to classes or interfaces warnings

We've added a few third-party libraries to the SDK along with few pro-guard rules, you can resolve those warnings by adding -ignorewarnings to proguard.pro file.

What all third-party libraries baked in the SDK?

The following jar files to our SDK.

• bcprov-jdk15on-1.62.jar

• jcip-annotations-1.0.jar

• json-smart-2.3.jar

• nimbus-jose-jwt-8.19.jar

Error ' Dependency failing: com.nimbusds:nimbus-jose-jwt:5.1 -> net.minidev:json-smart@[1.3.1,2.3] '

Root Cause:

Google started using nimbus library dependencies in its play services with version 4.3.0 ('com.google.gms:google-services:4.3.0') this is causing conflicts with anyone using nimbus library dependencies, google is using net.minidev:json-smart:1.3.1 where the latest version of nimbus library uses 2.3 this is causing conflict when merchants integrating CardinalMobile SDK with required dependencies ( 'com.nimbusds', name: 'nimbus-jose-jwt', version: '7.0.1', 'org.bouncycastle', name: 'bcprov-jdk15on', version: '1.61'). There are couple of ways to resolve this issue which are mentioned below.

Solution 1 :

When you face conflicts in using dependencies version you can configure the Android Studio project to use a specific version.

Add below code to use 2.3 version of json-smart (if you want to use 1.3.1 replace prefer value to 1.3.1)

components.all {
        allVariants {
            withDependencies { deps ->
                deps.each { dep ->
                    if (dep.group == 'net.minidev' && dep.name =='json-smart') {
                        dep.version {
                            prefer "2.3"
                        }
                        dep.because "resolving dependencies issue"
                    }
                }
            }
        }
    }

Solution 2:

The other solution is using an old version of google play service which doesn't use nimbus library which is 'com.google.gms:google-services:4.1.0'

Why I am seeing duplicate dependency for nimbus-jose-jwt and bcprov-jdk15on?

You will see these duplicate dependency errors if you are using Gradle import statements for nimbus and bouncy-castle, with the latest version of SDK we removed integration on third party dependency through Gradle imports and included these dependencies in SDK. Add the following script in gradle.build to exclude duplicate imports.

android {
  ...
    configurations {
        implementation.exclude module: 'nimbus-jose-jwt'
        implementation.exclude module: 'bcprov-jdk15on'
    }   
}
 
//With specific group name
android {
  ...
    configurations {
        implementation.exclude group: 'com.nimbusds', module: 'nimbus-jose-jwt'
        implementation.exclude group: 'org.bouncycastle', module: 'bcprov-jdk15on'
    }
}

Config FAQs

Can I test staging credentials in production environment of SDK?

No, if you are using staging credentials make sure SDK config is set to Staging Environment and switch back to Production Environment when moving to production. SDK is configured to the Production Environment by default.

Can I customize the Challenge Screens?

Yes, you can customize the certain aspect of the Challenge Screen by setting the UICustomization in SDK Config. See UI Customization v2.2.3 for details.

How do I set custom font for UICustomization?

You should verify the following:

Copy your .ttf file to “font” folder under “assets” in the main directory
1. If you don’t already have an assets file, right-click on the main directory | New | Android Resource Directory
  - Directory name: assets
  - Directory Type: assets
  - Source Set: main
  - Once the directory is created, right-click | New | Android Resource Directory |
  - Directory name: font
  - Directory Type: font
  - Source Set: main
Once you have verified you have your font in the right place, Pass in fontName as “font/font_name.ttf”
1. eg. buttonCustomization.setTextFontName(“font/walkwayblack.ttf”);

Can I get Setup Completion Handler called unsafe-only after Data Collection is complete?

Yes, you can set enableDFSync to true in SDK Config to get Setup Completion Handler called after Data Collection is complete. enableDFSync is set to false by default.

Setup/Init FAQs

Why do I get Invalid JWT Error?

JWT might be invalid if the credentials in the JWT like OrgUnitID, APIKey, APIIdentifiers are invalid or the JWT has expired. Also, make sure the credentials in the JWT point to the correct environment that SDK is set to in the config.

Will I notified if Device Data Collection fails?

By default, no. If you want Setup to be successful only after Device Data collection is complete, then enable DF Sync in the SDK Config.

What if the device doesn't have internet access during Setup call?

OnValidated handler of the Setup will be called with the corresponding error message.

ProcessBin FAQs

When does the ProcessBin unsafe-onComplete Handler doesn't get called?

If you start ProcessBin without successful completion of Setup/Init, then ProcessBin cannot be completed. Please check the console log for error details.

Continue FAQs

When can continue throw an error even without showing a challenge screen?

If the parameter you passed to the continue, like TransactionId or Payload is invalid then, continue will throw an error.

What should be passed as directoryServerID on continue?

You can use DirectoryServerID.VISA01 in V 2.1.3-X, this method is deprecated in the 2.1.4-X version of the SDK

Why is my Payload from Lookup response Invalid?

Make sure the ThreeDSVersoin of the lookup response matches with what SDK Supports. SDK does not support 1.0 Payload.

How can I test different UI in Challenge Screen?

After all initial setup, in continue pass a sample payload of various UI Types to test different UI in Challenge Screens. You can get the sample payload for various UI type from your Client Manager or Implementation Manager.

Does Failure ActionCode mean there was an error?

No. It means the authentication failed based on the data user provided.