Fusion APIs that deal with retrieval of card information require the organization to be PCI DSS compliant. To avoid the burden of PCI compliance, Fusion introduces Card SDKs. By integrating these Card SDKs, the organizations can fetch sensitive card details like PAN, card CVV, and more.

Before you begin

Take care of the following prerequisites before you begin with SDK setup:

• Ensure you have a card.json file which contains configuration data necessary to set up the SDK. Contact Zeta in case if you haven't received the file.
• Fusion uses an authentication token to authenticate the SDK. To know how to generate an authentication token , see SDK Authentication.
• Minimum Android SDK version required: 19
• Minimum Java Runtime Environment (JRE) version required: 8

Getting Started with Android Card SDK

Follow the steps below to integrate SDK:

1. Add the SDK to your project or app.
2. Prepare the SDK setup.
3. Now the SDK setup is ready to begin with verifying the SDK.

Step 1: Adding the SDK

The Android SDK is compatible with apps supporting Android with version 4.4 to 4.4.4 or API level 19 and above. To add the SDK to your project, follow these steps:

1. Add the following rule to your project-level gradle file. This downloads the Maven repository which holds all the build artifacts and dependencies necessary for your project.

   Project build.gradle

   allprojects {
       repositories {
           ....
           maven {
               credentials  {
                   username = "<usename>"
                   password = "<password>"
               }
               url 'https://apollo-sdk.zetaapps.in/repository/maven-releases/'
               authentication {
                   basic(BasicAuthentication)
               }
           }
           maven {
               credentials  {
                   username = "<username>"
                   password = "<password>"
               }
               url 'https://apollo-sdk.zetaapps.in/repository/maven-snapshots/'
               authentication {
                   basic(BasicAuthentication)
               }
           }
           ....        
       }
   }

2. In your module app- level gradle file, add the following code snippet:

   App build.gradle  Expand source

   android {
       defaultConfig {
   	// Use this for debug build.
       multiDexEnabled true
       }
       compileOptions {
           sourceCompatibility JavaVersion.VERSION_1_8
           targetCompatibility JavaVersion.VERSION_1_8
       }
       kotlin_options = {
           jvmTarget = "1.8"
       }
       packagingOptions {
       // Include this if you face packing errors.
           exclude 'META-INF/library_release.kotlin_module'
           exclude 'META-INF/DEPENDENCIES'
       }
   }
   dependencies {
     implementation 'in.zeta.apollo:cards:<latest-version>'
   }
   configurations {
   // Include this if you are not using a j2v8 engine in your code. APK would inflate if we don't do this
       all*.exclude group: 'in.apollo.android', module: 'templating_engine'
       all*.exclude group: 'com.eclipsesource.j2v8', module: 'j2v8'
   }

   Following are the descriptions of different modules in app-level gradle code: 

   • multiDexEnabled: Optional. Add this for debugging the build if you overshoot the 64K methods ceiling.
     

   • compileOptions: Required. Add support for Java 8 language features.
     

   • packagingOptions: Optional. Add this only if you face packaging error.
     

   • dependencies: Required. Include Card SDK dependencies for the latest version.
     

Step 2: Setting up the SDK

Follow the steps below to set up the SDK: 

1. Adding the configuration file

A configuration file contains all the configurable properties necessary for activating the SDK. You should add the file to your project (app/src/main/assets/) to prepare your app to work with the SDK. You will receive the configuration file named card.json through email. If you haven't received the file, contact Zeta.

2. Creating the card SDK object

In the onCreate() method of your Application class, create a in.zeta.apollo.cards.CardsService instance.

 final CardsService cardsService = new CardsServiceBuilder(this).build();

3. Registering the SDK

Card SDK registration triggers the authentication of the SDK using a tenantAuthToken. Registering the Card SDK involves only two steps:

1. Create the authentication token (tenantAuthToken). To know how to generate an authentication token, see SDK Authentication.
2. Invoke a call to cardsService.registerSDK(tenantAuthToken) method.

On successful authentication of SDK, you can access the getCard and setPin APIs.

Please ensure to set a valid tenantAuthToken on every app launch inside the following onCreate() method of MyApplication class to get better performance.

public class MyApplication extends Application {

   @Override
   public void onCreate() {
       super.onCreate();
       cardsService.registerSDK(tenantAuthToken);
       .........
   }
}

Step 3: Verifying the SDK

After successful SDK setup, you can  validate the SDK using the following APIs:

• Fetch Card Details
• Set Card PIN
• Logout

Fetch Card Details

Fetch Card Details API enables you to retrieve card information. In this API call, you should pass the card identifier (cardID).

cardsService.getCard(cardID, listener)

Parameters descriptions:

• cardID: A unique identifier of the card whose details are to be fetched.
• listener: A callback listener for the API invocation.

A call to Fetch Card Details API returns the below output in the form of POJO object:

{
	"binRange": {
		"bin": "508645",
		"range": "32"
	},
	"cardDetails": {
		"nameValuePairs": {
			"cardID": "f51c7421-xxxx-xxxx-8b69-64120332ddc8",
			"pan": "50864xxxxxx42345",
			"cvv": "XXX",
			"expiry": "1224",
			"isVirtual": false,
			"createdAt": "2020-01-06T19:16:28.656Z[UTC]"
		}
	},
	"cardStatus": "ENABLED",
	"cardType": "PHYSICAL",
	"crn": "********",
	"maskedPan": "508645-xxxxxx-2345",
	"sensitiveView": {
		"algo": "ECDH",
		"value": {
			"encryptedData": "<encrypted data>",
			"iv": "<iv for decryption>",
			"serverPublicKey": "<server public key>"
		}
	},
	"vectors": ["vector://ACCOUNTHOLDER/b1a70947-c88c-4fb1-810f-cc9a95c8a28c"]
}

Set Card PIN

Set Card PIN API enables you to perform set PIN operation on the card. In this API call, you should pass the card identifier ( cardID ) and a new card PIN requested (newPin ).

cardsService.setPin(newPin, cardID, listener)

Parameters descriptions:

• newPIN: A four digit security PIN to be associated with the card.
• cardID: A unique identifier of the card whose PIN are to be set.
• listener: A callback listener for the API invocation.

Logout

When a user logs out from the app, ensure that you clear all the session data. A default call to Logout method is important for the SDK to work properly in next login session.

A simple logout is available by using:

cardsService.logout()

Exceptions and error codes

This section explains the various exceptions and error codes thrown by Card SDK.

All the exceptions thrown will have the following fields in addition to the message:

1. code: Error code related to the response.
2. traceId: Trace ID which can be provided to Zeta support for identifying the root cause.
3. errorType: Type of error.

There are two kinds of exceptions that Card SDK can throw:

• SdkAuthException
• CardsSdkException

Below sample error response shows server-side error code and the message returned:

apollo@console$ in.zeta.apollo.sdkauth.SdkAuthException: The jwt token set seems invalid. Please check the parameters and signature to create the token
SdkAuthException.code: SDKAUTH_ERR_001

The following table lists the error codes, descriptions and possible solutions. If the issue persists, contact Zeta.