Switch to dark theme

Switch to light theme

APIs & Features

After you have successfully completed the steps from the previous section you are now ready to use an instance of CardsService to work with your customers card details.

This section covers the functionalities that the Cards SDK has on offer

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 card’s view if the user has not been asked for authentication already in the current app session.

Sample Screens

You also have a copy card number feature on the view to copy the card on the clipboard.

There are two methods offered for the card view. One method is a simple method with minimal features. The other one has lots of customizations. Sample calls for both of them are added below:

Switch Theme
Expand More
Copy
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
/**
Parameters:
1) activity invoking activity
2) cardId The form factor id of the card
3) listener The callback listener.
*/

MyApplication.getCardsService().getCardView(this,
 cardId,
 (view, exp) -> {
   runOnUiThread(() -> {
       // Check for null value of the exception and then render the view returned.
   });
});
Code Copied
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
/**
Parameters:
1) activity invoking activity
2) cardId The form factor id of the card
3) listener The callback listener.
4) cardsViewTemplateId The templateId for the template to be used. Set this to null if you want to use the default template.
5) jsonPayload The additional json payload we need to pass to the template. We can access this payload using the 'attrs' field in the template. Set null if you don't want to pass any interceptor.
6) cardsViewChangeInterceptor The additional interceptor we can pass. Set this to null if you don't want to pass the interceptor.
*/

MyApplication.getCardsService().getCardView(this,
 cardId,
 (view, exp) -> {
   runOnUiThread(() -> {
       // Check for null value of the exception and then render the view returned.
   });
}, null,
 "card_EN_UIVIEW",
 null,
 null);
Code Copied
Switch Theme
Expand More
Copy
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
// Note: You can ignore optional params for simple integration.
getInstance().getCardView(this,
   cardId,
   object: CardsService.GetViewListener {
       override fun done(view: View?, exp: Throwable?) {
           // Check for null value of the exception and then render the view returned.
       }
   },
   state = "expanded", // (Optional) pass the state in which you want your card to be rendered.
   cardsViewTemplateId = "your_custom_template_id", // (Optional) pass any custom template id here
   jsonPayload = JsonObject(), // (Optional) pass json object with params that can be used to
   cardsViewChangeInterceptor = myInterceptor // (Optional) set this to intercept card view changing states
)
Code Copied

Features offered

  1. We can have custom templates for the card view. Based on the templateID, the cards SDK can render different templates. The template must have two states (expanded and collapsed).

Sample Screenshot for a custom card template below

  1. By default, the template receives the card details (card number, expiry and cvv) as the payload. We can also pass some additional payload which we may use in our template. This payload can be accessed in the template using the attrs attribute.
Switch Theme
Expand More
Copy
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
JsonObject jsonPayload = new JsonObject();
jsonPayload.addProperty("company_name", "Zeta-India");
jsonPayload.addProperty("background_image", "https://abc.png");

CardsService.getInstance().getCardView(
       this,
       cardId,
       (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();
           }
       },
       null,
       "card_EN_UIVIEW",
       jsonPayload,
       cardViewChangeInterceptor);
Code Copied
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
val jsonPayload = JsonObject()
jsonPayload.addProperty("company_name", "Zeta-India")
jsonPayload.addProperty("background_image", "https://abc.png")

getInstance().getCardView(
   this,
   cardId,
   object: CardsService.GetViewListener {
       override fun done(view: View?, exp: Throwable?) {
           if (view != null) {
               // render to view received from cards sdk here..
           } else if (exp != null) {
               Toast.makeText(this@MainActivity, exp.message, Toast.LENGTH_SHORT).show()
           }
       }
   },
   null,
   "card_EN_UIVIEW",
   jsonPayload,
   cardViewChangeInterceptor)
Code Copied

Sample Payload that can be used in the template:

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 the additional payload can be used 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

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

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
Switch Theme
Expand More
Copy
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
getInstance().getSuperPinForResource(activity, resourceId,
   object: CardsService.GetSuperPinListener {
       override fun done(superPin: SuperPin?, exp: Throwable?) {
           if(exp != null) {
               // Exception in getting the super pin
           } else {
               // Super pin fetched successfully
           }
       }
   })
Code Copied

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.

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
Switch Theme
Expand More
Copy
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
getInstance().getSuperPin(activity,
   object: CardsService.GetSuperPinListener {
       override fun done(superPin: SuperPin?, exp: Throwable?) {
           if(exp != null) {
               // Exception in getting the super pin
           } else {
               // Super pin fetched successfully
           }
       }
   })
