Android Card SDK

Cards SDK comes packed with a rich feature set to solve for different card use cases.

With Cards SDK, fintech organisations can avoid the burden of spending several months on being compliant for card issuance, lifecycle management & operations which serve as a bottleneck. Now, you can focus on innovating your products with out-of-the-box security provided by SDK & launch financial products in a remarkable time frame.

Preparing the Environment

Ensure that the following requirements are met by your project :

• Latest version of Android Studio

• Target API level 19

• Physical device/ Emulator to run your app (Google play services should be installed & enabled on either)

• Java 8 or above

• Jitpack/ Maven repos

The current version is only secure for non-rooted devices.

Getting started

1. Accessing the SDK via App Center

Login to Apollo App Center

After you receive an email confirming that it’s been provisioned for you

Create a project

By providing the following details

• The name of your project
• Key - a unique identifier for your apps. This could be used to differentiate your preprod & prod apps.
• Repo Key - a unique identifier that will help you with setting up sharing access across environments
• Description - for your project
• Image - for your project

Allow the App Center a few minutes to in the background set up configurations, assets, bitbucket repositories, jenkins jobs and create your project for you. Once you see the success prompt, click go to project.

2. Registering the SDK

On the Dashboard you will be able to see a list of all SDKs. Go ahead and select Cards SDK from the list

Registration & application details

Fill out the following application details specific to your app to register your SDK as shown below :

• Android App name
• Bundle name
• Scheme

Click Register & Proceed!

Download configuration & asset files

On the left pane you will be able to see Cards SDK added after successful registration. This screen will summarise your projects setup so far. It also allows you to download your configuration & asset files.

Within the settings tab on the left pane of this project page, you will be able to access various settings for your project, applications that you will create, themes, currencies etc.

You will also be able to access the developer tools section through which you can go to your bitbucket repo & jenkins jobs.

Add dependencies to your project SDK

Add the following rule to your project level gradle file. This will download the Maven repository that holds all the build artefacts and dependencies necessary for your project. The code snippet looks like this :

Project level

gradle file

Switch Theme

Expand More

Copy

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27

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) } } .... } }

Code Copied

Additionally, insert the following code snippet to add dependency for Cards SDK to your application level gradle file. You will get to copy this code snippet too on the same page.

Application level

gradle file

Switch Theme

Expand More

Copy

1 2 3 4 5

dependencies { ............ implementation 'in.zeta.apollo:cards:<latest-version>' ............. }

Code Copied

Set themes, currencies etc. as per your project form App Center itself.

You will also get to copy theese code snippets with your username & password in the “How to integrate the SDK” section after selecting your SDK from the left pane as shown below :

3. Setup auth config

Head over to the Auth Config tab under your project name to set up authentication for your SDK and enter the following details shared with you by the Zeta Support team

• Domain
• Scope name
• Bank issuer ID (optional)
• Type
• Public key
• Sandbox ID (optional)
• Sandbox rule (optional)

Click on create to complete your auth config setup as shown below.

At this point, if you check your bitbucket repository from the developer tools section under settings, you will be able to see various templates, files etc. generated by the automated jenkins pipeline.

You can also further use this section to build and deploy templates after you’ve made changes & wish to deploy them.

Adding the cards SDK to your app

The following permissions need to be added in your Apps androidManifest.xml file to get the network state and take actions accordingly.

manifest.xml file

Manifest File

Switch Theme

Expand More

Copy

1 2 3

<uses-permission android:name="android.permission.INTERNET"/> <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" /> <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />

Code Copied

Add the cards.json file that you downloaded from App Center to your app/src/main/assets folder. The contents of a sample file are shown below.

Sample config file

Config.json File

Switch Theme

Expand More

Copy

1 2 3

<uses-permission android:name="android.permission.INTERNET"/> <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" /> <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />

Code Copied

Cards SDK is capable of allowing you to define the theme & layout that is in use. These can be edited remotely on the fly, so you don’t have to release a new build if you decide to change the way your views look. To deal with first time initializations it’s preferable to release a build along with a local copy of the files that define the views within your App.

You downloaded 2 files from the App Center, that are named as per the format below :

• scopeID.<id>.templates
• scopeID.<id>.theme_config

Add these files to app/src/main/assets/collections in your projects hierarchy. (Add the collections folder if you haven’t already).

To use a unified font across your app and give a good user experience, you can add your font files in the app/src/main/assets/fonts folder of your project.

Font files can be provided in either of the following formats :

• ttf
• otf

