STEP 2 Provide wallet access

Before any mobile payments can happen, a user must first be able to register and access a wallet profile in the Paydiant platform that is uniquely associated with the device on which the app is installed.

Access Wallet Flow

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 Device Coordinator, the User Enrollment Coordinator, and the Authentication Coordinator of the SDK.

Note: Mobile app screens shown in this guide are for functional demonstration only and not intended as design recommendations.

1. Check 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 Paydiant 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

  1. Initialize the Device Management facade.

  2. Invoke isDeviceRegistered.

        - (void)verifyDeviceIsRegistered {
     
            [CommonUtil showProgressindicatorOnView:self]
         
     (1)    PDDeviceCoordinator *deviceCoordinator = [PDDeviceCoordinator new];
     
     (2)    [deviceCoordinator isDeviceRegistered:^(BOOL isRegistered, BOOL isActive) {
                [CommonUtil hideProgressIndicatorOnView:self];
                [self updateViewAccordingToDeviceRegistrationStatus:isRegistered activationStatus:isActive];
         
                // Device register status check successful.
                if (isRegistered == NO) {
                    self.registerBTN.hidden = NO;
                    self.loginBTN.hidden = NO;
                }
         
            } failureBlock:^(PDPaydiantError *deviceManagementError) {
                [CommonUtil hideProgressIndicatorOnView:self];
                [CommonUtil displayError:deviceManagementError];
                self.isRegistered = NO;
                self.isActive = NO;
            }];
        }    
     

Based on the results of the device check, display one of two screens:

  • Device is not registered: display the Welcome screen.

    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 By Username/Password). Paydiant advises also including operators to allow a user to reset forgotten credentials.

  • Device is registered: display the PIN Login screen (Login By PIN).

    PIN Login Screen

- (void)updateViewAccordingToDeviceRegistrationStatus:(BOOL)deviceRegisterdStatus activationStatus:(BOOL)deviceActivationStatus {

    AppDelegate *appDelegate = (AppDelegate*) [[UIApplication sharedApplication] delegate];
    BOOL loginStatus = [appDelegate isLoggedIn];
    self.registrationButton.enabled = !deviceRegisterdStatus;
    self.deviceUnlinkButton.enabled = deviceRegisterdStatus && !loginStatus;
    if ((deviceRegisterdStatus == deviceActivationStatus) && !loginStatus) {
        self.loginButton.enabled = YES;
    }
    else if ((deviceRegisterdStatus && !deviceActivationStatus )|| loginStatus) {
        self.loginButton.enabled = NO;
    }
}

2. Enroll a new wallet

Once the app is identified as 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.
  2. Retrieve the password and PIN minimum requirements.
  3. Present the user with the enrollment form.
  4. Submit the registration profile.
  5. Authenticate the user and register the device.

1. Retrieve MFA Security Questions

As part of Paydiant's multi-factor authentication (MFA) protocol, the 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.

Note: Be sure to initialize the User Enrollment facade before invoking the call to identify the calling service and ensure proper response handling.

- (void)retreiveMFAQuestions {

    PDUserEnrollmentCoordinator *userEnrollmentCoordinator = [[PDUserEnrollmentCoordinator alloc] init];
    [userEnrollmentCoordinator retrieveMFAQuestionsWithMetadata:^(PDRetrieveMFAQuestionsWithMetadataResponse *response) {
        self.mfaQuestionsAndAnswers = [NSMutableDictionary dictionary];
        for (NSString *question in response.mfaQuestions) {
            [self.mfaQuestionsAndAnswers setObject:kMFA forKey:question];
        }
    } failureBlock:^(PDPaydiantError *userEnrollmentError) {
         [CommonUtil hideProgressIndicatorOnView:self];
         [CommonUtil displayError:userEnrollmentError];
     }];
}

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.

Use this returned data to facilitate collection of the user's security question responses for use in populating the userProfile.mfaQuestionAnswers value.

2. Retrieve PIN and password 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 prevent such failure.

Note: Password and PIN requirements are retrieved independently using separate methods, as shown in the following sample.

- (void)retrievePasswordConfigurations {

    PDUserEnrollmentCoordinator *userEnrollmentCoordinator = [PDUserEnrollmentCoordinator new];
    [userEnrollmentCoordinator retrievePasswordConfigurations:^(PDUserPasswordConfigurations *userPasswordConfigurations) {
        self.userPasswordConfigurations = userPasswordConfigurations;
    } failureBlock:^(PDPaydiantError *userEnrollmentError) {
    }];
    [userEnrollmentCoordinator retrievePasscodeConfigurations:^(PDUserPasscodeConfigurations *userPasscodeConfigurations) {
        self.userCodeConfigurations = userPasscodeConfigurations;
    } failureBlock:^(PDPaydiantError *userEnrollmentError) {
    }];
}

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.