Code Copied
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.

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
Switch Theme
Expand More
Copy
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
CardsService.getInstance().getSuperPinForResourceUI(activity, resourceId,
   object: CardsService.GetSuperPinListener {
       override fun done(superPin: SuperPin?, exp: Throwable?) {
           if(exp != null) {
               // Exception in getting the super pin
           } else {
               // Super pin fetched successfully
           }
       }
   })
Code Copied

Sample response

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.

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
Switch Theme
Expand More
Copy
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
CardsService.getInstance().getSuperPinUI(activity,
   object: CardsService.GetSuperPinListener {
       override fun done(superPin: SuperPin?, exp: Throwable?) {
           if(exp != null) {
               // Exception in getting the super pin
           } else {
               // Super pin fetched successfully
           }
       }
   })
Code Copied

Sample response

Set Static PIN UI

Cards SDK also 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 and equality. Upon authentication, the PIN is stored in an encrypted store.

Here is the code snippet for the same.

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
Switch Theme
Expand More
Copy
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
CardsService.getInstance().setStaticPinWithUI(launchingActivity, cardId,
   object : CardsService.ResponseListener {
       override fun done(response: JsonObject?, exp: Throwable?) {
           if(exp == null) {
               // Pin set is a success
           } else {
               // Pin set is a failure
           }
       }
   })
Code Copied

Sample response

  • Set Static PIN UI - Initial

* Set Static PIN UI - Incorrect PIN

* Set Static PIN UI - Correct PIN

* Set Static PIN UI - Success

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. This feature sits behind user-authentication and requires authentication per launch of the app. The UI comprises of three input fields where we can enter:

  1. Old Static PIN
  2. New Static PIN
  3. 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:

  1. PIN lengths
  2. Correctness of Old Static PIN entered.
  3. Equality of the New Static PIN entered twice.

Here is the code snippet for the same.

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
Switch Theme
Expand More
Copy
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
CardsService.getInstance().changeStaticPinWithUI(launchingActivity, cardId,
   object: CardsService.ResponseListener {
       override fun done(response: JsonObject?, exp: Throwable?) {
           if (exp == null) {
               // Change Static PIN is a success
           } else {
               // Change Static PIN is a failure
           }
       }
   })
Code Copied

Sample response

  • Change Static PIN UI - Initial

  • Change Static PIN UI - New PIN Mismatch

  • Change Static PIN UI - Success

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.

