API Reference for Android
casan221saas
The following topics provide information about the classes, enums, and response beans of the Android SDK:
In the context of this CA solution, the term "accounts" covers both payment card accounts and bank accounts.
Classes
This section describes the classes provided by the SDK.
Class AuthenticationHandler
This AuthenticationHandler class provides methods that can be called by the business app or authenticator app. The app can use these methods to activate CA Strong authentication for a user’s accounts and to authenticate the user.
authenticateUsingConsent
Java Code Snippet
public class AuthenticationHandler {public static void initSALib(…) public AuthenticationHandler(…) public TransactionDetailsResponse getTransaction() public TransactionDetailsResponse getTransaction(…) public ArrayList<Authentication> getAllAuthenticationModes() public ArrayList<AuthenticationType> getEnabledAuthenticationTypes() public UpdateAuthenticationResponse updateAuthenticationType(…) public AuthenticationResponse authenticateUsingConsent(…) public AuthenticationResponse authenticateUsingUserPin(…) public CancelTransactionResponse cancelTransaction(…) public boolean isPinSetUp() public AccountActivationDetails verifyActivation(…) public AccountActivationDetails verifyActivation(…) public AccountsActivationDetails verifyActivation(…) public AccountsActivationDetails verifyActivation(…) public AccountDeletionResponse deleteAccount(…) public ActivationAcknowledgementResponse setPin(…) public List<ActivationAcknowledgementResponse> setPin(…) public ArrayList<AccountDetails> getAllEnrolledAccounts() public String[] getAllServiceURLs() public boolean setURL(…) public OTPResponse generateOTP(…) public ChangePinResponse changePin(…) public VerifyPinResponse verifyPin(…) public ProfileInfo getProfileInfo() public Boolean isDeviceJailBroken() public SSLPinningConfigResponse configureSSLPinning(SSLPinningConfigs sslPinningConfigs) } |
Constructor
AuthenticationHandler(Context activityContext) | Initializes Activity Context. |
AuthenticationHandler
Constructor of the class. It initializes the Activity context.
Code snippet
public AuthenticationHandler(Context activityContext) throws IllegalArgumentException |
Parameters
Parameter | Mandatory? | Description |
activityContext | Yes | Activity context. |
Return Value
AuthenticationHandler – Instance of the class.
Exceptions
Exception | Descripton |
IllegalArgumentException | This exception is thrown if activityContext is not an instance of android.app.Activity. |
initSALib
Initializes the Activity context, device token (with FCM registration ID), and device nickname.
Code snippet
public static void initSALib(Context activityContext, String fcmRegistrationId, String deviceNickName) |
Parameters
Parameter | Mandatory? | Description |
activityContext | Yes | Activity context. This activity context can be different from the activity context passed to the AuthenticationHandler constructor. |
fcmRegistrationId | Yes | FCM registration ID. |
deviceNickName | Yes | Device nickname. The user can be prompted to specify a device nickname when the SDK is initialized. Alternatively, the existing device nickname can be extracted and shown to the user, along with the option to edit the nickname. Note: The device nickname is used to track the device that has been used to track transactions and authentications conducted. |
Return Value
None.
Exceptions
None.
getTransaction (get latest pending transaction)
Gets the latest pending transaction for the accounts. Call this API when push notification is not used (or is not available) to initiate authentication for a transaction.
Call this API in a background thread.
Code snippet of getTransaction
public TransactionDetailsResponse getTransaction() |
Parameters
None.
Return Value
This method returns a TransactionDetailsResponse object, which contains the status and error code.
The status can be one of the following values:
- SUCCESS:Operation was successful. This means one of the accounts has the pending transactions.
- FAILURE:Operation failed.
If the status is FAILURE, then the response object will have one of the following error codes:
Error Code | Description | Action to Take |
ERROR_NETWORK_UNAVAILABLE | The device is not connected to the Internet. | Ensure that the Internet connection available and try again. |
ERROR_INVALID_AUTH_APP_ID | The Auth App Id is not present in database. | Ensure getAuthAppId method returns a value. If not, please contact the administrator. |
ERROR_NO_ACTIVE_ACCOUNTS | No active accounts are present. For example, when the existing accounts are locked. | Unenroll and reenroll the accounts. |
ERROR_SERVER_UNREACHABLE | Server is not reachable. Returns null or empty value in the response. | Check if the internet connection available and try again. |
ERROR_SERVER_INTERNAL | Server has returned an error. The credential_type not present in the response | Retry after some time or contact the administrator. |
ERROR_NO_TRANSACTION_AVAILABLE | There are no pending transactions. | Perform initAuth API call to get the transaction. |
ERROR_ACCOUNT_NOT_FOUND | Invalid account. | The user has no enrolled accounts. |
ERROR_PINNING_FAILURE | The SSL pinning has resulted in failure. | Valid certificate must be passed from the customer app to the SDK. |
Exceptions
None.
getTransaction (get a specified transaction)
Gets the pending transaction corresponding to a particular transaction ID. Call this API to initiate authentication for a transaction after the user taps the push notification received for the transaction.
Call this API in a background thread.
Code snippet
public TransactionDetailsResponse getTransaction(String transactionId, String accountId, String accountType) |
Parameters
Parameter | Mandatory? | Description |
transactionId | Yes | CA Strong Authentication transaction ID. |
accountId | Yes | Account ID. |
accountType | Yes | Account type. |
Return Value
This method returns a TransactionDetailsResponse object, which contains the status and error code.
The status can be one of the following values:
- SUCCESS:Operation was successful. This means one of the accounts has the pending transactions.
- FAILURE:Operation failed.
If the status is FAILURE, then the response object will have one of the following error codes:
Error Code | Description | Action to Take |
ERROR_NETWORK_UNAVAILABLE | The device is not connected to the Internet. | Ensure that the Internet connection available and try again. |
ERROR_SDK_INTERNAL | There might a JSONException. | Ensure mobile3ds.sqlite file has read and write permissions. If the issue still persists please contact the administrator. |
ERROR_INVALID_ARGUMENT | Incorrect details were passed. | Ensure the arguments that you pass are correct and not null. |
ERROR_INVALID_AUTH_APP_ID | The Auth App Id is not present in database. | Ensure getAuthAppId method returns a value. If not, please contact the administrator. |
ERROR_SERVER_UNREACHABLE | Server is not reachable. Returns null or empty value in the response. | Check if the internet connection available and try again. |
ERROR_SERVER_INTERNAL | Server has returned an error. The credential_type not present in the response | Retry after some time or contact the administrator. |
ERROR_NO_TRANSACTION_AVAILABLE | There are no pending transactions. | Perform initAuth API call to get the transaction. |
ERROR_ACCOUNT_NOT_FOUND | Invalid account. | The user has no enrolled accounts. |
ERROR_PINNING_FAILURE | The SSL pinning has resulted in failure. | Valid certificate must be passed from the customer app to the SDK. |
Exception
None.
getAllAuthenticationModes
Gets all available (SDK supported) authentication types. Call this API in any scenario in which the app needs to know which authentication types are supported by the SDK on this user's mobile.
Code snippet
public ArrayList<Authentication> getAllAuthenticationModes() |
Parameters
None.
Return Value
ArrayList<Authentication>.
See Authentication for more information.
Exception
None.
getEnabledAuthenticationTypes
Gets all enabled authentication types. Call this API in any scenario in which the app needs to know which authentication types are enabled by the user and are (therefore) available for use during authentication.
Code snippet
public ArrayList<AuthenticationType> getEnabledAuthenticationTypes() |
Parameters
None.
Return Value
ArrayList<AuthenticationType>.
See AuthenticationType for more information.
Exception
None.
updateAuthenticationType
Updates a specific Authentication object in the app database. Call this API to apply (that is, persist) the user's action of enabling or disabling a specific authentication type.
Before calling the updateAuthenticationType API, call the verifyPin API to ensure that the user has submitted the correct PIN.
Call this API in a background thread.
Code snippet
public UpdateAuthenticationResponse updateAuthenticationType(Authentication authentication, String userPin) |
Parameters
Parameter | Mandatory? | Description |
authentication | Yes | An Authentication object. |
userPin | Yes | User PIN. |
Return Value
This method returns an UpdateAuthenticationResponse object, which contains the status and error code.
The status can be one of the following values:
- SUCCESS:Operation was successful.
- FAILURE:Operation failed.
If the status is FAILURE, then one of the following error codes is returned:
Error Code | Description | Action to Take |
ERROR_INVALID_AUTH_APP_ID | The Auth App Id is not present in database. | Ensure getAuthAppId method returns a value. If not, please contact the administrator. |
ERROR_NO_BIOMETRIC_AVAILABLE | Biometric authentication is not enabled on this device. | Ensure the BIOMETRIC-related options are enabled on your device. |
ERROR_INVALID_PIN | Invalid PIN. | Ensure PIN is numeric and the length is in between 4 to 10 digits. |
ERROR_INTERNAL_READWRITE | The query execution failed due to insufficient permissions. | Ensure mobile3ds.sqlite file has read and write permissions. |
ERROR_OPERATION_NOT_ALLOWED | User is trying to disable an authentication type (biometric) that is already disabled. | Ensure the authentication is enabled. Call getEnabledAuthenticationTypes method and verify the enabled authentication types. |
See UpdateAuthenticationResponse for more information.
Exception
None.
authenticateUsingConsent
Applies device authentication.
Use this API when you do not want to apply user authentication (that is, PIN or biometric authentication) for a low-risk transaction. The use of device authentication ensures that the mobile device on which CA Strong Authentication has been activated for the user’s account is used in the authentication process. For more information about device authentication, see CA Strong Authentication SDKs.
Call this API in a background thread.
Code snippet
public AuthenticationResponse authenticateUsingConsent(TransactionDetailsResponse transactionDetailsResponse) |
Parameters
Parameter | Mandatory? | Description |
transactionDetailsResponse | Yes | TransactionDetailsResponse object. |
Return Value
This method returns an AuthenticationResponse object, which contains the status and error code.
The status can be one of the following values:
- SUCCESS:Operation was successful.
- FAILURE:Operation failed.
If the status is FAILURE, then one of the following error codes is returned
Error Code | Description | Action to Take |
ERROR_INVALID_PIN | Invalid PIN. | Ensure PIN is numeric and the length is in between 4 to 10 digits. |
ERROR_NO_TRANSACTION_AVAILABLE | There are no pending transactions. | Perform initAuth API call to get the transaction. |
See AuthenticationResponse for more information.
Exception
None.
authenticateUsingUserPin
Applies user authentication by using the user PIN.
This is one of the APIs for applying user authentication. For more information about user authentication, see CA Strong Authentication SDKs.
Call this API in a background thread.
Code snippet
public AuthenticationResponse authenticateUsingUserPin(TransactionDetailsResponse transactionDetailsResponse, String pin) |
Parameters
Parameter | Mandatory? | Description |
transactionDetailsResponse | Yes | TransactionDetailsResponse object. |
Pin | Yes | User PIN. |
Return Value
This method returns an AuthenticationResponse object, which contains the status and error code.
The status can be one of the following values:
- SUCCESS:Operation was successful.
- FAILURE:Operation failed.
If the status is FAILURE, then one of the following error codes is returned:
Error Code | Description | Action to Take |
ERROR_NETWORK_UNAVAILABLE | The device is not connected to the Internet. | Ensure that the Internet connection available and try again. |
ERROR_INVALID_ARGUMENT | Incorrect details were passed | Ensure the arguments that you pass are correct and not null. |
ERROR_SERVER_UNREACHABLE | Server is unreachable. | Ensure that you have internet connection available and try again. |
ERROR_ACCOUNT_NOT_FOUND | Invalid account. | Ensure the account is valid and present. Unenroll and then reenroll accounts. |
ERROR_SDK_INTERNAL | SDK has returned an error. | Ensure mobile3ds.sqlite file has read and write permissions. If the issue still persists please contact the administrator. |
ERROR_INVALID_AUTHENTICATION_TYPE | Invalid AuthenticationType object present in the request. | Ensure that the credential_type parameter is present in the passed object. |
ERROR_INVALID_AUTH_APP_ID | InvaIid Auth app ID. | Ensure the app ID is correct. |
ERROR_INVALID_PIN | Invalid PIN. | Ensure PIN is numeric and the length is in between 4 to 10 digits. |
ERROR_SDK_AND_SERVER_OUT_OF_SYNC | Migration flow resulted in failure. | Uninstall the application and re-enroll accounts. Contact administrator if the error persists. |
ERROR_NO_TRANSACTION_AVAILABLE | There are no pending transactions. | Perform initAuth API call to get the transaction. |
ERROR_PINNING_FAILURE | The SSL pinning has resulted in failure. | Valid certificate must be passed from the customer app to the SDK. |
See AuthenticationResponse for more information.
Exception
None.
autoEnrollAccount
Auto-enrolls a replacement card account.
Code Snippet
public AutoEnrollmentResponse autoEnrollAccount(String displayName)
Parameters
Parameter | Mandatory? | Description |
displayName | Yes | Display name for the auto-enrolled account. This name can be derived from, for example, the card number. |
Return Value
This method returns an AutoEnrollmentResponse object, which contains the auto-enrollment details for the replacement card account.
The status can be one of the following values:
- SUCCESS:Operation was successful.
- FAILURE:Operation failed.
If the status is FAILURE, then one of the following errorCode values is returned
Error Code | Description | Action to Take |
ERROR_SDK_LIB_NOT_INITIALIZED | Device parameter not initialized. | Ensure the SDK Lib is initialized. If not, empty or null value is received from the reference app. |
ERROR_SDK_INTERNAL | SDK has returned an error. | Ensure mobile3ds.sqlite file has read and write permissions. If the issue still persists please contact the administrator. |
ERROR_NETWORK_UNAVAILABLE | The device is not connected to the Internet. | Ensure that the Internet connection available and try again. |
ERROR_INVALID_AUTH_APP_ID | The Auth App Id is not present in database. | Ensure getAuthAppId method returns a value. If not, please contact the administrator. |
ERROR_PIN_SETUP_PENDING | The user PIN is not set. | Ensure isPINSetup method returns true. |
ERROR_INVALID_DISPLAY_NAME | Display name is not valid because, for example, it is NULL or an empty string. | Ensure passed display name has a value. |
ERROR_DISPLAY_NAME_ALREADY_EXISTS | Display name already exists in the database. | Change the display name and try again. |
ERROR_AUTO_ENROLLMENT_FAILURE | Auto-enrollment operation failed on the server. This could have resulted for any of the following reasons:
| Check the debug log for more details or contact administrator. |
ERROR_SERVER_UNREACHABLE | Server is unreachable. | Ensure that you have internet connection available and try again. |
ERROR_AUTHENTICATION_FAILURE | Authentication of the new account failed after successful auto-enrollment. | Display a Transaction Rejected message. Check the debug log for more details or contact administrator.
|
ERROR_MIGRATION_REQUIRED | The SDK is updated to 2.0, but the migration flow is not completed | Ensure the migration flow is successfully completed. |
ERROR_SERVER_INTERNAL | Internal server error occurred. | Contact your administrator. |
ERROR_PINNING_FAILURE | The SSL pinning has resulted in failure. | Valid certificate must be passed from the customer app to the SDK. |
ERROR_NO_TRANSACTION_AVAILABLE | There are no pending transactions. | Perform initAuth API call to get the transaction. |
Exception
None.
cancelTransaction
Cancels the transaction specified by a TransactionDetailsResponse object. Call this API when, for example, the user declines a transaction. You can decide on the other scenarios for which this API must be called.
Call this API in a background thread.
Code snippet
public CancelTransactionResponse cancelTransaction(TransactionDetailsResponse transactionDetailsResponse) |
Parameters
Parameter | Mandatory? | Description |
transactionDetailsResponse | Yes | TransactionDetailsResponse object. |
Return Value
This method returns a CancelTransactionResponse object, which contains the status and error code.
The status can be one of the following values:
- SUCCESS:Operation was successful.
- FAILURE:Operation failed.
If the status is FAILURE, then one of the following error codes is returned:
Error Code | Description | Action to Take |
ERROR_INVALID_PIN | Invalid PIN. | Ensure PIN is numeric and the length is in between 4 to 10 digits. |
ERROR_OPERATION_NOT_ALLOWED | User is trying to disable an authentication type (biometric) that is already disabled. | Ensure the authentication is enabled. Call getEnabledAuthenticationTypes method and verify the enabled authentication types. |
ERROR_NO_BIOMETRIC_AVAILABLE | Biometric authentication is not enabled on this device. | Ensure the BIOMETRIC-related options are enabled on your device. |
ERROR_INTERNAL_READWRITE | The query execution failed due to insufficient permissions. | Ensure mobile3ds.sqlite file has read and write permissions. |
ERROR_NETWORK_UNAVAILABLE | The device is not connected to the Internet. | Ensure that the Internet connection available and try again. |
ERROR_INVALID_ARGUMENT | Incorrect details were passed | Ensure the arguments that you pass are correct and not null. |
ERROR_INVALID_AUTH_APP_ID | The Auth App Id is not present in database. | Ensure getAuthAppId method returns a value. If not, please contact the administrator. |
ERROR_SDK_INTERNAL | The server URL data not available in the database. | Contact the administrator. |
ERROR_SERVER_UNREACHABLE | Server is unreachable or the API response is null. | Ensure that you have internet connection available and try again. |
ERROR_NO_TRANSACTION_AVAILABLE | There are no pending transactions. | Perform initAuth API call to get the transaction. |
ERROR_PINNING_FAILURE | The SSL pinning has resulted in failure. | Valid certificate must be passed from the customer app to the SDK. |
See CancelTransactionResponse for more information.
Exception
None.
isPinSetUp
Returns true if the user has set up a PIN. Most of the SDK flows, including the Authentication flows, begin with a call to this API. These flows can proceed only if the user has a PIN.
Code snippet
public boolean isPinSetUp() |
Parameters
None.
Return Value
boolean
Exception
None.
verifyActivation (for the first account before the PIN is set up)
Activates CA Strong Authentication for the first account.
The user sets up the PIN while activating CA Strong Authentication for the first account. The PIN setup page is displayed to the user as part of this API call.
Call this API in a background thread.
This API is deprecated, and it will be removed in a future release. To activate CA Strong Authentication for a single account, you can call the 'verifyActivation (for multiple accounts before the PIN is set up)' API, which is covered later in this table.
Code snippet
public AccountActivationDetails verifyActivation(String activationRefId, String activationCode, String serverURL, String displayName) |
Parameters
Parameter | Mandatory? | Description |
activationRefId | Yes | Reference ID. |
activationCode | Yes | Activation code. |
serverURL | Yes | CA Strong Authentication server URL. |
displayName | Yes | Display name of the account. |
Return Value
Returns an AccountActivationDetails object, which contains the status and error code.
The status can be one of the following values:
- SUCCESS:Operation was successful.
- FAILURE:Operation failed.
If the status is FAILURE, then one of the following error codes is returned
Error Code | Description | Action to Take |
ERROR_SDK_LIB_NOT_INITIALIZED | Device parameter not initialized. | Ensure the SDK Lib is initialized. If not, empty or null value is received from the reference app. |
ERROR_SDK_INTERNAL | SDK has returned an error. | Ensure mobile3ds.sqlite file has read and write permissions. If the issue still persists please contact the administrator. |
ERROR_NETWORK_UNAVAILABLE | The device is not connected to the Internet. | Ensure that the Internet connection available and try again. |
ERROR_INVALID_PIN | Invalid PIN. | Ensure PIN is numeric and the length is in between 4 to 10 digits. |
ERROR_INVALID_ARGUMENT | Incorrect details were passed. | Ensure the arguments that you pass are correct and not null. |
ERROR_SERVER_UNREACHABLE | The verifyActivationResponse is nil. | Ensure that you have internet connection available and try again. |
ERROR_DISPLAY_NAME_ALREADY_EXISTS | Display name already exists in the database. | Change the display name and try again |
ERROR_INVALID_AUTH_APP_ID | The Auth App Id is not present in database. | Ensure getAuthAppId method returns a value. If not, please contact the administrator. |
ERROR_SERVER_INTERNAL | Internal server error was encountered. | Try again after some time or contact the administrator. |
ERROR_INVALID_ACTIVATION_REF_ID | User submitted an invalid reference ID. | Ensure valid activation reference ID is passed in this method. |
ERROR_INVALID_CREDENTIALS | User submitted an invalid credential. | nsure valid credentials are passed in this method. |
ERROR_MIGRATION_REQUIRED | The SDK is updated to 2.0, but the migration flow is not completed. | Ensure the migration flow is successfully completed. |
ERROR_PINNING_FAILURE | The SSL pinning has resulted in failure. | Valid certificate must be passed from the customer app to the SDK. |
See AccountActivationDetails for more information.
Exception
None.
verifyActivation (for a single account after the PIN is set up)
Activates CA Strong Authentication for the second or subsequent account.
The PIN must be set up before calling this API.
Call this API in a background thread.
This API is deprecated, and it will be removed in a future release. To activate CA Strong Authentication for a single account, you can call the 'verifyActivation (for multiple accounts before the PIN is set up)' API, which is covered later in this table.
Code snippet
public AccountActivationDetails verifyActivation(String activationRefId, String activationCode, String serverURL, String displayName, String userPin) |
Parameters
Parameter | Mandatory? | Description |
activationRefId | Yes | Reference ID. |
activationCode | Yes | Activation code. |
serverURL | Yes | CA Strong Authentication server URL. |
displayName | Yes | Display name of the account. |
userPin | Yes | User PIN. |
Return Value
Returns an AccountActivationDetails object, which contains the status and error code.
The status can be one of the following values:
- SUCCESS:Operation was successful.
- FAILURE:Operation failed.
If the status is FAILURE, then one of the following error codes is returned:
Error Code | Description | Action to Take |
ERROR_SDK_LIB_NOT_INITIALIZED | Device parameter not initialized. | Ensure the SDK Lib is initialized. If not, empty or null value is received from the reference app. |
ERROR_SDK_INTERNAL | SDK has returned an error. | Ensure mobile3ds.sqlite file has read and write permissions. If the issue still persists please contact the administrator. |
ERROR_NETWORK_UNAVAILABLE | The device is not connected to the Internet. | Ensure that the Internet connection available and try again. |
ERROR_INVALID_PIN | Invalid PIN. | Ensure PIN is numeric and the length is in between 4 to 10 digits. |
ERROR_INVALID_ARGUMENT | Incorrect details were passed. | Ensure the arguments that you pass are correct and not null. |
ERROR_SERVER_UNREACHABLE | The verifyActivationResponse is nil. | Ensure that you have internet connection available and try again. |
ERROR_DISPLAY_NAME_ALREADY_EXISTS | Display name already exists in the database. | Change the display name and try again |
ERROR_INVALID_AUTH_APP_ID | The Auth App Id is not present in database. | Ensure getAuthAppId method returns a value. If not, please contact the administrator. |
ERROR_SERVER_INTERNAL | Internal server error was encountered. | Try again after some time or contact the administrator. |
ERROR_INVALID_ACTIVATION_REF_ID | User submitted an invalid reference ID. | Ensure valid activation reference ID is passed in this method. |
ERROR_INVALID_CREDENTIALS | User submitted an invalid credential. | nsure valid credentials are passed in this method. |
See AccountActivationDetails for more information.
Exception
None.
verifyActivation (for multiple accounts before the PIN is set up)
Activates CA Strong Authentication for multiple accounts.
The user sets up the PIN as part of this process. The PIN setup page is displayed to the user as part of this API call.
Call this API in a background thread.
ThIs API can be called during the silent enrollment process. For information about silent enrollment, see Sequence Diagrams for Enrollment Flows.
Code snippet
public AccountsActivationDetails verifyActivation(AccountActivationRequest[] requests, String serverUrl) |
Parameters
Parameter | Mandatory? | Description | ||||||||
AccountActivationRequest[] | Yes | Array of AccountActivationRequest objects. Each object contains the following attributes:
| ||||||||
serverURL | Yes | CA Strong Authentication server URL. |
Return Value
Returns an AccountsActivationDetails object, which contains the status and error code.
The status can be one of the following values:
- SUCCESS:Operation was successful.
- FAILURE:Operation failed.
If the status is FAILURE, then one of the following error codes is returned:
Error Code | Description | Action to Take |
ERROR_SDK_LIB_NOT_INITIALIZED | Device parameter not initialized. | Ensure the SDK Lib is initialized. If not, empty or null value is received from the reference app. |
ERROR_SDK_INTERNAL | SDK has returned an error. | Ensure mobile3ds.sqlite file has read and write permissions. If the issue still persists please contact the administrator. |
ERROR_NETWORK_UNAVAILABLE | The device is not connected to the Internet. | Ensure that the Internet connection available and try again. |
ERROR_INVALID_ACTIVATION_PARAMS | MultipleAccountActivationParams parameter validation failed. | Ensure multipleAccountActivationParams is passed in the method and has values. |
ERROR_INVALID_PIN | Invalid PIN. | Ensure PIN is numeric and the length is in between 4 to 10 digits. |
ERROR_INVALID_ARGUMENT | Incorrect details were passed. | Ensure the arguments that you pass are correct and not null. |
ERROR_SERVER_UNREACHABLE | The verifyActivationResponse is nil. | Ensure that you have internet connection available and try again. |
ERROR_DISPLAY_NAME_ALREADY_EXISTS | Display name already exists in the database. | Change the display name and try again |
ERROR_INVALID_AUTH_APP_ID | The Auth App Id is not present in database. | Ensure getAuthAppId method returns a value. If not, please contact the administrator. |
ERROR_SERVER_INTERNAL | Internal server error was encountered. | Try again after some time or contact the administrator. |
ERROR_INVALID_ACTIVATION_REF_ID | User submitted an invalid reference ID. | Ensure valid activation reference ID is passed in this method. |
ERROR_INVALID_CREDENTIALS | User submitted an invalid credential. | nsure valid credentials are passed in this method. |
ERROR_INVALID_SERVER_URL | Server URL is empty. | Ensure serverURL is passed in the method correctly. |
ERROR_PINNING_FAILURE | The SSL pinning has resulted in failure. | Valid certificate must be passed from the customer app to the SDK. |
See AccountsActivationDetails for more information.
Exception
None.
verifyActivation (for multiple accounts after the PIN is set up)
Activates CA Strong Authentication for multiple accounts.
This API must be called if the user has already set up the PIN.
Call this API in a background thread.
ThIs API can be called during the silent enrollment process. For information about silent enrollment, see Sequence Diagrams for Enrollment Flows.
Code snippet
public |
Parameters
Parameter | Mandatory? | Description | ||||||||
AccountActivationRequest[] | Yes | Array of AccountActivationRequest objects. Each object contains the following attributes:
| ||||||||
serverURL | Yes | CA Strong Authentication server URL. | ||||||||
userPin | Yes | User PIN. |
Return Value
Returns an AccountsActivationDetails object, which contains the status and error code.
The status can be one of the following values:
- SUCCESS:Operation was successful.
- FAILURE:Operation failed.
If the status is FAILURE, then one of the following error codes is returned:
Error Code | Description | Action to Take |
ERROR_SDK_LIB_NOT_INITIALIZED | Device parameter not initialized. | Ensure the SDK Lib is initialized. If not, empty or null value is received from the reference app. |
ERROR_SDK_INTERNAL | SDK has returned an error. | Ensure mobile3ds.sqlite file has read and write permissions. If the issue still persists please contact the administrator. |
ERROR_NETWORK_UNAVAILABLE | The device is not connected to the Internet. | Ensure that the Internet connection available and try again. |
ERROR_INVALID_ACTIVATION_PARAMS | MultipleAccountActivationParams parameter validation failed. | Ensure multipleAccountActivationParams is passed in the method and has values. |
ERROR_INVALID_PIN | Invalid PIN. | Ensure PIN is numeric and the length is in between 4 to 10 digits. |
ERROR_INVALID_ARGUMENT | Incorrect details were passed. | Ensure the arguments that you pass are correct and not null. |
ERROR_SERVER_UNREACHABLE | The verifyActivationResponse is nil. | Ensure that you have internet connection available and try again. |
ERROR_DISPLAY_NAME_ALREADY_EXISTS | Display name already exists in the database. | Change the display name and try again |
ERROR_INVALID_AUTH_APP_ID | The Auth App Id is not present in database. | Ensure getAuthAppId method returns a value. If not, please contact the administrator. |
ERROR_SERVER_INTERNAL | Internal server error was encountered. | Try again after some time or contact the administrator. |
ERROR_INVALID_ACTIVATION_REF_ID | User submitted an invalid reference ID. | Ensure valid activation reference ID is passed in this method. |
ERROR_INVALID_CREDENTIALS | User submitted an invalid credential. | nsure valid credentials are passed in this method. |
ERROR_INVALID_SERVER_URL | Server URL is empty. | Ensure serverURL is passed in the method correctly. |
ERROR_MIGRATION_REQUIRED | The SDK is updated to 2.0, but the migration flow is not completed. | Ensure the migration flow is successfully completed. |
See AccountsActivationDetails for more information.
Exception
None.
deleteAccount
Deletes the account specified by an AccountDetails object.
This method will be deprecated in a future release. The unenrollAccounts API can be used to delete a single or multiple accounts. This overloaded API is described later in this table.
Call this API in a background thread.
Code snippet
public AccountDeletionResponse deleteAccount(AccountDetails account) |
Parameters
Parameter | Mandatory? | Description |
account | Yes | AccountDetails object |
Return Value
Returns an AccountDeletionResponse object, which contains the status and error code.
The status can be one of the following values:
- SUCCESS:Operation was successful.
- FAILURE:Operation failed.
If the status is FAILURE, then the one of the following error codes is returned:
Error Code | Description | Action to Take |
ERROR_NETWORK_UNAVAILABLE | The device is not connected to the Internet. | Ensure that the Internet connection available and try again. |
ERROR_SDK_INTERNAL | SDK has returned an error. | Ensure mobile3ds.sqlite file has read and write permissions. If the issue still persists please contact the administrator. |
ERROR_INVALID_ARGUMENT | Incorrect details were passed. | Ensure the arguments that you pass are correct and not null. |
ERROR_INVALID_AUTH_APP_ID | The Auth App Id is not present in database. | Ensure getAuthAppId method returns a value. If not, please contact the administrator. |
ERROR_ACCOUNT_NOT_FOUND | Account not present in the database. | Unenroll and reenroll the accounts. |
ERROR_SERVER_UNREACHABLE | Server is unreachable. | Ensure that you have internet connection available and try again. |
ERROR_INTERNAL_READWRITE | The query execution failed due to insufficient permissions. | Ensure mobile3ds.sqlite file has read and write permissions.
|
ERROR_MIGRATION_REQUIRED | The SDK is updated to 2.0, but the migration flow is not completed. | Ensure the migration flow is successfully completed. |
ERROR_PINNING_FAILURE | The SSL pinning has resulted in failure. | Valid certificate must be passed from the customer app to the SDK. |
See AccountDeletionResponse for more information.
Exception
None.
setPin (for a single account)
Sets the user PIN when the verifyActivation method (for a single account) is called in a scenario when the user has not set a PIN..
Call this API in a background thread.
Code snippet
public ActivationAcknowledgementResponse setPin(String accountId, String userPin) |
Parameters
Parameter | Mandatory? | Description |
accountId | Yes | Account ID. |
userPin | Yes | User PIN. |
Return Value
Return an ActivationAcknowledgementResponse object, which contains the status and error code.
The status can be one of the following values:
- SUCCESS:Operation was successful.
- FAILURE:Operation failed.
If the status is FAILURE, the one of the following error codes value is returned:
Error Code | Description | Action to Take |
ERROR_NETWORK_UNAVAILABLE | The device is not connected to the Internet. | Ensure that the Internet connection available and try again. |
ERROR_INVALID_ARGUMENT | Incorrect details were passed. | Ensure the arguments that you pass are correct and not null. |
ERROR_INVALID_AUTH_APP_ID | The Auth App Id is not present in database. | Ensure getAuthAppId method returns a value. If not, please contact the administrator. |
ERROR_INVALID_PIN | Invalid PIN. | Ensure PIN is numeric and the length is in between 4 to 10 digits. |
ERROR_INTERNAL_READWRITE | The query execution failed due to insufficient permissions. | Ensure mobile3ds.sqlite file has read and write permissions. |
ERROR_MIGRATION_REQUIRED | The SDK is updated to 2.0, but the migration flow is not completed. | Ensure the migration flow is successfully completed. |
ERROR_SERVER_UNREACHABLE | Server is unreachable. | Ensure that you have internet connection available and try again. |
ERROR_SERVER_INTERNAL | Internal server error. | Contact your administrator. |
ERROR_PINNING_FAILURE | The SSL pinning has resulted in failure. | Valid certificate must be passed from the customer app to the SDK. |
See ActivationAcknowledgementResponse for more information.
Exception
None.
setPin (for multiple accounts)
Sets the user PIN when the verifyActivation method (for multiple accounts) is called in a scenario when the user has not set a PIN.
Call this API in a background thread.
Code snippet
List<ActivationAcknowledgementResponse> setPin(String userPin) |
Parameters
Parameter | Mandatory? | Description |
userPin | Yes | User PIN. |
Return Value
Return a List of ActivationAcknowledgementResponse objects. Each object contains the status and error code.
The status can be one of the following values:
- SUCCESS:Operation was successful.
- FAILURE:Operation failed.
If the status is FAILURE, the one of the following error codes value is returned:
Error Code | Description | Action to Take |
ERROR_NETWORK_UNAVAILABLE | The device is not connected to the Internet. | Ensure that the Internet connection available and try again. |
ERROR_INVALID_AUTH_APP_ID | The Auth App Id is not present in database. | Ensure getAuthAppId method returns a value. If not, please contact the administrator. |
ERROR_INVALID_REQUEST | setPin is called when it is not required by the SDK. | |
ERROR_INVALID_PIN | Invalid PIN. | Ensure PIN is numeric and the length is in between 4 to 10 digits. |
ERROR_INTERNAL_READWRITE | The query execution failed due to insufficient permissions. | Ensure mobile3ds.sqlite file has read and write permissions. |
ERROR_SDK_INTERNAL | An SDK error was encountered. | Contact your administrator. |
ERROR_SERVER_INTERNAL | Internal server error. | Contact your administrator. |
ERROR_MIGRATION_REQUIRED | The SDK is updated to 2.0, but the migration flow is not completed. | Ensure the migration flow is successfully completed. |
ERROR_PINNING_FAILURE | The SSL pinning has resulted in failure. | Valid certificate must be passed from the customer app to the SDK. |
See ActivationAcknowledgementResponse for more information.
Exception
None.
getAllEnrolledAccounts
Gets all accounts for which CA Strong Authentication has been activated.
Code snippet
public ArrayList<AccountDetails> getAllEnrolledAccounts() |
Parameters
None.
Return Value
ArrayList of AccountDetails objects.
See AccountDetails for more information.
Exception
None.
getAllServiceURLs
Gets the service URLs for activating CA Strong Authentication for the user’s accounts. These URLs may be direct URLs of the CA Strong Authentication server. Alternatively, they can be URLs of the enterprise back-end server that, in turn, calls the CA Strong Authentication server.
Code snippet
public String[] getAllServiceURLs() |
Parameters
None.
Return Value
String array.
Exception
None.
setURL
Updates the Service URL for the specified organization, in the SDK database. Returns true if the update operation is successful.
Code snippet
public boolean setURL(String orgName, String newURL) |
Parameters
Parameter | Mandatory? | Description |
orgName | Yes | Organization name in CA Strong Authentication. |
newURL | Yes | Service URL. |
Return Value
boolean
Exception
None.
generateOTP (generates OTP without using transaction data)
Generates an OTP in the Offline mode for the specified account, without using transaction data.
If you are implementing the Dynamic Linking article of PSD2, then see generateOTP (generates OTP using transaction data).
Code snippet
public OTPResponse generateOTP(AccountDetails account, String userPin) |
Parameters
Parameter | Mandatory? | Description |
account | Yes | AccountDetails object. |
userPin | Yes | User PIN. |
Return Value
Returns an OTPResponse object, which contains the status and error code.
The status can be one of the following values:
- SUCCESS:Operation was successful.
- FAILURE:Operation failed.
If the status is FAILURE, then one of the following error codes is returned:
- ERROR_SDK_INTERNAL:SDK error scenario.
- ERROR_INVALID_ARGUMENT:Incorrect details were passed.
- ERROR_INVALID_PIN:Invalid PIN passed to the method.
See OTPResponse for more information.
Exception
None.
generateOTP (generates OTP using transaction data)
Generates an OTP in the Offline mode for the specified account by using transaction data. Use this API if you are implementing the Dynamic Linking article of PSD2.
Code snippet
public OTPResponse generateOTP(AccountDetails account, String userPin, HashMap additionalInputs) |
Parameters
Parameter | Mandatory? | Description |
account | Yes | AccountDetails object. |
userPin | Yes | User PIN. |
additionalInputs | Yes | HashMap that holds the SIGNING_DATA key. The value of this key must be the transaction data. The SIGNING_DATA is defined in the M3DSConstants file. It can be referred to as follows: additionalInput.put(M3DSConstants.SIGNING_DATA,transactionSignData) |
Return Value
Returns an OTPResponse object, which contains the status and error code.
The status can be one of the following values:
- SUCCESS:Operation was successful.
- FAILURE:Operation failed.
If the status is FAILURE, then one of the following error codes is returned:
Error Code | Description | Action to Take |
ERROR_INVALID_ARGUMENT | Incorrect details were passed. | Ensure the arguments that you pass are correct and not null. |
ERROR_INVALID_PIN | Invalid PIN. | Ensure PIN is numeric and the length is in between 4 to 10 digits. |
ERROR_INVALID_SIGNING_DATA | Invalid transaction data was passed. | Ensure the signing data passed in the method has values. |
ERROR_SDK_INTERNAL | SDK has returned an error. | Ensure mobile3ds.sqlite file has read and write permissions. If the issue still persists please contact the administrator. |
See OTPResponse for more information.
Exception
None.
changePin
Changes the user PIN.
Call this API in a background thread.
Code snippet
public ChangePinResponse changePin(String oldPin, String newPin) |
Parameters
Parameter | Mandatory? | Description |
oldPin | Yes | Old user PIN. |
newPin | Yes | New user PIN. |
Return Value
Returns a ChangePinResponse object, which contains the status and error code.
The status can be one of the following values:
- SUCCESS:Operation was successful.
- FAILURE:Operation failed.
If the status is FAILURE, then one of the following error codes is returned
Error Code | Description | Action to Take |
ERROR_NO_ACTIVE_ACCOUNTS | Active account not present in the database. | Unenroll and reenroll the accounts. |
ERROR_INVALID_AUTH_APP_ID | The Auth App Id is not present in database. | Ensure getAuthAppId method returns a value. If not, please contact the administrator. |
ERROR_INVALID_PIN | Invalid PIN passed to the method. | Ensure PIN is numeric and the length is in between 4 to 10 digits. |
ERROR_SDK_INTERNAL | SDK has returned an error. | Ensure mobile3ds.sqlite file has read and write permissions. If the issue still persists please contact the administrator. |
See ChangePinResponse for more information.
Exception
None.
verifyPin (verifies PIN without using transaction data)
Verifies the user PIN, without using transaction data.
Use this API for operations such as activating new accounts on the device, changing the PIN, disabling or enabling the authentication types, or deleting an account.
If you are implementing the Dynamic Linking article of PSD2, then see verifyPin (verifies PIN using transaction data).
Call this API in a background thread.
Code snippet
public VerifyPinResponse verifyPin(String pin) |
Parameters
Parameter | Mandatory? | Description |
Pin | Yes | User PIN. |
Return Value
Returns a VerifyPinResponse object, which contains the status and error message.
The status can be one of the following values:
- SUCCESS:Operation was successful.
- FAILURE:Operation failed.
If the status is FAILURE, then one of the following error codes is returned:
Error Code | Description | Action to Take |
ERROR_INVALID_ARGUMENT | Incorrect details were passed. | Ensure the arguments that you pass are correct and not null. |
ERROR_INVALID_AUTH_APP_ID | The Auth App Id is not present in database. | Ensure getAuthAppId method returns a value. If not, please contact the administrator. |
ERROR_INVALID_PIN | Invalid PIN. | Ensure PIN is numeric and the length is in between 4 to 10 digits. |
ERROR_NO_ACTIVE_ACCOUNTS | No active accounts are present. For example, when the existing accounts are locked. | Unenroll and reenroll the accounts. |
ERROR_INVALID_SIGNING_DATA | Invalid transaction data was passed. | Ensure the signing data passed in the method has values. |
ERROR_SERVER_INTERNAL | Server has returned an error. The credential_type not present in the response. | Retry after some time or contact the administrator. |
ERROR_PINNING_FAILURE | The SSL pinning has resulted in failure. | Valid certificate must be passed from the customer app to the SDK. |
Exception
None.
verifyPin (verifies PIN without using transaction data)
Verifies the user PIN, without using transaction data.
Use this API for operations such as activating new accounts on the device, changing the PIN, disabling or enabling the authentication types, or deleting an account.
If you are implementing the Dynamic Linking article of PSD2, then see verifyPin (verifies PIN using transaction data).
Call this API in a background thread.
Code snippet
public VerifyPinResponse verifyPin(String pin, TransactionDetailsResponse transactionDetailsResponse, String autoEnrollId) |
Parameters
Parameter | Mandatory? | Description |
Pin | Yes | User PIN. |
AutoEnrollId | Yes | The auto enroll identifier. |
Return Value
Returns a VerifyPinResponse object, which contains the status and error message.
The status can be one of the following values:
- SUCCESS:Operation was successful.
- FAILURE:Operation failed.
If the status is FAILURE, then one of the following error codes is returned:
Error Code | Description | Action to Take |
ERROR_MIGRATION_REQUIRED | The SDK is updated to 2.0, but the migration flow is not completed. | Ensure the migration flow is successfully completed. |
ERROR_INVALID_AUTH_APP_ID | The Auth App Id is not present in database. | Ensure getAuthAppId method returns a value. If not, please contact the administrator. |
ERROR_NETWORK_UNAVAILABLE | The device is not connected to the Internet. | Ensure that the Internet connection available and try again. |
ERROR_SDK_INTERNAL | SDK has returned an error. | Ensure mobile3ds.sqlite file has read and write permissions. If the issue still persists please contact the administrator. |
ERROR_SDK_LIB_NOT_INITIALIZED | Device parameter not initialized. | Ensure the SDK Lib is initialized. If not, empty or null value is received from the reference app. |
ERROR_PIN_SETUP_PENDING | The user PIN is not set. | Ensure isPINSetup method returns true. |
ERROR_INVALID_ARGUMENT | Incorrect details were passed. | Ensure the arguments that you pass are correct and not null. |
ERROR-INVALID_SIGNING_DATA | The signing data in invalid or not found. | Verify the signing data passed in the method has values. If not, pass the signing data and try again. |
ERROR_INVALID_PIN | Invalid PIN. | Ensure PIN is numeric and the length is in between 4 to 10 digits. |
ERROR_PINNING_FAILURE | The SSL pinning has resulted in failure. | Valid certificate must be passed from the customer app to the SDK. |
Exception
None.
verifyPin (verifies PIN using transaction data)
Verifies the user PIN by using transaction data.
Use this API if you are implementing the Dynamic Linking article of PSD2.
Use this API for operations such as activating new accounts on the device, changing the PIN, disabling or enabling the authentication types, or deleting an account.
Call this API in a background thread.
Code snippet
public VerifyPinResponse verifyPin(String pin, String transactionSignData) |
Parameters
Parameter | Mandatory? | Description |
pin | Yes | User PIN. |
transactionSignData | Yes | Transaction data for signing |
Return Value
Returns a VerifyPinResponse object, which contains the status and error message.
The status can be one of the following values:
- SUCCESS:Operation was successful.
- FAILURE:Operation failed.
If the status is FAILURE, then one of the following error codes is returned:
Error Code | Description | Action to Take |
ERROR_INVALID_ARGUMENT | Incorrect details were passed. | Ensure the arguments that you pass are correct and not null. |
ERROR_INVALID_AUTH_APP_ID | The Auth App Id is not present in database. | Ensure getAuthAppId method returns a value. If not, please contact the administrator. |
ERROR_INVALID_PIN | Invalid PIN. | Ensure PIN is numeric and the length is in between 4 to 10 digits. |
ERROR_NO_ACTIVE_ACCOUNTS | No active accounts are present. For example, when the existing accounts are locked. | Unenroll and reenroll the accounts. |
ERROR_INVALID_SIGNING_DATA | Invalid transaction data was passed. | Ensure the signing data passed in the method has values. |
ERROR_SERVER_INTERNAL | Server has returned an error. The credential_type not present in the response. | Retry after some time or contact the administrator. |
ERROR_PINNING_FAILURE | The SSL pinning has resulted in failure. | Valid certificate must be passed from the customer app to the SDK. |
Exception
None.
getProfileInfo
Returns the device information.
Code snippet
public ProfileInfo getProfileInfo()
Parameters
None.
Return Value
Return a ProfileInfo object, which contains the status and error code values.
The status can be one of the following values:
- SUCCESS: Operation was successful.
- FAILURE: Operation failed.
If status is FAILURE, then one of the below error codes will be returned in the response object:
Error Code | Description | Action to Take |
PROFILE_INFO_NOT_AVAILABLE | No profile available in the device. | Enroll at least one account and invoke this method. If the error still persists, then contact the administrator |
Exception
None.
isDeviceJailBroken
Code snippet
public Boolean isDeviceJailBroken()
Parameters
None.
Return Value
Return a boolean object.The status can be one of the following values:
- TRUE: Indicates device is jail-broken.
- FALSE: Indicates that the device is not jail-broken.
Exception
None.
unenrollAccounts (for a single or multiple accounts)
Deletes a single or multiple accounts selected by the user.
Call this API in a background thread.
Code snippet
public UnenrollAccountResponse unEnrollAccounts(List<AccountDetails> accountDetails, boolean removeFromServer)
Parameters
Parameter | Mandatory? | Description |
accountDetails | Yes | Array of AccountDetails objects. |
removeFromServer | Yes | Boolean flag that specifies whether the accounts must also be deleted from the CA Strong Authentication server. When this flag is set to true, accounts are removed from the device and server. However, the PIN is not removed, so new accounts can continue to be provisioned on this device. |
Return Value
Returns a UnenrollmentResponse object, which contains the status and error message. The status can be one of the following values:
- SUCCESS:Operation was successful.
- FAILURE:Operation failed.
Error Code | Description | Action to Take |
ERROR_INVALID_ARGUMENT | Incorrect details were passed. | Ensure the arguments that you pass are correct and not null. |
ERROR_INVALID_AUTH_APP_ID | The Auth App Id is not present in database. | Ensure getAuthAppId method returns a value. If not, please contact the administrator. |
ERROR_MIGRATION_REQUIRED | The SDK is updated to 2.0, but the migration flow is not completed. | Ensure the migration flow is successfully completed. |
ERROR_SDK_INTERNAL | SDK has returned an error. | Ensure mobile3ds.sqlite file has read and write permissions. If the issue still persists please contact the administrator. |
ERROR_UNENROLL_ACCOUNTS | The unenroll account operation failed. | Please try again after some time. If the issue still persists please contact the administrator. |
ERROR_MIGRATION_REQUIRED | The SDK is updated to 2.0, but the migration flow is not completed. | Ensure the migration flow is successfully completed. |
ERROR_NETWORK_UNAVAILABLE | The device is not connected to the Internet. | Ensure that the Internet connection available and try again. |
ERROR_SERVER_UNREACHABLE | Server is not reachable. Returns null or empty value in the response. | Check if the internet connection available and try again. |
ERROR_PINNING_FAILURE | The SSL pinning has resulted in failure. | Valid certificate must be passed from the customer app to the SDK. |
Exception
None.
unenrollAccounts (for all accounts)
Deletes all accounts and can also delete the PIN setup.
Call this API in a background thread.
Code snippet
public unenrollAccounts unenrollAccounts(boolean removePinSetup, boolean removeFromServer)
Parameters
Parameter | Mandatory? | Description |
removePinSetup | Yes | Boolean flag that specifies whether the user's current PIN must be retained or removed. In addition, the PIN is removed. To activate new accounts on this device or a different device, the user will be prompted to set up a PIN. |
removeFromServer | Yes | Boolean flag that specifies whether the accounts must also be deleted from the CA Strong Authentication server. When this flag is set to true, accounts are removed from the device and server. However, the PIN is not removed, so new accounts can continue to be provisioned on this device. |
Return Value
Returns a UnenrollmentResponse object, which contains the status and error message. The status can be one of the following values:
- SUCCESS:Operation was successful.
- FAILURE:Operation failed.
Error Code | Description | Action to Take |
ERROR_INVALID_ARGUMENT | Incorrect details were passed. | Ensure the arguments that you pass are correct and not null. |
ERROR_INVALID_AUTH_APP_ID | The Auth App Id is not present in database. | Ensure getAuthAppId method returns a value. If not, please contact the administrator. |
ERROR_MIGRATION_REQUIRED | The SDK is updated to 2.0, but the migration flow is not completed. | Ensure the migration flow is successfully completed. |
ERROR_SDK_INTERNAL | SDK has returned an error. | Ensure mobile3ds.sqlite file has read and write permissions. If the issue still persists please contact the administrator. |
ERROR_UNENROLL_ACCOUNTS | The unenroll account operation failed. | Please try again after some time. If the issue still persists please contact the administrator. |
ERROR_MIGRATION_REQUIRED | The SDK is updated to 2.0, but the migration flow is not completed. | Ensure the migration flow is successfully completed. |
ERROR_NETWORK_UNAVAILABLE | The device is not connected to the Internet. | Ensure that the Internet connection available and try again. |
ERROR_SERVER_UNREACHABLE | Server is not reachable. Returns null or empty value in the response. | Check if the internet connection available and try again. |
ERROR_PINNING_FAILURE | The SSL pinning has resulted in failure. | Valid certificate must be passed from the customer app to the SDK. |
Exception
None.
configureSSLPinning (SSLPinningConfigs sslPinningConfigs)
This method checks if the SSL pinning configurtion is successful.
Code snippet
public SSLPinningConfigResponse configureSSLPinning(SSLPinningConfigs sslPinningConfigs)
Parameters
Parameter | Mandatory? | Description |
sslPinningConfigs | Yes | Contains the pinning configuration details, such as certificates, type of pinning (public key or certiticate), indication if the pinning is required or not. |
Return Value
Returns a SSLPinningResponse object, which contains status, error code, and error message. The status can be one of the following values:
- SUCCESS:Operation was successful.
- FAILURE:Operation failed.
Error Code | Description | Action to Take |
ERROR_PINNING_CONFIG | The SSL pinning configuration has resulted in failure. This error can be returned in scenarios, such as:
| Based on the error description, provide the correct input to the SDK. |
Exception
None.
Class Authentication
This Authentication class contains the AuthenticationType and AuthenticationTypeStatus enums. This class manages the various authentications types, such as USER_PIN and BIOMETRIC.
Java Code Snippet
public class Authentication {public Authentication(AuthenticationType authType, AuthenticationTypeStatus authTypeStatus) public AuthenticationType getAuthType () public void setAuthType(AuthenticationType authType) public AuthenticationTypeStatus getAuthTypeStatus() public void setAuthTypeStatus(AuthenticationTypeStatus authTypeStatus) } |
Constructor
Authentication(AuthenticationType authType, AuthenticationTypeStatus authTypeStatus) | Initializes the Authentication object. |
Methods
getAuthType | Gets the AuthenticationType instance. See AuthenticationType. |
setAuthType | Sets the AuthenticationType instance value |
getAuthTypeStatus | Gets the AuthenticationTypeStatus instance. |
setAuthTypeStatus | Sets the AuthenticationTypeStatus instance value. |
Class FingerPrintAuthenticator
This FingerPrintAuthenticator class contains methods to authenticate using biometrics (fingerprtints).
Java Code Snippet
public class FingerPrintAuthenticator {public FingerPrintAuthenticator(AuthenticateTransactionCallback authenticateTransactionCallback, Context activityContext, TransactionDetailsResponse transactionDetailsResponse) public FingerPrintAuthenticator(GenerateOTPCallback generateOTPCallback, Context activityContext, AccountDetails accountDetails) public void setTransactionSignData(String transactionSignData) public void setFingerPrintDialogueTitle(String title) public void setFingerPrintDialogueMessage(String message) public void setFingerPrintTouchSensorText(String sensorText) public void setFingerPrintCancelButtonText(String cancelButtonText) public void setFingerPrintAuthenticationFailureText(String authFailureText) public void setFingerPrintAuthenticationSuccessText(String authSuccessText) public void setPinAuthenticationText(String pinToAuthenticateText) public void authenticate() } |
Constructor
FingerPrintAuthenticator(AuthenticateTransactionCallback authenticateTransactionCallback, Context activityContext, TransactionDetailsResponse transactionDetailsResponse) | Initializes the FingerPrintAuthenticator object for fingerprint authentication of a transaction. |
FingerPrintAuthenticator(GenerateOTPCallback generateOTPCallback, Context activityContext, AccountDetails accountDetails) | Initializes the FingerPrintAuthenticator object for generating an OTP using fingerprint authentication. |
Methods
setTransactionSignData | Sets the transaction data (if available) for signing the transaction. |
setFingerPrintDialogueTitle | Sets the title of the fingerprint dialog that prompts the user for fingerprint authentication. |
setFingerPrintDialogueMessage | Sets the message of the fingerprint dialog that prompts the user for fingerprint authentication. |
setFingerPrintTouchSensorText | Sets the message of the fingerprint dialog touch sensor text. |
setFingerPrintCancelButtonText | Sets the message of the fingerprint dialog cancel button text. |
setFingerPrintAuthenticationFailureText | Sets the message of the fingerprint dialog in case of authentication failure. |
setFingerPrintAuthenticationSuccessText | Sets the message of the fingerprint dialog authentication success message. |
setPinAuthenticationText | Sets the message of the fingerprint dialog for the PIN authentication text. This will shown after the user fails to authenticate using fingerprint. The PIN authentication is a fallback means of verifying the user. |
authenticate | Authenticates the user by using fingerprint authentication. |
authenticate
Authenticates the user by using fingerprint authentication.
This is one of the APIs for applying user authentication. For more information about user authentication, see CA Strong Authentication SDKs.
Code snippet
public void authenticate()
Parameters
None.
Return Value
None. The outcome of authentication is returned in the specified callback methods.
Exception
None.
Interfaces
This section describes the interfaces provided by the SDK.
Interface FingerPrintAuthenticationCallback
The FingerPrintAuthenticationCallback interface defines callback methods that perform actions corresponding to the outcome of biometric authentication.
Java Code Snippet
package com.ca.mpn_android_lib.fingerprint; public interface FingerPrintAuthenticationCallback { void onAuthenticationFailure(String errorCode); void onAuthenticationCancelled(); void onAuthenticationFallback(); } |
Methods
onAuthenticationFailure | Method to handle the Failure response. |
onAuthenticationCancelled | Method to handle the scenario in which the user selects the PIN option. In other words, the user opts to use PIN authentication instead of continuing with biometric authentication. |
onAuthenticationFallback | Method to handle the scenario in which the user cancels or closes the biometric authentication dialog. |
Interface AuthenticateTransactionCallback
The AuthenticateTransactionCallback interface defines callback methods that perform actions corresponding to the outcome of biometric authentication during a transaction. This interface extends the FingerPrintAuthenticationCallback interface.
Java Code Snippet
package com.ca.mpn_android_lib.fingerprint; import com.ca.mobile3ds.beans.AuthenticationResponse; public interface AuthenticateTransactionCallback extends FingerPrintAuthenticationCallback { void onAuthenticationSuccess(AuthenticationResponse authenticationResponse); } |
Methods
onAuthenticationSuccess | Method to handle the Success response from transaction authentication. |
Interface GenerateOTPCallback
The GenerateOTPCallback interface defines callback methods that perform actions corresponding to the outcome of biometric authentication during the Generate OTP (Offline Mode) flow. This interface extends the FingerPrintAuthenticationCallback interface.
Java Code Snippet
package com.ca.mpn_android_lib.fingerprint; import com.ca.mobile3ds.beans.OTPResponse; public interface GenerateOTPCallback extends FingerPrintAuthenticationCallback { void onAuthenticationSuccess(OTPResponse otpResponse); } |
Methods
onAuthenticationSuccess | Method to handle the Success response from authentication conducted during the Generate OTP (Offline Mode) flow. |
Enums
This section describes the enums provided by the SDK.
Enum AuthenticationType
The AuthenticationType enum defines the various authentication types.
Java Code Snippet
public enum AuthenticationType {DEVICE_PIN_AUTH(0), USER_PIN_AUTH(1), BIOMETRIC_AUTH(2); public int getIntValue() public static AuthenticationType getAuthTypeFromIntValue(int intValue) } |
The value DEVICE_PIN_AUTH(0) indicates device authentication.
Enum AuthenticationTypeStatus
The AuthenticationTypeStatus enum defines the statuses of an authentication type.
Java code snippet
public enum AuthenticationTypeStatus { ENABLED(0), DISABLED(1), NA(2); public int getIntValue() public static AuthenticationTypeStatus getAuthTypeFromIntValue(int intValue) } |
The value NA(2) indicates that biometric authentication is not supported on the device.
Response Beans
This section describes the classes whose objects are returned by the responses of the SDK operations.
Class TransactionDetailsResponse
The TransactionDetailsResponse class contains information about pending transactions. An object of this class is sent in the response of the getTransaction method.
See getTransaction for more information.
Java Code Snippet
public class TransactionDetailsResponse {public String getStatus() public String getTransactionId() public String getTransactionMessage() public String getDisplayName() public ArrayList<AuthenticationType> getAuthenticationTypes() public String getErrorCode() public String getAutoEnrollId() } |
Methods
getStatus | Gets the status of pending transactions. See the getTransaction method for more information. |
getTransactionId | Gets the transaction ID. |
getTransactionMessage | Gets the transaction message that has the details of the transaction conducted by the user. These details are displayed by the app to the user. For a push-notification-based transaction, the transaction message contains the HTML snippets that were specified as the value of the Push Body Heading Message and Push Body Passage Message elements in the Push Notification message template. For more information, see Configuring Message Templates for OTP and Push Notification Delivery. |
getDisplayName | Gets the user account display name for the pending transactions. |
getAuthenticationTypes | Gets an ArrayList of AuthenticationTypes. See the AuthenticationType enum for more information. |
getErrorCode | Gets the error code value. |
getAutoEnrollId | Gets the Auto Enrollment ID that is used to auto-enroll a replacement card. |
Class AuthenticationResponse
The AuthenticationResponse class contains information about user authentication results. An object of this class is sent in the response of the authenticateUsingConsent and authenticateUsingUserPin methods.
See the authenticateUsingConsent and authenticateUsingUserPin methods for more information.
Java Code Snippet
public class AuthenticationResponse {public String getTransactionId() public String getStatus() public boolean getAttemptAgain() public String getErrorCode() } |
Methods
getStatus | Gets the status of pending transactions. See the authenticateUsingConsent and authenticateUsingUserPin methods for more information. |
getTransactionId | Gets the transaction ID. |
getAttemptAgain | Returns true if the user enters an incorrect PIN, while the user has more retry attempts to complete the authentication.
If this method returns true, then the app should display the authentication prompt again. |
getErrorCode | Gets the Error code value. |
Class AutoEnrollmentResponse
The AutoEnrollmentResponse class contains information about the enrollment details for a replacement card. An object of this class is sent in the response of the autoEnrollAccount method.
public class AutoEnrollmentResponse { public AutoEnrollmentResponse() public AutoEnrollmentResponse(String transactionId, String status, String errorCode) public String getTransactionId() public String getStatus() public String getErrorCode() } |
Methods
Name | Description |
AutoEnrollmentResponse | Constructor. |
AutoEnrollmentResponse | Parameterized constructor. |
getTransactionId | Gets the transaction ID. |
getStatus | Gets the status of pending transactions. See the following methods for more information: |
getErrorCode | Gets the error code value. |
Class CancelTransactionResponse
The CancelTransactionResponse class contains information about the results of a Cancel Transaction operation. An object of this class is sent in the response of the cancelTransaction method.
See the cancelTransaction method for more information.
Java Code Snippet
public class CancelTransactionResponse {public String getStatus() public String getTransactionId() public String getErrorCode() } |
Methods
getStatus | Gets the status of the Cancel Transaction operation. See the cancelTransaction method for more information. |
getTransactionId | Gets the transaction ID. |
getErrorCode | Gets the Error code value. |
Class AccountActivationDetails
The AccountActivationDetails class contains account activation details. An object of this class is sent in the response of the verifyActivation (for a single account) method.
See the verifyActivation method for more information.
Java code snippet
public class AccountActivationDetails {public String getAccountId() public String getDisplayName() public String getStatus() public String getErrorCode() public String isPinRequired() } |
Methods
getStatus | Gets the status of account activation. For more information, see the verifyActivation method (for a single account). This is an overloaded method. |
getDisplayName | Gets the account display name. |
getAccountId | Gets the account ID of the activated account. |
getErrorCode | Gets the Error code value. |
isPinRequired | Returns true if the PIN is required. Otherwise, returns false.
If this method returns true, then the app must display a prompt for the user to submit the PIN or biometric. |
Class AccountsActivationDetails
The AccountsActivationDetails class contains account activation details for multiple accounts. An object of this class is sent in the response of the verifyActivation method (for multiple accounts).
Java code snippet
public class AccountsActivationDetails {public List<ActivationResponse> getAcctActivationResponses() public String getErrorCode() public String getStatus() public boolean isPinRequired() } |
Methods
getAcctActivationResponses | Gets a list of ActivationResponse objects .See Class ActivationResponse for more information. |
getErrorCode | Gets the Error code value. |
getStatus | Gets the account ID of the activated account. |
isPinRequired | Returns true if the PIN is required. Otherwise, returns false.
If this method returns true, then the app must display a prompt for the user to submit the PIN or biometric. |
Class AccountDeletionResponse
The AccountDeletionResponse class contains information about the results of an Account Deletion operation. An object of this class is sent in the response of the deleteAccount method.
See the deleteAccount method for more information.
Java Code Snippet
public class AccountDeletionResponse {public String getStatus() public String getDisplayName() public String getErrorCode() } |
Methods
getStatus | Gets the status of account deletion. See the deleteAccount method for more information |
getDisplayName | Gets the account display name. |
getErrorCode | Gets the Error code value. |
Class ActivationAcknowledgementResponse
The ActivationAcknowledgementResponse class contains activation acknowledgement details.
An object of this class is sent in the response of the setPin method (during the activation process for a single account). See the setPin (for a single account) method for more information. This is an overloaded method.
A list of objects of this class is sent in the response of the setPin method (during the activation process for multiple accounts). See the setPin (for multiple accounts) method for more information.
Java Code Snippet
public class ActivationAcknowledgementResponse{public String getAccountId() public String getStatus() public String getDisplayName() public String getErrorCode() } |
Methods
getAccountId | Gets the account ID. |
getStatus | Gets the status of account activation. |
getDisplayName | Gets user account display name. |
getErrorCode | Gets the Error code value. |
Class ActivationResponse
The ActivationResponse object contains information about an account. An object of this class is sent in the response of the getAllEnrolledAccounts method.
See the getAllEnrolledAccounts method for more information.
Java Code Snippet
public class ActivationResponse {public String getAccountId() public String getDisplayName() public String getErrorCode() public String getReferenceId() public String getStatus() } |
Methods
getAccountId | Gets the account ID. |
getDisplayName | Gets the user account display name. |
getErrorCode | Gets the Error code value. |
getReferenceId | Gets the reference ID. |
getStatus | Gets the status of account activation. |
Class UpdateAuthenticationResponse
The UpdateAuthenticationResponse class contains information about the results of an Update Authentication Type operation. An object of this class is sent in the response of the updateAuthenticationType method.
See the updateAuthenticationType method for more information.
Java Code Snippet
public class UpdateAuthenticationResponse { public String getStatus() public String getError_code() } |
Methods
getStatus | Gets the status of authentication type update. See the updateAuthenticationType method for more information |
getError_code | Gets the Error code value. |
Class AccountDetails
The AccountDetails contains information about an account. An object of this class is sent in the response of the getAllEnrolledAccounts method.
See the getAllEnrolledAccounts method for more information.
Java Code Snippet
public class AccountDetails {public String getAccountType() public String getAccountId() public String getDisplayName() } |
Methods
getAccountId | Gets the account id value. |
getDisplayName | Gets user account display name. |
getAccountType | Gets the account type value. |
Class OTPResponse
The OTPResponse class contains information about an OTP. An object of this class is sent in the response of the generateOTP method.
See the generateOTP method for more information.
Java code snippet
public class OTPResponse {public String getOtp() public String getStatus() public String getErrorCode() } |
Methods
getOtp | Gets the OTP value. |
getStatus | Gets status of generateOTP method. See the generateOTP method for more information. |
getErrorCode | Gets the Error code value. |
Class VerifyPinResponse
The VerifyPinResponse class contains information about the results of the Verify PIN operation. An object of this class is sent in the response of the verifyPin method.
See the verifyPin method for more information.
Java code snippet
public class VerifyPinResponse {public String getStatus() public String getErrorCode() public String getTransactionId() } |
Methods
getStatus | Gets status of verifyPin method. See the verifyPin method for more information. |
getErrorCode | Gets the Error code value. |
getTransactionId | Gets the transaction ID. |
Class ChangePinResponse
The ChangePinResponse class contains information about the results of the Change PIN operation. An object of this class is sent in the response of the changePin method.
See the changePin method for more information.
Java code snippet
public class ChangePinResponse {public String getStatus() public String getErrorCode() } |
Methods
getStatus | Gets status of changePin method. See the changePin method for more information. |
getErrorCode | Gets errorCode value. |
Class ProfileInfo
The ProfileInfo class contains information about the device.
See the getProfileInfo method for more information.
Java code snippet
public class ProfileInfo {public String getDeviceNickname() public String getDeviceId() public String getStatus() public String getErrorCode } |
Methods
getStatus | Gets status of getProfileInfo method. See the getProfileInfo method for more information. |
getErrorCode | Gets errorCode value. |
getDeviceId | Gets the Device’s profile id value. |
getDeviceNickname | Gets the Device’s Nickname value. |
Class UnenrollmentResponse
The UnenrollmentResponse class contains information about the results of unrolled accounts operation. An object of this class is sent in the response of the unenrollAccounts method.
Code Snippet
public class UnenrollAccountResponse{private List <UnenrollAccountResponse> success = new ArrayList<>();private List <UnenrollAccountResponse> failure = new ArrayList<>();private String status;private String errorCode;private String accountId;private String orgName;private String accountLevelStatus;private String errorMessage;public UnenrollAccountResponse(){}public UnenrollAccountResponse(String errorCode,String status){this.status = status;this.errorCode = errorCode;}public List<UnenrollAccountResponse> getSuccess() {return success;}public void setSuccess(List<UnenrollAccountResponse> success) {this.success = success;}public List<UnenrollAccountResponse> getFailure() {return failure;}public void setFailure(List<UnenrollAccountResponse> failure) {this.failure = failure;}public String getAccountId() {return accountId;}public void setAccountId(String accountId) {this.accountId = accountId;}public String getOrgName() {return orgName;}public void setOrgName(String orgName) {this.orgName = orgName;}public String getAccountLevelStatus() {return accountLevelStatus;}public void setAccountLevelStatus(String accountLevelStatus) {this.accountLevelStatus = accountLevelStatus;}public String getErrorMessage() {return errorMessage;}public void setErrorMessage(String errorMessage) {this.errorMessage = errorMessage;}public String getStatus() {return status;}public void setStatus(String status) {this.status = status;}public String getErrorCode() {return errorCode;}public UnenrollAccountResponse setErrorCode(String errorCode) {this.status = M3DSConstants.FAILURE;this.errorCode = errorCode;return this.getErrorResponse(errorCode,this.status);}public UnenrollAccountResponse getErrorResponse(String errorCode,String status){return new UnenrollAccountResponse(errorCode, status);}}
Properties
Name | Type | Description |
errorcode | String | errorCode that is returned depending on the scenario in which the UnenrollmentResponse object is populated. |
status | String | Specifies whether the Unenrollment Type operation has success or failed. |
success | ArrayList | Contains details of successfully unenrolled accounts. An array of UnenrollmentResponse objects, which contain elements such as, accountId and Orgname. |
failure | ArrayList | Contains details of accounts for which unenrollment failed. An array of UnenrollmentResponse objects, which contain elements such as, accountId, Orgname, errorCode. |
accountId | String | This will be part of successStatusArray or failureStatusArray of UnenrollmentResponse objects, which will have the accountId. |
accountLevelStatus | String | This will be part of the accountLevelStaus, which will contain the individual accountlevel messages. |
errorMessage | String | This will be part of successStatusArray or failureStatusArray of UnenrollmentResponse objects, which will have the errorMessage. |
orgName | String | This will be part of successStatusArray or failureStatusArray of UnenrollmentResponse objects, which will have this orgName. |
Localizing the Biometric Authentication Dialog Text
To localize the text that is displayed on the app for biometric authentication:
The following images show the text that can be localized and the corresponding methods that must be used for the text.