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.

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

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.

Errors

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.

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.

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.

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.

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.

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.

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.