On this page
No Headings
STEP 2 Provide wallet access
Last updated: June 3, 2026
DOCS
The first thing a mobile payments app must do is allow a user to register and access a wallet profile in the WLW platform that is uniquely associated with the device on which the app is installed.
As the flow diagram illustrates, there are three possible paths of access to a wallet once the app launches. This section walks through the steps to implement each of these paths, which invoke endpoints exposed through the security and userregistration packages of the Android SDK.
Note: Mobile app screens shown in this guide are for functional demonstration only and not intended as design recommendations.
1. Validate device status
The first step in providing wallet access through the app is to identify the device on which the app is installed and determine whether or not it is already associated with a wallet on the WLW platform.
Note: You should invoke the device status check every time the app launches, as well as when the app resumes to the foreground after having been in the background. Since it is possible for a device to be deactivated remotely in the case of loss, it is important to always verify that the device is registered and active at the time of use.
IMPLEMENTATION STEPS
- Bind to the UserManagementService.
- Set the UserManagementService listener.
- Invoke
validateDeviceStatus. - Configure callbacks to handle responses and display appropriate next screens.
(1) public ServiceConnection userManagementServiceConnection = new ServiceConnection()
{
@Override
public void onServiceConnected(ComponentName name, IBinder service)
{
userManagementService = ((LocalBinder <IUserManagementService>) service).getService();
(2) if (userManagementService != null)
{
userManagementService.setUserManagementServiceListener(userAdapter);
(3) DeviceInfo deviceInfo = new DeviceInfo();
deviceInfo.setDeviceId(DevicePropertyUtil.retrieveDeviceProperties(getActivity()).get(IDevicePropertyCodes.DEVICE_ID));
deviceInfo.setDeviceTypeName(AppConstants.DEVICE_TYPE);
userManagementService.validateDeviceStatus(deviceInfo);
}
}Based on the results of the device check, display one of two screens:
-
Device is not registered: display the Welcome screen.
The Welcome screen gives the user the option to register a new wallet (Enroll a New Wallet) or to associate an existing wallet with the current device (Login With Username/Password). WLW advises also including operators to allow a user to reset forgotten credentials.
-
Device is registered: display the PIN Login screen (Login With PIN).
(4) protected UserManagementListenerAdapter userAdapter = new UserManagementListenerAdapter()
{
@Override
public void onValidateDeviceStatusSuccess(DeviceState deviceState)
{
Log.v(TAG, "" + deviceState.isRegistered());
if (deviceState.isRegistered())
{
deviceLinked = true;
}
else
{
disableActionItem(getActionItem(R.id.left_button));
disableActionItem(getActionItem(R.id.right_button));
registerPaypalTextView.setVisibility(View.VISIBLE);
registerNewTextView.setVisibility(View.VISIBLE);
forgotPasswordTextView.setVisibility(View.VISIBLE);
forgotPasscodeTextView.setVisibility(View.VISIBLE);
}
}2. Enroll a new wallet
Once the app is determined to be installed on an unregistered device and the user elects to register a new wallet, proceed with the new user enrollment flow.
IMPLEMENTATION STEPS
1. Retrieve MFA security questions
As part of WLW's multi-factor authentication (MFA) protocol, user must provide responses for a predefined number of security questions to be used for secondary identity verification when needed, such as in the case of a forgotten PIN or password.
The wallet issuer configures a pool of security questions from which the user may choose to provide responses for the issuer-designated required number. Retrieve these issuer configurations in order to present them to the user in the enrollment form.
userManagementService.retrieveMfaQuestions();The success response returns the pool of available questions and the number of questions for which the user must provide a response, as well as whether any of the questions is mandatory.
@Override
public void onRetrieveMfaQuestionsSuccess(MFAQuestionList mfaQuestionList)
{
super.onRetrieveMfaQuestionsSuccess(mfaQuestionList);
mfaList = mfaQuestionList;
isMFARetrieved = true;
registerNewUser();
}Use this returned data to facilitate collection of the user's security question responses for use in populating the MfaQuestionAnswers attribute of the createCustomer instance.
2. Retrieve password and PIN requirements
The user enrollment will fail if the PIN and password values submitted by the user do not meet the minimum requirements set by the issuer. Retrieving the set of requirements before you present the enrollment form to the user allows you to advise the user of the requirements beforehand, implement field validation in the app, and preempt such failure.
Note: Password and PIN requirements are retrieved independently using separate methods, as shown in the following sample.
userManagementService.retrievePasswordPolicyConfiguration();
userManagementService.retrievePasscodeConfiguration();
@Override
public void onRetrievePasscodeConfiguration(PasscodeConfiguration passcodeConfiguration)
{
super.onRetrievePasscodeConfiguration(passcodeConfiguration);
/*validate user passcode against policy configuration*/
}
@Override
public void onRetrievePasswordPolicyConfigurationSuccess(PasswordConfiguration passwordConfiguration)
{
super.onRetrievePasswordPolicyConfigurationSuccess(passwordConfiguration);
Log.v(TAG, "min length" + passwordConfiguration.getPasswordMinLength() + " " + "max length" + passwordConfiguration.getPasswordMaxLength());
/*validate user password against policy configuration*/
}3. Present enrollment form to user
Once you have retrieved all the relevant data about required registration values and configuration settings, display a registration form to collect the corresponding input from the user.
4. Submit the registration profile
Once all the relevant profile data has been collected and mapped to the corresponding fields, build the CreateCustomer class.
CreateCustomer createCustomer = new CreateCustomer();
createCustomer.setFirstName(AppConstants.USER_FIRST_NAME);
createCustomer.setLastName(AppConstants.USER_LAST_NAME);
createCustomer.setEmail(AppConstants.EMAIL);
createCustomer.setPassword(AppConstants.PASSWORD);
createCustomer.setConfirmPassword(AppConstants.PASSWORD);
createCustomer.setPasscode(AppConstants.PASSCODE);
createCustomer.setConfirmPasscode(AppConstants.PASSCODE);
createCustomer.setPhone(AppConstants.PHONE);
createCustomer.setMfaQuestionAnswers(getMfaAnswers(mfaList));When the CreateCustomer object is populated with the user's input values, invoke the registration call.
userManagementService.registerUser(createCustomer);5. Authenticate the user and register the device
The registration success response returns the CreatedCustomer object containing a temporary, one-time nonce value. Configure the callback to invoke loginByNonce using that value to seamlessly authenticate the user and complete the device-wallet association.
Note: The nonce value specifies a time-to-live property. If the loginByNonce call is not invoked within that limit, the call will fail.
public void onRegisterUserSuccess(final CreatedCustomer createdCustomer)
{
super.onRegisterUserSuccess(createdCustomer);
Log.v(TAG, "User register Success");
AlertDialog.Builder alert = new AlertDialog.Builder(LoginActivity.this);
alert.setMessage(getString(R.string.register_success));
alert.setPositiveButton(getString(R.string.button_label_ok), new DialogInterface.OnClickListener()
{
@Override
public void onClick(DialogInterface dialog, int which)
{
loginByNonce(createdCustomer.getNonce());
Log.v(TAG, "Nonce=" + createdCustomer.getNonce());
}
});
alert.show();
}
private void loginByNonce(String nonce)
{
DeviceSecurityProfile deviceSecurityProfile = new DeviceSecurityProfile();
deviceSecurityProfile.setNonce(nonce);
/*use this constructor for Device : Device(final ContextWrapper contextWrapper)*/
device = new Device(this);
deviceSecurityProfile.setDevice(device);
userLoginService.loginByNonce(deviceSecurityProfile);
}This completes the new wallet registration path for accessing a mobile wallet through the app.
Note: If email verification is enabled, you cannot use the login by nonce method. The user must complete the email verification and then login by username/password in order to complete the device-wallet link.
3. Login with Username/Password
Logging into the app with the username and password credentials is typically triggered in the following use cases:
- The user already has a wallet account, but is accessing it for the first time on a new (unregistered) device.
- The user has previously unlinked the existing wallet account from the current device and must re-associate the device with the wallet account.
- the user just completed a new registration that required email verification and therefore could not invoke loginByNonce for the first authentication.
- The device is already linked to an existing mobile wallet, but the wallet issuer does not support Login By PIN (this is not common).
In the first three use cases, the device does not yet have a recognized association with an existing account. Therefore, successful login will trigger the multi-factor authentication flow in order to verify the user's identity and associate the device with the wallet.
IMPLEMENTATION STEPS
1. Invoke Username & Password login
When the device status check reveals that the app is not registered with the device, and the user chooses Login from the Welcome screen, it is typically because the user already has a wallet, it is just not currently associated with the device. The user may have unlinked the wallet from the device or may have gotten a new phone.
In any case, display the Username & Password Login screen and pass the user's input values in the loginWithUsernamePassword call.
First, define the service connection and configure the onServiceConnected callback to initialize the UserLoginService.
private UserLoginService userLoginService;
public ServiceConnection userLoginServiceConnection = new ServiceConnection()
{
@Override
public void onServiceDisconnected(ComponentName name)
{
userLoginService = null;
}
@Override
public void onServiceConnected(ComponentName name, IBinder service)
{
userLoginService =
((LocalBinder <UserLoginService> ) service).getService();
if (userLoginService != null)
{
userLoginService.setUserLoginListener(loginAdapter);
}
}
};Next, bind the service connection.
Intent serviceIntent = new Intent(this, UserLoginService.class);
bindService(serviceIntent, userLoginServiceConnection, BIND_AUTO_CREATE);Finally, collect the users' input credentials and build a deviceSecurityProfile instance and pass it with the login request.
UserCredentials userCredentials = new UserCredentials(email, AppConstants.PASSWORD);
DeviceSecurityProfile deviceSecurityProfile = new DeviceSecurityProfile();
deviceSecurityProfile.setUserCredentials(userCredentials);
Device device=new Device();
deviceSecurityProfile.setDevice(device);
userLoginService.loginWithUsernamePassword(deviceSecurityProfile);2. Invoke MFA authentication
When a user successfully logs into an existing wallet from an unregistered device, the platform returns the onPromptMfa callback with the 412 status code and a randomly selected question from the set of security questions for which the user has previously provided responses.
Configure this callback to prompt the user to input the answer to the question and then populate the question and response values in an instance of the deviceSecurityProfile object. Then re-call loginWithUsernamePassword, passing the updated device profile instance.
@Override
public void onPromptMFA(String question)
{
super.onPromptMFA(question);
Log.v(TAG, "MFA Prompt");
submitMFA(question, AppConstants.MFA_ANSWER);
}
private void submitMFA(String mfaQuestion, String mfaAnswer)
{
DeviceSecurityProfile deviceSecurityProfile = new
DeviceSecurityProfile();
QuestionAndAnswer questionAndAnswer = new QuestionAndAnswer();
questionAndAnswer.setSecurityQuestion(mfaQuestion);
questionAndAnswer.setSecurityAnswer(mfaAnswer);
deviceSecurityProfile.setUserCredentials(userCredentials);
deviceSecurityProfile.setQuestionAndAnswer(questionAndAnswer);
deviceSecurityProfile.setDevice(device);
userLoginService.loginWithUsernamePassword(deviceSecurityProfile);
}4. Login with PIN
Display the PIN login screen when the device is associated with an existing wallet account and PIN login is supported by the issuer. Pass the user's input values in the loginWithPin call.
UserCredentials userCredentials = new UserCredentials(AppConstants.PASSCODE);
DeviceSecurityProfile deviceSecurityProfile = new DeviceSecurityProfile();
deviceSecurityProfile.setUserCredentials(userCredentials);
Device device=new Device();
deviceSecurityProfile.setDevice(device);
userLoginService.loginWithPin(deviceSecurityProfile);5. Logout
It is important to provide a means for the user to explicitly logout, if desired.
The WLW platform automatically terminates an app session after a maximum duration of inactivity specified by the wallet issuer. Some apps allow the user to set a preference for session timeout that is less than the default issuer timeout. In such cases, the app must invoke the logout method upon expiration of the user-specified timeout. Otherwise, the session will remain active until the issuer-configured timeout expires.
- Define a Logout operator on the app Home screen.
- Instantiate the userLogoutService.
- Invoke the SDK logout method upon activation of operator.
- Configure Success and Failure callbacks to handle server response.
(1) @Override
protected void onCreate(Bundle savedInstanceState)
{
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_home);
setUpActionBar();
setLeftButtonText(getString(R.string.action_unlink));
setRightButtonText(getString(R.string.text_logout));
progressBar = (ProressBar) findViewById(R.id.progressBar);
View.OnClickListener onClickListener = new View.OnClickListener()
{
@Override
public void onClick(View v)
{
Intent intent;
if (v.getId() == R.id.wallet_btn)
{
intent = new Intent(HomeActivity.this, MyWalletActivity.class);
startActivity(intent);
...
}
else
if (v.getId() == R.id.right_button)
{
(2) userLogoutService.setLogoutListener(userLogoutListener);
(3) userLogoutService.logout();
progressBar.setVisibility(View.VISIBLE);
disableActionItem(getActionItem(R.id.right_button));
}
}
(4) IUserLogoutListener userLogoutListener = new IUserLogoutListener()
{
@Override
public void onLogoutSuccess()
{
Log.v(TAG, "USER LOGGED OUT SUCCESSFULLY ");
progressBar.setVisibility(View.INVISIBLE);
Intent intent = new Intent(HomeActivity.this, LoginActivity.class);
startActivity(intent);
HomeActivity.this.finish();
}
@Override
public void onLogoutError(PaydiantException e)
{
Log.v(TAG, "USER LOGGED OUT ERROR ");
progressBar.setVisibility(View.INVISIBLE);
}
};Tip: Ensure that any sensitive data retrieved by the app is cleared from the app's memory cache when the logout method is invoked.
6. Unlink a device
Occasionally, users have reason to divorce a device's association with a particular mobile wallet account. Since a device can only be associated with one mobile wallet account (for a specific issuing partner), a user must disassociate a device from the wallet to which it is currently registered in order to link it to a different account.
private void unLinkDevice()
{
if (unlinkDeviceService != null)
{
DeleteDevice deleteDevice = new DeleteDevice();
deleteDevice.setDeviceId(DevicePropertyUtil.retrieveDeviceProperties(this).get(IDevicePropertyCodes.DEVICE_ID));
deleteDevice.setDeviceTypeName(ApplicationProperties.DEVICE_TYPE);
unlinkDeviceService.unlinkDevice(deleteDevice);
progressBar.setVisibility(View.VISIBLE);
}
}