Android SDK - Security Module

The security module of the SDK encompasses all functionality that relates to the manner in which a user gains access to the mobile wallet through the app.

Item Description
UI Services com.paydiant.android.ui.service.security.UserLoginServicecom.paydiant.android.ui.service.security.UnlinkDeviceService
Core com.paydiant.android.core.facade.SecurityManagerFacade

For the logout or unlink device methods, you may alternatively use the com.paydiant.android.core.facade.SecurityManagerFacade#SecurityManagerFacade(ISecurityManagerService)constructor.

Set UI Package Security Service Listeners

To invoke the callback methods returned by the Paydiant service in response to the methods invoked by the security module of the SDK, the developer must set an implementation of the applicable listener interfaces in the UI Services class.

Item Description
Set Login Listener void setUserLoginListener (IUserLoginListenerlistener);
com.paydiant.android.ui.service.security.IUserLoginListener
or
com.paydiant.android.ui.service.security.IUserLoginExtendedListener
or
an overridden instance of com.paydiant.android.ui.service.security.UserLoginListenerAdapter
Set Logout Listener void setUserLogoutListener(IUserLogoutListener listener);brcom.paydiant.android.ui.service.security.IUserLogoutListener
or
an overridden instance of com.paydiant.android.ui.service.security.UserLogoutListenerAdapter
Set Unlink Listener void setUnlinkDeviceListener(IUnlinkDeviceListener listener);brcom.paydiant.android.ui.service.security.IUnlinkDeviceListener
or
an overridden instance of com.paydiant.android.ui.service.security.UnlinkDeviceListenerAdapter
Remove Listener void removeListener();

Call this method from within the corresponding service class in order to remove the associated listener and set it to null.

Security Module Events

The security module methods use a generic exception populated with a specific eventCode to identify the method during which the error occurred. Error code definitions for this module vary by event, so developers should handle these errors individually for each specific event.

Security Events
LOGIN_BY_USERNAME_PASSWORD_EVENT
LOGIN_BY_PIN_EVENT
LOGIN_BY_NONCE_EVENT
LOGIN_BY_FEDERATED_IDENTITY_EVENT
CHECK_LONG_LIVE_SESSION_EVENT
GENERATE_DEVICE_AUTH_TOKEN_EVENT
LOGIN_BY_DEVICE_AUTH_TOKEN_EVENT
EXPIRE_AUTH_TOKEN_EVENT

Login with Email and Password

Authenticates the identity of the user based on the email address and password set at the time wallet registration.

UI implementation

Item Description
UI Method void loginWithUsernamePassword(DeviceSecurityProfile deviceSecurityProfile);

deviceSecurityProfile - An instance of the object that identifies the device as it is associated with the username (email address) and password for the registered wallet.
Success The login method can invoke one of the following two possible success callbacks. Implement only one or the other to handle the login method response. Do not implement both.

void onSuccess ();
Implement this standard callback to handle the success response from the server and invoke the relevant next steps, such as launching the welcome screen of the app, obtaining profile or account data, or other actions.

void onSuccess (Map < String, String > additionalAttributes);
Implement this overloaded callback to request additional details relevant to the authentication that may mitigate a different result in the app. For example, if the last login date was more than a specified amount of time ago, you may force a password change or display an incentive coupon.

additionalAttributes - An instance of the object that defines, as key/value pairs, the attributes for which the app is requesting values.
Failure The login method can invoke one of the following three possible failure callbacks. Implement all three to handle different failure scenarios as described here.

void onFailed:();
Implement this callback to handle responses in which the credentials passed with the method failed to authenticate the user.

void onError (PaydiantException e);
Implement this callback to handled responses where the call is unable to reach the Paydiant server and therefore cannot be processed.

void onPromptMFA(String question);
Implement this callback to handle responses where multi-factor authentication (MFA) is enabled by the issuer. The SDK will invoke this callback when the credentials are correct, but the device is not recognized as associated with the wallet being logged-into. Prompt the user to enter the previously configured response to the passed question and set the QuestionAndAnswer value in the deviceSecurityProfile domain object, then recall the login method, passing the deviceSecurityProfile object as a parameter.

question - A randomly selected MFA question that the user answered during registration.
Core Method String loginByUsername(DeviceSecurityProfile deviceSecurityProfile);

deviceSecurityProfile - an instance of the object that identifies the device as it is associated with the username (email address) and password for the registered wallet.

Returns
True = successful login
False= login failure

Note: To obtain additional attribute values when using the core package, invoke the following core method immediately following a successful login:
public Map < String, String > getAdditionalAttributes();

Errors

The following errors are relevant responses for the login method:

Error Description
401 An incorrect username or password has been entered.
412 The device from which the login is attempted is not linked to a mobile wallet. Invoke onPromptMfa callback.
418 Login failed because email verification is incomplete.
424 The application signature of the mobile wallet is not valid.
426 The application or SDK version is out of date and an update is required.
503 This device has been suspended.
511 Application Instance verification required.

Login with PIN

Authenticates the identity of the user based on an input passcode (PIN) set for the wallet associated with the device. This login option is only applicable when the wallet has already been linked to the current device.

Item Description
UI Method void loginWithPin(DeviceSecurityProfile deviceSecurityProfile);

deviceSecurityProfile - an instance of the object that identifies the device as it is associated with the PIN for the registered wallet.
Success The login method can invoke one of the following two possible success callbacks. Implement only one or the other to handle the login method response. Do not implement both.

void onSuccess ();
Implement this standard callback to handle the success response from the server and invoke the relevant next steps, such as launching the welcome screen of the app, obtaining profile or account data, or other similar events.

void onSuccess (Map < String, String > additionalAttributes);
Implement this overloaded callback to request additional details relevant to the authentication that may mitigate a different result in the app. For example, if the last login date was more than a specified amount of time ago, you may force a PIN update or display an incentive coupon.

additionalAttributes - An instance of the object that defines, as key/value pairs, the attributes for which the app is requesting values.
Failure The login method can invoke one of the following two possible failure callbacks. Implement both to handle different failure scenarios as described here.

void onFailed:();
Implement this callback to handle responses in which the credentials passed with the method failed to authenticate the user.

void onError (PaydiantException e);
Implement this callback to handled responses where the call is unable to reach the Paydiant server and therefore cannot be processed.
Core Method String loginWithPin(DeviceSecurityProfiledeviceSecurityProfile deviceSecurityProfile);

deviceSecurityProfile - an instance of the object that identifies the device as it is associated with the user credentials for the registered wallet.

Returns
True = successful login
False= login failure

Note: To obtain additional attribute values when using the core package, invoke the following core method immediately following a successful login:
public Map < String, String > getAdditionalAttributes();

Errors

The following errors are relevant responses for the login method:

Error Description
401 An incorrect username or password has been entered.
418 Login failed because email verification is incomplete.
424 The application signature of the mobile wallet is not valid.
426 The application or SDK version is out of date and an update is required.
503 This device has been suspended.
511 Application Instance verification required.

Login with Nonce

Paydiant’s SSO framework allows issuers to leverage the existing user profiles in their own systems to streamline the registration process for their mobile payments platform integration.

When a new mobile payments registration is created through the SSO framework, the call returns a one-time nonce token that must be passed during the first login attempt in order for Paydiant to register the device with the Paydiant service and establish SSO authentication through the IDP.

Once the device association is complete, subsequent logins can be handled using Paydiant’s standard login calls.

Item Description
UI Method void loginByNonce(DeviceSecurityProfile deviceSecurityProfile);

deviceSecurityProfile - an instance of the object that identifies the device as it is associated with the security credentials for the registered wallet. For this method, populate the nonce attribute with the value returned during customer registration.
Success Implement one of the callbacks below to handle the success response from the server and invoke the relevant next steps (for example, launching the welcome screen of the app, obtaining profile or account data, or other similar events) depending on the specific issuer configration.

void onPromptMFA (DeviceSecurityProfile deviceSecurityProfile);
Implement the preceding callback to handle responses where the login credentials were successful, but MFA is enabled by the issuer.

void onSuccess ();
Implement this standard callback if MFA is not enabled and no additional attributes are requested.

void onSuccess (Map < String, String > additionalAttributes);
Implement this overloaded callback if MFA is not enabled, but additional details relevant to the authentication are relevant. For example, if the last login date was more than a specified amount of time ago, you may force a PIN update or display an incentive coupon.

deviceSecurityProfile - an instance of the object that provides information about the user profile, including the QuestionAndAnswer class that passes the security question that the user is expected to answer. Once answered, the app should populate mfaAnswer property of the QuestionAndAnswer class and pass it with submitMfa request.
additionalAttributes - an instance of the object that defines, as key/value pairs, any additional attributes for which the app is requesting values.
Failure The login method can invoke one of the following two possible failure callbacks. Implement both to handle different failure scenarios as described here.

void onFailed:();
Implement this callback to handle responses in which the credentials passed with the method failed to authenticate the user.

void onError (PaydiantException e);
Implement this callback to handled responses where the call is unable to reach the Paydiant server and therefore cannot be processed.
Core Method public DeviceSecurityProfile loginByNonce (DeviceSecurityProfile deviceSecurityProfile);

deviceSecurityProfile - an instance of the object that identifies the device as it is associated with the security credentials for the registered wallet. For this method, populate the nonce attribute with the value returned during customer registration.