Here is the code snippet for the same.

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
Switch Theme
Expand More
Copy
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
CardsService.getInstance().blockCard(cardId,
   object: CardsService.ResponseListener {
       override fun done(response: JsonObject?, exp: Throwable?) {
           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.

Here is the code snippet for the same.

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
Switch Theme
Expand More
Copy
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
CardsService.getInstance().blockCardUI(activity, cardId,
   object: CardsService.ResponseListener {
       override fun done(response: JsonObject?, exp: Throwable?) {
           if (exp == null) {
               // Block card is a success
           } else {
               // Block card is a failure
           }
       }
   })
Code Copied

Sample response

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.

Here is the code snippet for the same.

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
Switch Theme
Expand More
Copy
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
CardsService.getInstance().unblockCard(cardId,
   object: CardsService.ResponseListener {
       override fun done(response: JsonObject?, exp: Throwable?) {
           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.

Here is the code snippet for the same.

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
Switch Theme
Expand More
Copy
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
CardsService.getInstance().unblockCardUI(activity, cardId,
   object: CardsService.ResponseListener {
       override fun done(response: JsonObject?, exp: Throwable?) {
           if (exp == null) {
               // Unblock card is a success
           } else {
               // Unblock card is a failure
           }
       }
   })
Code Copied

Sample response

Copy Card Number

Card SDK provides the functionality to copy the un-masked card number. On success, it shows a toast message with the card number. Post that, you can paste the card number where-ever required.

Here is the code snippet for the same.

Switch Theme
Expand More
Copy
1
2
3
4
5
6
7
CardsService.getInstance().copyCardNumber(launchingActivity, cardId, (response, exp) -> {
  if(exp == null) {
      // Card number copied successfully
  } else {
      // Copying card number failed.
  }
});
Code Copied
Switch Theme
Expand More
Copy
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
CardsService.getInstance().copyCardNumber(launchingActivity, cardId,
   object: CardsService.ResponseListener {
       override fun done(response: JsonObject?, exp: Throwable?) {
           if (exp == null) {
               // Card number copied successfully
           } else {
               // Copying card number failed.
           }
       }
   })
Code Copied

Front Face Card UI

Cards SDK provides a full equipped front face card UI. This is a full UI for all the features provided by SDK cards. This UI supports multiple customisations and can be completely designed and changed from as per client requirement.

Here is a code snippet.

Switch Theme
Expand More
Copy
1
2
3
4
5
6
7
CardsService.getInstance().triggerFrontFaceUI(activity, (response, exp) -> {
   if(exp != null) {
       // Exception in rendering front face UI.
   } else {
       // Front Face UI rendering successful.
   }
});
Code Copied
Switch Theme
Expand More
Copy
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
getInstance().triggerFrontFaceUI(activity,
   object: CardsService.ResponseListener {
       override fun done(response: JsonObject?, exp: Throwable?) {
           if (exp != null) {
               // Exception in rendering front face UI.
           } else {
               // Front Face UI rendering successful.
           }
       }
   })
Code Copied

Here are some of the UI designs supported with Front Face Card UI:

Design 1

Design 2

Customised Super PIN View

We can have a custom view for the super pin displayed in expanded state. You can directly register the super pin view and cards SDK will handle the things like:

  1. Injecting the super pin to the layout.
  2. Updating the super pin whenever it expires.
  3. Informing the client to update the UI when the super pin expires.
  4. Hiding the super pin view in a collapsed state and showing it in an expanded state.

In order to use the custom super pin view, you need to register a super pin view holder with the cards SDK. This must be done in every session. The task of the super pin view holder is to provide the Super PIN view.

An example of super pin view holder is shown below:

Switch Theme
Expand More
Copy
1
2
3
4
5
6
7
8
9
public class ClientSuperPinViewHolder implements CardsService.SuperPinViewProvider {
    @NotNull
    @Override
    public CardsService.SuperPinView getInstance() {
        return new ClientSuperPinView();
    }
}

CardsService.getInstance().registerSuperPinViewProvider(new ClientSuperPinViewHolder());
Code Copied
Switch Theme
Expand More
Copy
1
2
3
4
5
6
7
8
9
class MyClientSuperPinViewHolder: ClientSuperPinViewHolder() {

   override fun getInstance(): CardsService.SuperPinView {
       return ClientSuperPinView()
   }
}


CardsService.getInstance().registerSuperPinViewProvider(MyClientSuperPinViewHolder())
Code Copied

The super pin view holder provides an instance of super pin view. A super pin view must implement 3 methods:

  1. getSuperPinPlaceHolder(superPinViewData) - The client must return a text-view where the super pin needs to be placed.
  2. configureSuperPinValidity(superPinViewData, validity) - This method is called by Cards SDK when the super pin is expired. The SDK will refresh the super pin on it’s own and trigger this method to inform the client to refresh the UI if needed. Under this, the client may refresh the timer that might be shown as part of the UI.
  3. getView(superPinViewData, context) - This method is called to get the parent view that needs to be placed.

While invoking the methods of super pin view, the SDK will also send superPinViewData. This data comprises card ID and template ID. The consumer may return a different UI based on the card ID, or based on the template ID. For instance, if you want to show a super pin on two different screens with different UI, you may achieve that using the superPinViewData.

An example of super pin view is shown below:

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
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
public class ClientSuperPinView implements CardsService.SuperPinView {
   private static final long PROGRESS_VIEW_INTERVAL_MS = 10;

   private View nativeView;
   private TextView pinLabel;
   private TextView pinView;
   private ProgressBar progressBar;
   private CountDownTimer codeHiderTimer;
   private Context context;

   @NotNull
   @Override
   public View getView(@NotNull SuperPinViewData superPinViewData, @NotNull Context context) {
       this.context = context;
       init();
       return nativeView;
   }

   @NotNull
   @Override
   public TextView getSuperPinPlaceHolder(@NotNull SuperPinViewData superPinViewData) {
       return pinView;
   }

   @Override
   public void configureSuperPinValidity(@NotNull SuperPinViewData superPinViewData, long validity) {
       showSuperCardPinTimer(validity);
   }

   private void showSuperCardPinTimer(long duration) {
       updateCodeHiderTimer(duration);
   }

   private void updateCodeHiderTimer(final long duration) {
       cancelCountdownTimer();
       codeHiderTimer = new CountDownTimer(duration, PROGRESS_VIEW_INTERVAL_MS) {
           @Override
           public void onTick(long timeUntilFinishedMs) {
               progressBar.setProgress((int)((1.0 + duration - timeUntilFinishedMs)/duration*100));
           }

           @Override
           public void onFinish() {

           }
       };
       codeHiderTimer.start();
   }

   private void init() {
       LayoutInflater layoutInflater = (LayoutInflater) context.getSystemService(Context.LAYOUT_INFLATER_SERVICE);
       nativeView = layoutInflater.inflate(R.layout.layout_client_super_pin_view, null);

       initViewIds();
   }

   private void initViewIds() {
       pinView = nativeView.findViewById(R.id.pin_value);
       progressBar = nativeView.findViewById(R.id.progress_bar);
       pinLabel = nativeView.findViewById(R.id.pin_label);
   }

   private void cancelCountdownTimer() {
       if (codeHiderTimer != null) {
           codeHiderTimer.cancel();
       }
   }
}
Code Copied
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
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
class ClientSuperPinView : CardsService.SuperPinView {
   private var nativeView: View? = null
   private var pinLabel: TextView? = null
   private var pinView: TextView? = null
   private var progressBar: ProgressBar? = null
   private var codeHiderTimer: CountDownTimer? = null
   private var context: Context? = null
  
   override fun getView(superPinViewData: SuperPinViewData, context: Context): View {
       this.context = context
       init()
       return nativeView!!
   }

   override fun getSuperPinPlaceHolder(superPinViewData: SuperPinViewData): TextView {
       return pinView!!
   }

   override fun configureSuperPinValidity(superPinViewData: SuperPinViewData, validity: Long) {
       showSuperCardPinTimer(validity)
   }

   private fun showSuperCardPinTimer(validity: Long) {
       updateCodeHiderTimer(validity)
   }

   private fun updateCodeHiderTimer(duration: Long) {
       cancelCountdownTimer()
       codeHiderTimer = object : CountDownTimer(duration, PROGRESS_VIEW_INTERVAL_MS) {
           override fun onTick(timeUntilFinishedMs: Long) {
               progressBar!!.progress =
                   ((1.0 + duration - timeUntilFinishedMs) / duration * 100).toInt()
           }

           override fun onFinish() {}
       }
       codeHiderTimer?.start()
   }

   private fun init() {
       val layoutInflater =
           context!!.getSystemService(Context.LAYOUT_INFLATER_SERVICE) as LayoutInflater
       nativeView = layoutInflater.inflate(R.layout.layout_client_super_pin_view, null)
       initViewIds()
       initTypeface()
   }

   private fun initViewIds() {
       pinView = nativeView!!.findViewById(R.id.pin_value)
       progressBar = nativeView!!.findViewById(R.id.progress_bar)
       pinLabel = nativeView!!.findViewById(R.id.pin_label)
   }

   private fun initTypeface() {
       pinView!!.typeface =
           Typeface.createFromAsset(context!!.assets, "fonts/IBMPlexSans-Bold.otf")
       pinLabel!!.typeface =
           Typeface.createFromAsset(context!!.assets, "fonts/IBMPlexSans-Regular.otf")
   }

   private fun cancelCountdownTimer() {
       if (codeHiderTimer != null) {
           codeHiderTimer!!.cancel()
       }
   }

   companion object {
       private const val PROGRESS_VIEW_INTERVAL_MS: Long = 10
   }
}
Code Copied

Sample Output

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. Here is a code snippet for the same.

Switch Theme
Expand More
Copy
1
2
3
CardsService.getInstance().logout(() -> {
   // The user is logged out …
});
Code Copied
Switch Theme
Expand More
Copy
1
2
3
4
getInstance().logout(object: CardsService.LogoutListener {
   override fun done() {
   }
})
Code Copied

Card Events

The Cards SDK publishes certain events. These events can be subscribed to by anyone. The following events are fired by Cards SDK:

  • 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.
  • BLOCK_CARD_SUCCESS - Fired when there is successful block action triggered.
  • BLOCK_CARD_FAILURE - Fired when block card action fails due to some reason.
  • UNBLOCK_CARD_SUCCESS - Fired when there is successful unblock action triggered.
  • UNBLOCK_CARD_FAILURE - Fired when unblock card action fails due to some reason.

Sample code to add or remove cards SDK listener:

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
Switch Theme
Expand More
Copy
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
val cardsEventListener = object: CardsService.CardsEventListener() {

   override fun onReceive(event: String?, exp: Throwable?) {
       Timber.d("Event Received from CARDS SDK: $event")
       //Perform the required functionality here..
       if (exp != null) {
           Timber.d("Error: " + exp.message)
       }
   }
}

// Use this to add the listener
getInstance().addCardsEventsListener(cardsEventListener)

// Use this to remove the listener
getInstance().removeCardsEventsListener(cardsEventListener)
Code Copied

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

Exceptions and error codes

All the exception 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)

There are two kinds of exception that cards SDK can throw

  1. SdkAuthException
  2. CardsSdkException

Note: All the exception classes extend the ApolloException

Following are the error codes and their meaning

  • SDKAUTH_ERR_001 - Authentication of tenantAuthToken fails. Potential reasons
    1. Token was signed with the incorrect private key
    2. The token does not have the configured claim
    3. 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 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.
Switch Theme
Expand More
Copy
1
2
[email protected]$ 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
Code Copied