Register User Screen

4. Submit the registration profile

Once all the relevant profile data has been collected and mapped to the corresponding fields, build the userProfile object.

- (IBAction)registerClicked:(id)sender {
    [CommonUtil showProgressIndicatorOnView:self];

    PDUserProfile *userProfile = [PDUserProfile new];
    userProfile.firstName = @"Paydiant";
    userProfile.lastName = @"User";
    userProfile.email = kUSER_NAME;
    userProfile.password = kPwd;
    userProfile.confirmPassword = kPwd;
    userProfile.passcode = kPin;
    userProfile.confirmPasscode = kPin;
    userProfile.phone = @"1234567890";
    userProfile.mfaQuestionAnswers = self.mfaQuestionsAndAnswers;

When the userProfile object is populated with the user's input values, invoke the registration call.

Note: Initialize the User Enrollment facade prior to invocation to ensure proper response handling.

PDUserEnrollmentCoordinator *userEnrollment = [[PDUserEnrollmentCoordinator alloc] init];
userProfile.additionalCustomerInformation = [NSDictionary dictionaryWithObjectsAndKeys:@"key", @"value", nil];
PDRegisterUserRequest *request = [PDRegisterUserRequest new];
request.userProfile = userProfile;

5. Authenticate the user and register the device

Configure the registration completion block to invoke the loginByNonce method, using the temporary, one-time nonce value returned in the response to seamlessly authenticate the user and complete the device-walet association.

Note: You must initialize the Authentication facade before calling the login method.

[userEnrollment registerNewUser:request
    completionBlock: ^(PDRegisterUserResponse *response) {
        [CommonUtil hideProgressIndicatorOnView:self];
        [CommonUtil displayMessageWithTitle:@"Success" andDescription:response.message];
        self.loginBTN.hidden = NO;
        self.forgotPasswordBTN.hidden = NO;
        self.forgotPasscodeBTN.hidden = NO;
        self.registerBTN.hidden = YES;
        self.registerPyPLBTN.hidden = YES;
        PDLoginByNonceRequest *request = [PDLoginByNonceRequest new];
        request.nonce = [NSString stringWithString:response.nonce];
        [self.authenticationCoordinator loginByNonce:request];
    } failureBlock: ^(PDPaydiantError *userEnrollmentError) {
        [CommonUtil hideProgressIndicatorOnView:self];
        [CommonUtil displayError:userEnrollmentError];
    }];
}

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 By 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 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 two use cases, the device does not 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.

MFA Screen Flow

IMPLEMENTATION STEPS

  1. Invoke Username & Password login
  2. Invoke MFA authentication
  3. Register the device

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 the user may have gotten a new phone.

In any case, display the Login By Username & Password screen and pass the user's input values in the loginByUsernamePassword call.

Note: Initialize the Authentication facade before calling the login method.

- (IBAction)loginClicked:(id)sender {
    [CommonUtil showProgressIndicatorOnView:self];
    [self.authenticationCoordinator loginByUsernamePassword:kUSER_NAME
                                                   password:kPwd];
    }
- (void)authenticationCoordinator:(PDAuthenticationCoordinator *)authenticationCoordinator authenticationDidSucceed:(PDLoginResponse *)loginResponse {
    [self authenticationDidSucceed:authenticationCoordinator];
}
- (void) authenticationDidSucceed:(PDAuthenticationCoordinator *)authenticationCoordinator {
    [CommonUtil hideProgressIndicatorOnView:self];
    self.loginBTN.hidden = YES;
    self.registerBTN.hidden = YES;
    self.UnlinkBarBTN.enabled = YES;
    self.logoutBarBTN.enabled = YES;
    self.walletBTN.hidden = NO;
    [self whatIsInMyWallet];
    [self loyalityProgram];
}
- (void)authenticationCoordinator:(PDAuthenticationCoordinator *)authenticationCoordinator authenticationInvocationDidFail:(PDPaydiantError *)authenticationError {
    [CommonUtil hideProgressIndicatorOnView:self];
    [CommonUtil displayError:authenticationError];
}
- (void)authenticationCoordinator:(PDAuthenticationCoordinator *)authenticationCoordinator authenticationDidFail:(PDPaydiantError *)authenticationError {
    [CommonUtil hideProgressIndicatorOnView:self];
    if (authenticationError.statusCode == 401) {
        [CommonUtil displayErrorMessageForCustomErrorCode:@"PASSCODE_401" usingError:authenticationError];
    }
    else {
        [CommonUtil displayError:authenticationError];
    }
}