Returns raw output of theDeviceSecurityProfile instance or relevant exception.

Note: To obtain additional attribute values using the core package, invoke the following core method immediately following a successful login: public Map < String, String > getAdditionalAttributes();

Errors

The following errors are relevant responses when logging in with a nonce.

Error Description
401 An incorrect username or password has been entered.
418 Login failed because email verification is incomplete.
421 Wallet is deactivated due to consecutive failed login attempts.
423 Device is deactivated due to consecutive failed login attempts.
424 The application signature of the mobile wallet is not valid.
426 The application SDK version is out of date and an update is required.
500 An internal server error has occurred.
503 This device has been suspended.
511 Application Instance verification required.

Login by Federated ID

When a user profile already exists in an external identity provider (IDP) that has implemented Paydiant’s SSO framework, the mobile app can use the pass-through login credentials from the IDP to establish a federated login with the mobile payments app. The first login through the mobile payments app needs to pass the IDP authorization code in order for Paydiant to associate the device.

Thereafter, subsequent logins can continue to use the federated username and password login or can use Paydiant’s Login with PIN method, if PIN login is enabled by the issuer.

Item Description
UI Method void loginByFederatedIdentity(DeviceSecurityProfile deviceSecurityProfile);

deviceSecurityProfile - an instance of the object that identifies the device as it is associated with the security credentials for the registered wallet. For this method, populate the identityProvider and authorizationCode attributes with values obtained from the IDP (outside of Paydiant’s SDK).
Success Implement one of the callbacks below to handle the success response from the server and invoke the relevant next steps (for example, launching the welcome screen of the app, obtaining profile or account data, and other similar events) depending on the specific issuer configuration.

void onPromptMFA (DeviceSecurityProfile deviceSecurityProfile);
Implement the preceding callback to handle responses where the login credentials were successful, but multi-factor authentication (MFA) is enabled by the issuer.

void onSuccess ();
Implement this standard callback if MFA is not enabled and no additional attributes are requested.

void onSuccess (Map < String, String > additionalAttributes);
Implement this overloaded callback if MFA is not enabled, but additional details relevant to the authentication are relevant. For example, if the last login date was more than a specified amount of time ago, you may force a PIN update or display an incentive coupon.

deviceSecurityProfile - an instance of the object that provides information about the user profile, including the QuestionAndAnswer class that passes the security question that the user is expected to answer. Once answered, the app should populate mfaAnswer property of the QuestionAndAnswer class and pass it with submitMfa request.
additionalAttributes - an instance of the object that defines, as key/value pairs, any additional attributes for which the app is requesting values.
Failure The login method can invoke one of the following three possible failure callbacks. Implement all three to handle different failure scenarios as described below.

void onFailed:();
Implement this callback to handle responses in which the credentials passed with the method failed to authenticate the user.

void onError (PaydiantException e);
Implement this callback to handled responses where the call is unable to reach the Paydiant server and therefore cannot be processed.
Core Method public DeviceSecurityProfile loginByFederatedIdentity (DeviceSecurityProfile deviceSecurityProfile);

deviceSecurityProfile - an instance of the object that identifies the device as it is associated with the security credentials for the registered wallet. For this method, populate the nonce attribute with the value returned during customer registration.

Returns raw output of the DeviceSecurityProfile instance or relevant exception.

Note: To obtain additional attribute values using the core package, invoke the following core method immediately following a successful login:
public Map < String, String > getAdditionalAttributes();

Errors

The following errors are relevant responses when logging in with a nonce.

Error Description
401 An incorrect username or password has been entered.
421 Wallet is deactivated due to consecutive failed login attempts.
423 Device is deactivated due to consecutive failed login attempts.
424 The application signature of the mobile wallet is not valid.
426 The application SDK version is out of date and an update is required.
500 An internal server error has occurred.
503 This device has been suspended.
511 Application Instance verification required.

Login with Device Authentication Token

When long-running sessions is enabled, invoke this method after successful device authentication to access the wallet using the authentication token.

Item Description
UI Method void loginByDeviceAuthToken();
Success void onLoginByDeviceAuthToken(boolean status);
Failure void onFailed();
Implement this callback to handle responses in which the credentials passed with the method failed to authenticate the user.

void onError(PaydiantException e);
Implement this callback to handled responses where the call is unable to reach the Paydiant server and therefore cannot be processed.
Core Method public boolean loginByDeviceAuthToken();

Returns a boolean value of true if the log in attempt was successful and false if the log in attempt was not successful.

Errors

The following errors are relevant responses when logging in with a device authentication token.

Error Description
401 An incorrect username or password has been entered.
421 Wallet is deactivated due to consecutive failed login attempts.
423 Device is deactivated due to consecutive failed login attempts.
500 An internal server error has occurred.
1062 The login method was called but there was no authentication token for the device.