Once you’ve successfully added all the files, your project structure should look like this :

4. Instantiate & authenticate the SDK

After completing the steps mentioned in Preparing the environment & Adding the Cards SDK to your App, you are now ready to create an instance of CardsService to instantiate the SDK.

Add the following piece of code to your Apps main application class (create one if you haven’t already)

Main Application Class

main class

Switch Theme

Expand More

Copy

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33

private static final String MANROPE3_REGULAR_FONT_PATH = "fonts/Manrope3-Regular.otf"; private static final String MANROPE3_MEDIUM_FONT_PATH = "fonts/Manrope3-Medium.otf"; private static final String MANROPE3_SEMI_BOLD_FONT_PATH = "fonts/Manrope3-Semibold.otf"; private static final String MANROPE3_BOLD_FONT_PATH = "fonts/Manrope3-Bold.otf"; private static final Map<String, String> fontMap = new HashMap<>(); static { fontMap.put("Manrope3-Regular".toLowerCase(), MANROPE3_REGULAR_FONT_PATH); fontMap.put("Manrope3-Medium".toLowerCase(), MANROPE3_MEDIUM_FONT_PATH); fontMap.put("Manrope3-Semibold".toLowerCase(), MANROPE3_SEMI_BOLD_FONT_PATH); fontMap.put("Manrope3-Bold".toLowerCase(), MANROPE3_BOLD_FONT_PATH); } @Override public void onCreate() { super.onCreate(); setupCardsSdk(); } private void setupCardsSdk() { new CardsServiceBuilder(this) .setLoggingEnabled(true) .setAppDisplayName(R.string.app_name) .setUseDeviceLock(true) .setFontMap(fontMap) .build(); // Can get the CardsService instance once it is built. cardsService = CardsService.getInstance(); }

Code Copied

Descriptions for each of the builder methods are below :

setAppDisplayName

• Pass the String resource for your application name. We show this String over the device lock screen when the user is asked to provide authentication.
• Note : This is a necessary field

setUseDeviceLock

• Enable/Disable device lock when asking for user authentication.
• This is set as true by default.
• If set to false or the device does not already have a lock mechanism enabled, a custom PIN setup will commence when the setupSdk() method is

setFontMap

• Create a font map and set it to the builder. The Cards SDK will then use the fonts mentioned while rendering any of its views. The file names here refer to the files that you have inside your assets folder.
• Note: You can invoke CardsServiceBuilder(..) only once per app session. To get an instance of CardsService anywhere in your application, use the following code snippet.

Cards Service

cards service get instance

Switch Theme

Expand More

Copy

1	final CardsService cardsService = CardsService.getInstance();

Code Copied

The next step is to authenticate the SDK

• You can authenticate the Cards SDK by invoking the authenticateSdk() function. This function expects a JWT token referred to as tenantAuthToken in subsequent sections. The tenantAuthToken contains the account holder ID in the issuer’s domain as the “claim” of the JWT token.
• The tenantAuthToken needs to be computed in your backend as it needs access to sensitive information while token creation. The information used to generate the tenantAuthToken should never be compromised. More information on how to generate the tenantAuthToken can be found here.
• As and when the user logs in to the App, your App should fetch the tenantAuthToken from your backend service. This is a one time activity and can be clubbed with the login flow of the App.

Why authenticate Cards SDK

Once the user has logged in to the app, you already have a session for the logged in user. The reason why you need to separately authenticate the Cards SDK is for the issuers domain. Through the process of SDK Authentication you will authenticate your user in the issuers domain as a valid account holder ID.

Validity of tenantAuthToken

• The validity of the tenantAuthToken can be kept the same as the validity of the logged in user of the App.
• This is a one time activity and should be only done along with the login flow of the App.
• Once the App has fetched the tenantAuthToken it should initiate the SDK Authentication flow as suggested in the code snippet below :

Tenant auth token

authenticateSdk

Switch Theme

Expand More

Copy

1 2 3

final String tenantAuthToken = myBackendService.issueAuthToken(userInfo); CardsService.getInstance().authenticateSDK(tenantAuthToken, accountHolderId);

Code Copied

5. Setup SDK

This step triggers the actual setting up of the SDK. Once this step iscompleted, the SDK will initiate background sync of the card details of the user. One critical step is setting up the secureStore on the App. SecureStore refers to the encrypted storage which is behind the device lock or custom App PIN authentication step.

For secureStore, the SDK always prefers device lock over custom App pin authentication. Setting up a secureStore may require the user to provide device lock authentication. In case of custom app pin authentication, it may require the user to set up the app pin or provide the app pin.

Note : The first invocation of the setupSDK function call may require user intervention. Subsequent invocation will not require any user intervention.

Setup SDK

setupSdk call

Switch Theme

Expand More

Copy

1 2 3 4 5 6 7 8 9 10 11 12

@Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); setContentView(R.layout.activity_main); CardsService.SdkInitListener sdkInitListener = (success, exp) -> { // Handle the response here ... }; CardsService.getInstance().setupSDK(this, sdkInitListener, null); setupView(); }

Code Copied

When to call setupSdk()

• setUpSdk() call should be made on every launch of the App

• On first launch the setUpSdk() could be a part of the onboarding flow of the App i.e. The time when it is appropriate for the App to setup the device lock authentication. Nonetheless, it should always be called after the authenticateSdk() step has completed.

• On subsequent launches of the App, it should be called as early as possible. You can invoke it inside the onCreate() method of the launching activity of your App.

• Under the hood, the setupSDK function triggers the SDK to set up secure storage.

• On first launch, the secure storage is actually set up, while in the subsequent launches, since the setup is already done, it simply does nothing and returns success.

• Once the secure storage is set up, it triggers the SDK to sync the card details of the user in the background. Once the card details are fetched, the SDK needs to persist it in the secure storage for subsequent offline access. The SDK will do the “persist to secure storage” operation in the background only if the secure storage is “unlocked”. This is often the case during the first launch since it has been just set up and it is left unlocked. But in subsequent launches, this may not be the case. The SDK will never initiate unlocking the secure storage unless explicitly asked by the mobile app. For this purpose, the SdkInitListener will fire an event “Secure_Storage_Unlock_Required” to let the mobile app know of such a need. At this stage, the mobile app may, whenever it feels appropriate, invoke the SDK function - triggerSecureStorageUnlock. This will let the SDK trigger secure storage unlock. This will require user intervention. Post unlock, the SDK will persist the card details to the secure storage.

• Note: In most of the cases, it is sufficient to sync the cards details only during the first launch. Subsequent background sync results in no further data. But for scenarios where either the sync fails after the first launch or new card is added for the user, the background sync may result in newer data to be persisted to the secure storage.

sdkInitListener

The setupSDK function takes as input a listener which provides regular updates about the status of the SDK setup. Listen to the listener for success & once done, you can now access the Cards SDK APIs & features.

Cards SDK Features

After authentication and setup, you are now ready to use the cardsService to work with your users card details. The following functionalities are on offer :

1. Card View

About Card View API

• You can get the card view with the layout and styles configured specifically for your App with the Zeta platform. The default state of the view returned is the collapsed view which shows only the card PAN.
• On clicking the view, the user can toggle between the collapsed and the sensitive info states. User authentication is required for accessing the sensitive state of the Cards view if the user has not been asked for authentication already in the current App session.
• Sample screenshots (Collapsed view - image 1 & Sensitive view - image 2) :

Card view events

• EXPAND_CARD_VIEW_SUCCESS

Fired when the SDK is able to successfully render the card view in expanded state

• COLLAPSE_CARD_VIEW_SUCCESS

Fired when the SDK is able to successfully render the card view in collapsed state

• CHANGE_CARD_VIEW_STATE_FAILURE

Fired when there is an issue with changing the card view from Collapsed to Expanded state & vice-versa.

Card view features

• Copy details

The SDK shows a copy card number feature on the view to copy the card on the clipboard.

• Templates

The SDK has support for custom templates in the card view. Based on the templateId, the cards SDK can render different templates. The template must have 2 states (expanded & collapsed respectively)

Sample screenshot for a custom template with expiry label in Blue color :

• Themes

The SDK can provide any kind of design with a specific theme that can be configured remotely. For example, the font style for the card number can be configured differently for the collapsed & expanded state. This can be modified in the template itself. Similarly, you can change other labels and design of the card view in the template too.

Sample screenshots for a template with different font styles for card number :

• Passing custom attributes

By default, the template receives the card details (card number, expiry & CVV) as the payload. You can also pass some additional attributes in the payload which may be needed in the template.

This payload can be accessed in the template using the attrs attribute. Sample code follows :

Passing custom attributes

custom attributes

Switch Theme

Expand More

Copy

1 2 3 4 5 6 7 8 9 10 11 12

JsonObject jsonPayload = new JsonObject(); jsonPayload.addProperty("company_name", "Zeta-India"); jsonPayload.addProperty("background_image", "https://abc.png"); CardsService.getInstance().getCardView(this, cardId, "card_EN_UIVIEW", jsonPayload, cardViewChangeInterceptor, (view, exp) -> { if(view != null) { // render to view received from cards sdk here.. } else if (exp != null) { Toast.makeText(MainActivity.this, exp.getMessage(), Toast.LENGTH_SHORT).show(); } });

Code Copied

Sample code that can be used in the template :

Passing custom attributes

custom attributes details

Switch Theme

Expand More

Copy

1 2 3 4 5 6 7 8 9 10 11

{ card: { pan: "1111111111111111", expiry: "1221" cvv: "123" }, attrs: { company_name: “Zeta-India”, background_image: “https://abc.png” } }

Code Copied

Example showing how additional payload can be used in the template :

Custom attributes in Template

custom attributes in template

Switch Theme

Expand More

Copy

1 2 3 4 5 6 7 8

{ "companyTitle": { "label": "<%= attrs.company_name %>" }, "backgroundImage": { "url": "<%= attrs.background_image %>" } }

Code Copied

• Interceptor control

The get card view has a provision to set an interceptor. If the interceptor is set then, whenever the user triggers a state change, the interceptor will receive a callback. The state will only change when the callback is received from the interceptor.

Sample code below :

Interceptor control

Interceptor

Switch Theme

Expand More

Copy

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19

CardsService.CardsViewChangeInterceptor cardsViewChangeInterceptor = new CardsService.CardsViewChangeInterceptor() { InterceptDone interceptDone = null; @Override public void onIntercept(@NotNull @CardViewState String requestedState) { Timber.d("This action was intercepted with requested state: " + requestedState); /* Here, we can write the code we want to perform whenever the state change is triggered by the user. Once done, we can call the interceptDone.done() function to continue the regular flow. */ if (interceptDone != null) { interceptDone.done(); } } @Override public void setInterceptDone(@NotNull CardsService.CardsViewChangeInterceptor.InterceptDone interceptDone) { this.interceptDone = interceptDone; } };

Code Copied

Sample logs :

Interceptor control

Logs

Switch Theme

Expand More

Copy

1 2	This action was intercepted with requested state: expanded This action was intercepted with requested state: collapsed

Code Copied

2. Super PIN

About Super PIN

Super PIN is a time-synced based dynamic pin that changes every 2 minutes (configurable). The app can query for the Super PIN for different resources associated with the user.

User’s authentication is required to fetch the Super PIN.

Note: When using the Cipher SDK along with the Cards SDK, you need to initialize Cipher SDK before accessing the Super PIN for Cards SDK.

Super PIN API

• Note: Use this only when you are sure that users have a single resource associated with their accountHolderId’s

• The return value is a Super PIN along with the validity in milliseconds.

• Here is a code snippet on how you can fetch the Super PIN assuming a single resource :

Super PIN API

Single Resource request

Switch Theme

Expand More

Copy

1 2 3 4 5 6 7

CardsService.getInstance().getSuperPin(activity, (superPin, exp) -> { if(exp != null) { // Exception in getting the super pin } else { // Super pin fetched successfully } });

Code Copied

• Sample response :

Super PIN API

Single Resource response

Switch Theme

Expand More

Copy

1 2 3 4

{ "superPin": "<superPin>", "validTill": <validityMilliSecs> }

Code Copied

Super PIN UI

• Note: Use this only when you are sure that users have a single resource associated with their accountHolderId’s

• Cards SDK also provides a UI for fetching the Super PIN. The UI adds a translucent black background on the existing screen and shows a popup containing the Super PIN. The UI is in accordance with the theme with which the SDK has been configured.

• Here is a code snippet on how you can fetch the Super PIN UI assuming a single resource :

Super PIN UI

Single Resource request

Switch Theme

Expand More

Copy

1 2 3 4 5 6 7

CardsService.getInstance().getSuperPinUI(activity, (superPin, exp) -> { if(exp != null) { // Exception in getting the super pin } else { // Super pin fetched successfully } });

Code Copied

• Sample response :

• Customisation aspect

Theme changes : font & fontColors supported.

Super PIN for Resource

• The return value is a Super PIN along with the validity in milliseconds.

• Here is a code snippet on how you can fetch the Super PIN for a given resource :

Super PIN for resource

Multiple Resource request

Switch Theme

Expand More

Copy

1 2 3 4 5 6 7

CardsService.getInstance().getSuperPinForResource(activity, resourceId, (superPin, exp) -> { if(exp != null) { // Exception in getting the super pin } else { // Super pin fetched successfully } });

Code Copied

• Sample response :

Super PIN for resource

Multiple Resource response

Switch Theme

Expand More

Copy

1 2 3 4

{ "superPin": "<superPin>", "validTill": <validityMilliSecs> }

Code Copied

Super PIN UI for resource

• Cards SDK also provides a UI for fetching the Super PIN for a given resource. The UI adds a translucent black background on the existing screen and shows a popup containing the Super PIN. The UI is in accordance with the theme with which the SDK has been configured.

• Here is a code snippet on how you can fetch the Super PIN UI for a resource :

Super PIN for resource

Multiple Resource response

Switch Theme

Expand More

Copy

1 2 3 4 5 6 7

CardsService.getInstance().getSuperPinForResourceUI(activity, resourceId, (superPin, exp) -> { if(exp != null) { // Exception in getting the super pin } else { // Super pin fetched successfully } });

Code Copied

• Sample response :

• Customisation aspect

Theme changes : font & fontColors supported.

3. Static PIN

About Static PIN

Cards SDK provides functionality to allow you to set Static PIN for a given card form factor ID.

Set static PIN API

• Cards SDK exposes this API to expose the set static PIN for a given card form factor id. This API is behind user authentication and requires authentication per launch of the app.

• Code snippet :

Static PIN API

Static PIN API request

Switch Theme

Expand More

Copy

1 2 3 4 5 6 7

CardsService.getInstance().setStaticPin(launchingActivity, pin, cardId, (response, exp) -> { if(exp == null) { // Pin set is a success } else { // Pin set is a failure } });

Code Copied

Set static PIN UI

• Cards SDK provides a UI flow for setting the static PIN. The UI is in accordance with the theme with which the SDK has been configured. The UI allows the user to enter the static PIN twice. The entered PIN has validations for PIN length & equality. Upon authentication, the PIN is stored in an encrypted store.

• Code snippet for same :

Static PIN UI

Static PIN UI request

Switch Theme

Expand More

Copy

1 2 3 4 5 6 7

CardsService.getInstance().setStaticPinWithUI(launchingActivity, cardId, (response, exp) -> { if(exp == null) { // Pin set is a success } else { // Pin set is a failure } });

Code Copied

• Sample response

Change static PIN API

• Cards SDK exposes this API to enable the user to change the Static PIN for a given card form-factor. This API can only be used once the static PIN is set. It takes the Old Static PIN and the New Static PIN as input. It checks whether the Old PIN entered by the user is the same as the one earlier set by the user. On successfully providing the correct Old PIN and a valid new PIN, the new PIN is set for the given card form-factor.

• Here is the code snippet for the same :

Change PIN API

Change PIN API request

Switch Theme

Expand More

Copy

1 2 3 4 5 6 7

CardsService.getInstance().changeStaticPin(launchingActivity, oldPIN, newPIN, cardId, (response, exp) -> { if(exp == null) { // Change Static PIN is a success } else { // Change Static PIN is a failure } });

Code Copied

Change static PIN UI

• Cards SDK also provides a UI for changing the Static PIN given a card form-factor. The UI is in accordance with the theme with which the SDK has been configured. The UI comprises of three input fields where we can enter:

Old static PIN New static PIN Re-enter new static PIN

• Users can update the Static by providing the correct Old PIN and valid new PIN. The UI also provides validations for:

PIN length Correctness of Old Static PIN entered Equality of the new static PIN twice

• Code snippet :

Change PIN UI

Change PIN UI request

Switch Theme

Expand More

Copy

1 2 3 4 5 6 7

CardsService.getInstance().changeStaticPinWithUI(launchingActivity, cardId, (response, exp) -> { if(exp == null) { // Change Static PIN is a success } else { // Change Static PIN is a failure } });

Code Copied

• Sample response

• Customisation aspect

Theme changes : font & fontColors supported.

4. Block/ Unblock

About block card

Cards SDK offers the functionality to block the card temporarily incase the user desires. It allows the user to unblock the card in the future as and when required.

Block card API

• Cards SDK exposes this API to expose the Block Card functionality. The user can use this API to block the card temporarily. The user may unblock the card in future if required. This API is behind user authentication and requires authentication per launch of the app.

• Here is the code snippet for the same :

Block Card API

Block card API request

Switch Theme

Expand More

Copy

1 2 3 4 5 6 7

CardsService.getInstance().blockCard(cardId, (response, exp) -> { if(exp == null) { // Block card is a success } else { // Block card is a failure } });

Code Copied

Block card UI

• Cards SDK also provides a UI for blocking the card. The UI is in accordance with the theme with which the SDK has been configured. The UI adds a translucent black background on the existing screen and shows a snackbar containing the option to either cancel or Block the card. Upon authentication, the Block card API is triggered.

• Here is the code snippet for the same.

Block Card UI

Block card UI request

Switch Theme

Expand More

Copy

1 2 3 4 5 6 7

CardsService.getInstance().blockCardUI(launchingActivity, cardId, (response, exp) -> { if(exp == null) { // Block card is a success } else { // Block card is a failure } });

Code Copied

• Sample output

Unblock card API

• Cards SDK exposes this API to expose the Unblock Card functionality. The user can use this API to unblock the card which was blocked temporarily using the Block Card API. This API is behind user authentication and requires authentication per launch of the app.

• Here is the code snippet for the same.

Unblock Card API

Unblock card API request

Switch Theme

Expand More

Copy

1 2 3 4 5 6 7

CardsService.getInstance().unblockCard(cardId, (response, exp) -> { if(exp == null) { // Unblock card is a success } else { // Unblock card is a failure } });

Code Copied

Unblock card UI

• Cards SDK also provides a UI for unblocking the card. The UI is in accordance with the theme with which the SDK has been configured. The UI adds a translucent black background on the existing screen and shows a snackbar containing the option to either cancel or Unblock the card. Upon authentication, the Unblock card API is triggered.

• Here is the code snippet for the same :

Unblock Card UI

Unblock card UI request

Switch Theme

Expand More

Copy

1 2 3 4 5 6 7

CardsService.getInstance().unblockCardUI(launchingActivity, cardId, (response, exp) -> { if(exp == null) { // Unblock card is a success } else { // Unblock card is a failure } });

Code Copied

• Sample output :

• Customisation aspect

Theme changes : font & fontColors supported.

5. Hotlist

About hotlisting card

Cards SDK allows the user to hotlist the card in case the user wishes to do so in a scenario where the card is lost, damaged or stolen.

Hotlist card API

• Cards SDK exposes this API to expose the Hotlist Card functionality. The user can use this API to block the card permanently. This can be done in a case when the user has lost his card and wants to block the card permanently to prevent any misuse. This API is behind user authentication and requires authentication per launch of the app.

• Here is the code snippet for the same :

Hotlist Card API

Hotlist card API request

Switch Theme

Expand More

Copy

1 2 3 4 5 6 7

CardsService.getInstance().hotlistCard(cardId, (response, exp) -> { if(exp == null) { // Hotlist card is a success } else { // Hotlist card is a failure } });

Code Copied

Hotlist card UI

• Cards SDK also provides a UI for hotlisting the card. The UI is in accordance with the theme with which the SDK has been configured. The UI adds a translucent black background on the existing screen and shows a snackbar containing the option to either cancel or Hotlist the card. Upon authentication, the Hotlist card API is triggered.

• Here is the code snippet for the same :

Hotlist Card UI

Hotlist card UI request

Switch Theme

Expand More

Copy

1 2 3 4 5 6 7

CardsService.getInstance().hotlistCardUI(launchingActivity, cardId, (response, exp) -> { if(exp == null) { // Hotlist card is a success } else { // Hotlist card is a failure } });

Code Copied

• Sample output

• Customisation aspect

Theme changes : font & fontColors supported.

6. Activate

About activate card

The Cards SDK provides an API to activate the card using card sensitive information.

Activate card with sensitive information API

The card sensitive information includes:

• Card Number
• Expiry Date
• CVV

This API is behind user authentication and requires authentication per launch of the app. Here is the code snippet for the same.

Activate Card API

Sensitive information API request

Switch Theme

Expand More

Copy

1 2 3 4 5 6 7

CardsService.getInstance().activateCard(launchingActivity, cardNumber, expiryDate, cvv, (response, exp) -> { if(exp == null) { // Activate card is a success } else { // Activate card is a failure } });

Code Copied

Activate card with sensitive infromation UI

Cards SDK also provides a UI for activating the card. The UI is in accordance with the theme with which the SDK has been configured. The UI allows us to enter the three required fields and supports the following checks:

• Validation check on the length of the card number.
• Validation check on the length of the expiry date.
• Validation check on the length of the CVV number.
• Validation for the date entered in the expiry date field.

Here is the code snippet for the same:

Activate Card UI

Sensitive information API request

Switch Theme

Expand More

Copy

1 2 3 4 5 6 7

CardsService.getInstance().activateCardUI(launchingActivity, (response, exp) -> { if(exp == null) { // Activate card is a success } else { // Activate card is a failure } });

Code Copied

• Sample output

Card activation with card ID API (for proxy users only)

• Cards SDK provides the functionality to activate a card using Card ID. The API only requires the user to enter the Card ID. Using this, the API is able to activate the card. This API is behind user authentication and requires authentication per launch of the app.

• Here is the code snippet for the same :

Activate Card proxy API

Activate Card proxy API

Switch Theme

Expand More

Copy

1 2 3 4 5 6 7

CardsService.getInstance().activateCard(launchingActivity, cardId, (response, exp) -> { if(exp == null) { // Activate card is a success } else { // Activate card is a failure } });

Code Copied

Card activation with card ID UI (proxy users only)

Cards SDK also provides the UI for activating cards using Card ID. The UI comprises of a two fields:

• Card ID - Editable field that allows the user to enter the Card ID. Validations on Card ID length are added to this field.
• DNI Number - Non - Editable user property.

Here is the code snippet for the same.

Activate Card proxy UI

Activate Card proxy UI

Switch Theme

Expand More

Copy

1 2 3 4 5 6 7 8 9

UserPropertiesWithDNINumber userPropertiesWithDNINumber = new UserPropertiesWithDNINumber(); userPropertiesWithDNINumber.setDNINumber(dniNumber); CardsService.getInstance().activateCard(launchingActivity, userPropertiesWithDNINumber, (response, exp) -> { if(exp == null) { // Activate card is a success } else { // Activate card is a failure } });

Code Copied

• Sample output

• Customisation aspect

Theme changes : font & fontColors supported.

7. Get Card Data & sensitive data

About get card data

Cards SDK provides the functionality to get the un-masked card number.

Get card data API

• The cards SDK invokes the API which gives the card information in encrypted form. This information is then decrypted by Cards SDK to get the un-masked card number. This API is behind user authentication and requires authentication per launch of the app.

• Here is the code snippet for the same.

Get card data API

Card data API

Switch Theme

Expand More

Copy

1 2 3 4 5 6 7

CardsService.getInstance().getCardData(cardId, launchingActivity, (response, exp) -> { if(exp == null) { // Get Card Data is a success } else { // Get Card Data is a failure } });

Code Copied

• Sample response

Get card data API response

Card data API response

Switch Theme

Expand More

Copy

1 2 3

{ "cardPan": "<cardPan>" }

Code Copied

Get card sensitive data API

Cards SDK provides the functionality to get the Card Sensitive information. The cards SDK invokes the API which gives the card information in encrypted form. The information contains following information:

• Masked Card Number
• Expiry
• CVV
• CSV4
• Creation Date and Time

This API is behind user authentication and requires authentication per launch of the app.

Sample code snippet for the same :

Get card sensitive data API

get card sensitive data API request

Switch Theme

Expand More

Copy

1 2 3 4 5 6 7

CardsService.getInstance().getCardSensitiveData(cardId, launchingActivity, (response, exp) -> { if(exp == null) { // Get Card Sensitive Data is a success } else { // Get Card Sensitive Data is a failure } });

Code Copied

• Sample response

Get card sensitive data API

get card sensitive data API response

Switch Theme

Expand More

Copy

1 2 3 4 5 6 7 8

{ "maskedPan": "<maskedPan>", "expiry": "<expiry>", "cvv": "<cvv>", "csv4": "<csv4>", "isVirtual": isVirtual (boolean), "createdAt": "<createdAt>" }

Code Copied

• Customisation aspect

Theme changes : font & fontColors supported.

8. FIS static PIN

About get FIS static PIN

Cards SDK provides the functionality to get the FIS Static PIN for a specific card ID

get FIS static PIN API (proxy users only)

It takes card ID as input. This API is behind user authentication and requires authentication per launch of the app.

Sample code for the same :

Get FIS static PIN API

FIS static PIN API request

Switch Theme

Expand More

Copy

1 2 3 4 5 6 7

CardsService.getInstance().getFISStaticPin(cardId, launchingActivity, (response, exp) -> { if(exp == null) { // Get FIS Static PIN is a success } else { // Get FIS Static PIN is a failure } });

Code Copied

• Sample response

Get FIS static PIN API

FIS static PIN API response

Switch Theme

Expand More

Copy

1 2 3 4 5 6 7

CardsService.getInstance().getFISStaticPin(cardId, launchingActivity, (response, exp) -> { if(exp == null) { // Get FIS Static PIN is a success } else { // Get FIS Static PIN is a failure } });

Code Copied

get FIS static PIN UI (proxy users only])

Cards SDK also provides the UI to get the FIS Static PIN for a specific card ID. The UI adds a translucent black background on the existing screen and shows a snackbar containing the FIS Static PIN. The UI is in accordance with the theme with which the SDK has been configured.

Code snippet for same :

Get FIS static PIN UI

FIS static PIN UI request

Switch Theme

Expand More

Copy

1 2 3 4 5 6 7

CardsService.getInstance().getFISStaticPin(cardId, launchingActivity, (response, exp) -> { if(exp == null) { // Get FIS Static PIN is a success } else { // Get FIS Static PIN is a failure } });

Code Copied

• Sample output

• Customisation aspect

Theme changes : font & fontColors supported.

9. Logout

About Logout

Ensure that you logout the user by calling this API when you want to switch a user or the user logs out from the app. Failing to do this, the SDK may behave erratically later on.

Logout API

Code snippet for the same

Logout API

Logout API request

Switch Theme

Expand More

Copy

1 2 3

CardsService.getInstance().logout(() -> { // The user is logged out … });

Code Copied

Card Events

The Cards SDK publishes certain events that can be subscribed to by anyone.

• SETUP_SDK_SUCCESS - Fired when the SDK is setup successfully.

• SETUP_SDK_FAILURE - Fired when there is some failure in SDK setup.

• AUTHENTICATE_SDK_SUCCESS - Fired when the SDK is authenticated successfully.

• AUTHENTICATE_SDK_FAILURE - Fired when there is some failure in SDK Authentication.

• EXPAND_CARD_VIEW_SUCCESS - Fired when the SDK is able to successfully render Card View in Expanded State.

• COLLAPSE_CARD_VIEW_SUCCESS - Fired when the SDK is able to successfully render Card View in Collapsed State.

• CHANGE_CARD_VIEW_STATE_FAILURE - Fired when there is some error in changing the card view state from Expanded to Collapsed or vice-versa.

• LOGOUT_SDK_SUCCESS - Fired when the logout is successful.

• LOGOUT_SDK_FAILURE - Fired when there is some error in logout.

Sample code snippet to add or remove cards SDK listener :

Events

Card events

Switch Theme

Expand More

Copy

1 2 3 4 5 6 7 8 9 10 11 12 13

CardsService.CardsEventListener cardsEventListener = (event, exp) -> { Timber.d("Event Received from CARDS SDK: " + event); //Perform the required functionality here.. if (exp != null) { Timber.d("Error: " + exp.getMessage()); } }; // Use this to add the listener CardsService.getInstance().addCardsEventsListener(cardsEventListener); // Use this to remove the listener CardsService.getInstance().removeCardsEventsListener(cardsEventListener);

Code Copied

Sample logs :

Logs

Sample logs

Switch Theme

Expand More

Copy

1 2 3 4

Event Received from CARDS SDK: AUTHENTICATE_SDK_SUCCESS Event Received from CARDS SDK: SETUP_SDK_SUCCESS Event Received from CARDS SDK: COLLAPSE_CARD_VIEW_SUCCESS Event Received from CARDS SDK: EXPAND_CARD_VIEW_SUCCESS

Code Copied

Error codes & Exceptions

About exceptions & error codes

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

code - The error code related to the response traceId - The trace id which can be provided to Zeta support for identifying the root cause errorType - The type of error. (Added for verbosity)

Types of exceptions

There are 2 kinds of exceptions that the Cards SDK can throw

SdkAuthException CardsSdkException

Note: All the exception classes extend the ApolloException

Error codes & meaning with possible reasons

• SDKAUTH_ERR_001 : Triggered when authentication of tenantAuthToken fails.

Possible reasons : Token was signed with the incorrect private key The token does not have the configured claim Token is expired

• SDKAUTH_ERR_002 : Internal error caused while trying to authenticate the user. Contact support if the issue persists.

• CARDS_ERR_001 : Exception in hitting the cards API. Retry/ Contact support if the issue persists

• ERR_001 : Exception is thrown due to a bad request. This might be due to an invalid input or the SDK is not initialized properly.

• ERR_002 : Internal server error. Contact support if the issue persists

• ERR_003 : Internal SDK error. You can try logging out or contact support if the issue persists

• ERR_004 : Invalid response from the server. Contact Zeta for further assistance on this.

• ERR_005 : You are doing an operation that is not allowed.