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:
|
|
|
|
|
|
Features offered
- 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
- 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.
|
|
|
|
Sample Payload that can be used in the template:
|
|
Example showing how the additional payload can be used in template:
|
|
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.
|
|
|
|
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 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.
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
Sample response
- Set Static PIN UI - Initial
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:
- 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 lengths
- Correctness of Old Static PIN entered.
- Equality of the New Static PIN entered twice.
Here is the code snippet for the same.
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
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:
- Injecting the super pin to the layout.
- Updating the super pin whenever it expires.
- Informing the client to update the UI when the super pin expires.
- 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:
|
|
|
|
The super pin view holder provides an instance of super pin view. A super pin view must implement 3 methods:
- getSuperPinPlaceHolder(superPinViewData) - The client must return a text-view where the super pin needs to be placed.
- 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.
- 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:
|
|
|
|
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.
|
|
|
|
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:
|
|
|
|
Sample logs:
|
|
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
- SdkAuthException
- 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
- 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 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.
|
|