Expire Device Authentication Token

If a user disables device-level authentication such as Touch ID for the app, invoke this method to expire the device authentication token and revert to one of the standard login methods. If the user then re-enables device authentication, you must generate a new token.

Item Description
UI Method void expireDeviceAuthToken();
Success void onExpireDeviceAuthToken(boolean status);
Failure void onFailed:();
Implement this callback to handle responses in which the credentials passed with the method failed to authenticate the user.

void onError (PaydiantException e);
Implement this callback to handled responses where the call is unable to reach the Paydiant server and therefore cannot be processed.
Core Method public boolean expireDeviceAuthToken();

Returns true - if the current device authentication token successfully expired and false - if the current device authentication token did not successfully expire.

Errors

The following errors are relevant responses when expiring a device authentication token.

Error Description
400 Cannot process the request due to a syntactical error.
500 An internal server error has occurred.
1062 The expire token method was called but there was no authentication token for the device.

Generate Device Authentication Token

If the app will support device-level authentication such as Touch ID, invoke this method, passing the user’s standard login credentials in the request, to enable a long lived session and generate a device-specific authentication token. The token is managed within the SDK layer, which retrieves and passes it as a parameter of the Login with Device Authentication Token call, enabling access to the app.

Note: Paydiant does not enable or implement Touch ID, or any other device-level user authentication. Rather, the long lived session provides access to the app based solely on the device recognition. It is up to the developer to ensure the user authentication is secured before invoking the corresponding login method.

Item Description
UI Method void generateDeviceAuthToken(DeviceSecurityProfile deviceSecurityProfile);

deviceSecurityProfile - an instance of the object that identifies the device as it is associated with the security credentials for the registered wallet.
Success void onGenerateDeviceAuthToken(DeviceSecurityProfile deviceSecurityProfile);

deviceSecurityProfile - an instance of the object that identifies the device as it is associated with the security credentials for the registered wallet.
Failure void onFailed:();
Implement this callback to handle responses in which the credentials passed with the method failed to authenticate the user.

void onError (PaydiantException e);
Implement this callback to handled responses where the call is unable to reach the Paydiant server and therefore cannot be processed.
Core Method public DeviceSecurityProfile generateDeviceAuthToken(deviceSecurityProfile deviceSecurityProfile);

deviceSecurityProfile - an instance of the object that identifies the device as it is associated with the security credentials for the registered wallet.

Returns deviceSecurityProfile - an instance of the object that identifies the device as it is associated with the security credentials for the registered wallet.

Errors

The following errors are relevant responses when generating a device authentication token.

Error Description
400 Cannot process the request due to a syntactical error.
401 An incorrect username or password has been entered.
500 An internal server error has occurred.

Check Device Authentication Status

If the mobile wallet app supports device-level authentication such as Touch ID, invoke this simple boolean call to determine whether a Device Authentication token is already active for the device.

Item Description
UI Method void isAuthorizationTokenExist();
Success void onIsLongLivedSessionEnabled(boolean status);
Failure void onFailed:();
Implement this callback to handle responses in which the credentials passed with the method failed to authenticate the user.

void onError (PaydiantException e);
Implement this callback to handled responses where the call is unable to reach the Paydiant server and therefore cannot be processed.
Core Method public boolean isAuthorizationTokenExist();

Errors

The following errors are relevant responses when checking the device authentication status.

Error Description
401 An incorrect username or password has been entered.
421 Wallet is deactivated due to consecutive failed login attempts.
423 Device is deactivated due to consecutive failed login attempts.
424 The application signature of the mobile wallet is not valid.
426 The application SDK version is out of date and an update is required.
500 An internal server error has occurred.
503 This device has been suspended.
511 Application Instance verification required.

Logout

Terminates the active user session with the app.

Item Description
UI Method void logout();
Success void onLogoutSuccess();
Failure void onLogoutFailure:();
void onError (PaydiantException e);
Core Method void logout();

Returns
True = successful login
False= login failure

Errors

The following errors are relevant responses for the logout method:

Error Description
500 An unknown server error has occurred.

Provides the functionality to break a previously registered device’s association with the wallet, leaving it free to register with a different wallet.

Item Description
UI Method void unlinkDevice(DeleteDevice deleteDevice);
Success void onUnlinkDeviceSuccess();
Failure void onUnlinkDeviceError (PaydiantException e);
Core Method boolean deleteDevice(DeleteDevice device);

Returns
True = successful login
False= login failure

Errors

The following errors are relevant responses when unlinking the device with an associated wallet:

Error Description
500 An unknown server error has occurred.

Other Resources

javadocs