2. Invoke MFA authentication

When a user successfully logs into an existing wallet from an unregistered device, the platform returns the mfaQuestionDidPrompt delegate with the 412 status code.

Configure this Authentication delegate within the loginByUsernamePassword call to prompt the user to input a response to the randomly selected secret question passed in the delegate. This will be one of the questions to which the user provided answers during registration.

MFA Prompt Screen

- (void)authenticationCoordinator:(PDAuthenticationCoordinator *)authenticationCoordinator mfaQuestionDidPrompt:(PDMFAToken *)mfaQuestionToken {
    [CommonUtil hideProgressIndicatorOnView:self];
    [self promptMFAQuestionFromToken:mfaQuestionToken];
}

3. Register the device

Once the user has input the secret question answer, use it to populate the mfaSecretAnswer attribute of the mfaQuestionToken object originally passed with the MFA delegate. Invoke the registerWithMfa method, passing the populated mfaQuestionToken, to complete the device-wallet association.

#pragma mark - Prompt MFA

- (void)promptMFAQuestionFromToken:(PDMFAToken *)mfaQuestionToken {
    mfaQuestionToken.mfaSecretAnswer = kMFA;
    [self.authenticationCoordinator registerWithMFA:mfaQuestionToken];
}

4. Login by 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 loginByPin call.

Note: Initialize the Authentication facade before calling the login method.

- (IBAction)loginClicked:(id)sender {
    [CommonUtil showProgressIndicatorOnView:self];
    [self.authenticationCoordinator loginByPIN:kPin;
    }
- (void)authenticationCoordinator:(PDAuthenticationCoordinator *)authenticationCoordinator authenticationDidSucceed:(PDLoginResponse *)loginResponse {
    [self authenticationDidSucceed:authenticationCoordinator];
}
- (void)authenticationCoordinator:(PDAuthenticationCoordinator *)authenticationCoordinator authenticationInvocationDidFail:(PDPaydiantError *)authenticationError {
    [CommonUtil hideProgressIndicatorOnView:self];
    [CommonUtil displayError:authenticationError];
}
- (void)authenticationCoordinator:(PDAuthenticationCoordinator *)authenticationCoordinator authenticationDidFail:(PDPaydiantError *)authenticationError {
    [CommonUtil hideProgressIndicatorOnView:self];
    if (authenticationError.statusCode == 401) {
        [CommonUtil displayErrorMessageForCustomErrorCode:@"PASSCODE_401" usingError:authenticationError];
    }
    else {
        [CommonUtil displayError:authenticationError];
    }
}

5. Logout

It is important to provide a means for the user to explicitly logout, if desired.

The Paydiant 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.

Note: Initialize the Authentication facade before calling the logout method.

PDAuthenticationCoordinator *authenticationCoordinator = [PDAuthenticationCoordinator new];
    authenticationCoordinator.delegate = (id)self;
    [self.authenticationCoordinator logout];

- (void)authenticationCoordinator:(PDAuthenticationCoordinator *)authenticationCoordinator authenticationInvocationDidFail:(PDPaydiantError *)authenticationError`

- (void) authenticationCoordinator:(PDAuthenticationCoordinator *)authenticationCoordinator logoutDidFail:(PDPaydiantError *)logoutError {
    [CommonUtil hideProgressIndicatorOnView:self];
    [CommonUtil displayError:logoutError];
}
- (void) finishedLogOut:(PDAuthenticationCoordinator *)authenticationCoordinator
{
    [CommonUtil hideProgressIndicatorOnView:self];
    self.scanBTN.hidden = YES;
    self.walletBTN.hidden = YES;
    self.loginBTN.hidden = NO;
    self.forgotPasswordBTN.hidden = NO;
    self.forgotPasscodeBTN.hidden = NO;
    self.UnlinkBarBTN.enabled = YES;
    self.logoutBarBTN.enabled = NO;
    [self authenticateByTouchID];
}

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.

Note: Initialize the Device facade before calling the unlink method.

PDDeviceCoordinator *deviceCoordinator = [PDDeviceCoordinator new];
[deviceCoordinator  removeDevice:^{
    [CommonUtil hideProgressIndicatorOnView:self];
    [self verifyDeviceIsRegistered];
    self.scanBTN.hidden = YES;
    self.walletBTN.hidden  = YES;
    self.UnlinkBarBTN.enabled = YES;
    self.logoutBarBTN.enabled = NO;
} failureBlock:^(PDPaydiantError *deviceRemovalError) {
    [CommonUtil hideProgressIndicatorOnView:self];
    [CommonUtil displayError:deviceRemovalError];
}];

NEXT STEP 3: Enroll payment methods

Feedback

Have feedback?

Let us know.