iOS SDK - User Enrollment Module

Use the endpoints of this module to create and manage a wallet user's profile, including contact information, login credentials, secret questions, etc.

Initialize User Enrollment Facade

Prior to invoking any user enrollment module endpoints:

  1. Create a new request object for the relevant coordinator.
  2. Implement the delegate for the coordinator to handle responses.
PDUserEnrollmentCoordinator *tempUserEnrollmentCoordinator = [[PDUserEnrollmentCoordinator alloc] init];
self.userEnrollmentCoordinator = tempUserEnrollmentCoordinator; [tempUserEnrollmentCoordinator release];

retrieveMfaQuestionsWithMetadata

Gets the set of multi-factor authentication (MFA) questions and requirements configured for the wallet by its issuer.

Note: If the enrollment is canceled or expires before completion but after MFA questions are retrieved, you must clear the retrieved questions from the app's memory cache. Since registration was not completed, the user is not logged in and the cache-clearing that you implement as a logout step is not invoked. If enrollment is abandoned prior to MFA retrieval, no action is required. Likewise, if MFA retrieval is invoked after login (such as for secret question reset), proper logout cache-clearing is sufficient.

Element Value
Method Signature -(void) retrieveMfaQuestionsWithMetadata;
Success void (^RetrieveMFAQuestionsWithMetadataCompletionBlock)(PDRetrieveMFAQuestionsWithMetadataResponse*response);

response - Contains the set of MFA questions available for selection as secondary authentication questions. Depending on the issuer configuration, the questions may be returned as a set of strings or as a set of PDMFAQuestionWithMetadata that also specify requirements, such as the number of questions the user must answer, whether any questions are mandatory, etc.
Failure void (^RetrieveMFAQuestionsWithMetadataFailureBlock)(PDPaydiantError*userEnrollmentError);

Configure user error messages for this call with the key kUserErrorFetchMfaQuestionsWithMetadataDomain.

Error Description
500 An unknown error occurred internally in the server.

retrievePasswordConfigurations

Gets the issuer-defined requirements for the user password, such as minimum length, capitals, lowercase, numbers, symbols, etc.

Note: It is the app's responsibility to validate the password field input based on the requirements returned in this call. Registration will fail if the password set does not meet the issuer's requirements.

Element Value
Method Signature -(void) retrievePasswordConfigurations;
Success void (^RetrievePasswordConfigurationsCompletionBlock)(PDUserPasswordConfigurations*passwordConfigs);

passwordConfigs - The complete set of password validation rules as defined during issuer onboarding.
Failure void (^RetrievePasswordConfigurationsFailureBlock)(PDPaydiantError*userEnrollmentError);

Configure user error messages for this call with the key kUserErrorRetrievePasswordConfigsDomain.

Error Description
500 An unknown error occurred internally in the server.

retrievePasscodeConfigurations

Gets the issuer-defined requirements for the user PIN, such as minimum length.

Note: The app must validate the PIN field input based on the requirements returned in this call. Registration will fail if the PIN set does not meet the issuer's requirements.

Element Value
Method Signature -(void) retrievePasscodeConfigurations;
Success void (^RetrievePasscodeConfigurationsCompletionBlock)(PDUserPasscodeConfigurations*passcodeConfigurations);

passcodeConfigurations - The complete set of PIN validation rules as defined during issuer onboarding.
Failure void (^RetrievePasscodeConfigurationsFailureBlock)(PDPaydiantError*userEnrollmentError);

Configure user error messages for this call with the key kUserErrorRetrievePasscodeConfigsDomain.

Error Description
500 An unknown error occurred internally in the server.

registerNewUser (Paydiant)

Submits a new user profile to register a new wallet account on the Paydiant platform.

Element Value
Method Signature -(void)registerNewUser:(PDRegisterUserRequest*)request;

request - Passes a new user profile populated with profile data values input by the user. The email address value must be unique to the Paydiant platform in order for the issuing partner to create a new registration.
Success void (^RegisterUserCompletionBlock)(PDRegisterUserResponse*response);

response - Contains the newly created user profile, plus status information related to the outcome of the call and a temporary nonce that, when passed with the loginByNonce method within the time period configured by the issuer, allows the app to automatically log the user in without requiring the user to re-enter credentials.
Failure void (^RegisterUserFailureBlock)(PDPaydiantError*userEnrollmentError);

Configure user error messages for this call with the key kUserErrorRegisterNewUserDomain.

Error Description
400 One or more parameters in the request is not valid.
416 The email address provided is already in use by an existing wallet.
419 The password does not meet the minimum requirements set by the wallet issuer.
420 The passcode does not meet the minimum requirements set by the wallet issuer.
500 An unknown error occurred internally in the server.

registerCustomer (SSO)

Registers a new wallet for a user where the profile is managed and authenticated by an external system repository, such as the issuer's existing user database or a third-party identity provider (IDP).

Note: Before invoking registration, call retrieveCustomerProfileMetaData to obtain the profile properties relevant to the external repository and a one-time session token required to call that system.

Element Value
Method Signature -(void)registerCustomer:(PDRegisterCustomerRequest*)request;

request - Passes a new user profile populated with profile data and the nonce returned in the retrieveCustomerProfileMetaData response.
Success void (^RegisterCustomerCompletionBlock)(PDRegisterCustomerResponse*response);

response - Contains the newly-assigned customerUri, a temporary nonce that, when passed with the loginByNonce method within the time period configured by the issuer, allows the app to automatically log the user in without requiring the user to re-enter credentials and returns any custom profile properties defined by the external repository.
Failure void (^RegisterCustomerFailureBlock)(PDPaydiantError*userEnrollmentError);

Configure user error messages for this call with the key kUserErrorRegisterCustomerDomain.

Error Description
400 One or more parameters in the request is not valid.
401 Access denied; invalid nonce.
408 The passcode does not meet the minimum requirements set by the wallet issuer.
410 MFA response is required.
416 The email address provided is already in use by an existing wallet.
500 An unknown error occurred internally in the server.

retrieveCustomerProfileMetaData

Obtains profile properties relevant to an external user repository that will be used to manage and authenticate wallet users for this issuer.

Note: This call requires the app to obtain an authorization token directly from the external identity provider (IDP) out of pocket from Paydiant's SDK.

Element Value
Method Signature -(void)retrieveCustomerProfileMetaData:(PDRetrieveCustomerProfileMetaDataRequest*)request;

request - Passes the previously-obtained authorization token that signifies permission to call the specified external IDP in order to request data.
Success void (^RetrieveCustomerProfileMetaDataCompletionBlock)(PDRetrieveCustomerProfileMetaDataResponse*response);

response - Contains the properties that define a user profile in the external repository and a temporary nonce required to create a new profile in the external system using the registerCustomer (SSO) method.
Failure void (^RetrieveCustomerProfileMetaDataFailureBlock)(PDPaydiantError*userEnrollmentError);

Configure user error messages for this call with the key kUserErrorRetrieveCustomerProfileMetaDataDomain.

Error Description
400 One or more parameters in the request is not valid.
401 Access denied; invalid authorization code.
500 An unknown error occurred internally in the server.

resendVerificationEmail

Issues another email containing the link by which a user must verify ownership of the email address provided during registration or profile update in the event that the previous email was lost or deleted. Login will fail until verification is complete.

Element Value
Method Signature -(void)resentVerificationEmail:(NSString *)email;

email - The email address that is pending verification.
Success void (^ResendVerificationEmailCompletionBlock)(NSString *message);

message - A message to display in the app that advises the user to check their email for the verification link.
Failure void (^ResendVerificationEmailFailureBlock)(PDPaydiantError*userEnrollmentError);
Status Code Description
500 An unknown error occurred internally in the server.

updateUserProfile

Submits changes to one or more properties of the user profile on record, observing the conventions defined below.

Note: If email verification in enabled by the issuer, updating the email address value triggers an email to the new address containing a verification link and a notification email to the prior address on record. The new address will not be activated until verification is completed.

Method Overview

Updates to additionalCustomerInformation values are applied according to the following conventions:

  • Properties that specify a value in the update object are modified with the new value. If the new value is the same as the existing value, the ModifiedDate still reflects that the property was changed.
  • Properties that are omitted from the request remain unchanged.
  • Properties that are included in the object with a null value are deleted from the record.

Updates to MFA question selection and/or responses on record are applied according to the following conventions:

  • The app must populate the mfaAnswers attribute of PDUserProfile with the exact number of required MFA question/answer values, as specified in the PDRetrieveMFAQuestionsWithMetadataResponse returned in the retrieveMFAQuestionsWithMetadata call.
  • If the mfaAnswers attribute contains fewer or more than the specified required value, the update operation will fail.
  • Once updated, previously selected question/answer values are deleted from the profile.

If the externalId attribute is defined for the profile, the updated PDUserProfile object must be populated with the same value. Otherwise, the value will be deleted.

Element Value
Method Signature -(void)updateUserProfile:(PDUserProfile*)anUpdatedUserProfile;

anUpdatedUserProfile -Includes updated values for properties to be changed in the record. See method overview for updating behavior.
Success void (^UpdateCustomerProfileCompletionBlock)(NSString *message);

message - An optional update confirmation message to display in the app.
Failure void (^UpdateCustomerProfileFailureBlock)(PDPaydiantError*userEnrollmentError);

Configure user error messages for this call with the key kUserErrorUpdateUserProfileDomain.

Error Description
400 One or more parameters in the request is not valid.
416 The email address provided is already in use by another wallet.
500 An unknown error occurred internally in the server.

updateUserPassword

Changes only the user's password without accessing the entire profile.

Note: Before invoking, validate that the password complies with issuer requirements (retrievePasswordConfigurations) and that the update and confirmed values match.

Element Value
Method Signature -(void)updateUserPassword:(NSString *)oldPassword newPassword:(NSstring *)newPassword confirmNewPassword:(NSString *)confirmedPassword;

oldPassword - The user's entry for the current password stored on the profile.
newPassword - The user's entry for the new password update.
confirmedPassword - The user's entry to confirm the new password update.
Success void (^UpdateUserPasswordCompletionBlock)(NSString *message);

message - An update confirmation message from the server.
Failure void (^UpdateUserPasswordFailureBlock)(PDPaydiantError*userEnrollmentError);

Configure user error messages for this call with the key kUserErrorUpdateUserCredentialsDomain.

Error Description
400 One or more parameters in the request is not valid.
403 The user is not currently logged-in.
406 The new password is not unique within the issuer defined period.
416 The current password value provided is not correct.
417 The new password and the confirmed password values do not match.
419 The new password does not met the minimum requirements set by the issuer.
421 The user is deactivated due to consecutive incorrect current password entries.
424 The call cannot be completed because the account is locked.
500 An unknown error occurred internally in the server.

updateUserPasscode

Changes only the user's PIN without accessing the entire profile.

Note: Before invoking, validate that the new pin complies with issuer requirements (retrievePasscodeConfigurations) and that the update and confirmed values match.

Element Value
Method Signature -(void)updateUserPasscode:(NSString *)oldPasscode newPasscode:(NSstring *)newPasscode confirmNewPasscode:(NSString *)confirmedPasscode;

oldPasscode - The user's entry for the current PIN stored on the profile.
newPasscode - The user's entry for the new PIN update.
confirmedPasscode - The user's entry to confirm the new PIN update.
Success void (^UpdateUserPasscodeCompletionBlock)(NSString *message);

message - An update confirmation message from the server.
Failure void (^UpdateUserPasscodeFailureBlock)(PDPaydiantError*userEnrollmentError);

Configure user error messages for this call with the key kUserErrorUpdateUserPasscodeDomain.

Error Description
400 One or more parameters in the request is not valid.
403 The user is not currently logged-in.
416 The current PIN value provided is not correct.
417 The new PIN and the confirmed PIN values do not match.
420 The new PIN does not met the minimum requirements set by the issuer.
421 The user is deactivated due to consecutive incorrect current PIN entries.
424 The call cannot be completed because the account is locked.
500 An unknown error occurred internally in the server.

updateMFAAnswers

Changes the user's selection of MFA questions and/or responses to previously answered MFA questions without updating the entire profile, observing the following conventions:

  • The call must pass the exact number of required MFA question/answer values stipulated by the issuer. Invoke retrieveMFAQuestionsWithMetadata to obtain the requirement.
  • To maintain the same answers for any of the previously answered questions, the same question and same answer must be passed in this call. Null values are prohibited.
  • Once updated, the previously selected question/answer values are deleted from the profile.
Element Value
Method Signature -(void)updateMFAAnswers:(NSDictionary *)mfaQuestionsAnswer;

mfaQuestionsAnswer - The set of key/value pairs that defines each question and corresponding updated answer value input by the user.
Success void (^UpdateUserMFAAnswersCompletionBlock)(NSString *message);

message - An update confirmation message from the server.
Failure void (^UpdateUserMFAAnswersFailureBlock)(PDPaydiantError*userEnrollmentError);

Configure user error messages for this call with the key kUserErrorUpdateMfaAnswersDomain.

Error Description
400 One or more parameters in the request is not valid.
403 The user is not currently logged-in.
500 An unknown error occurred internally in the server.

changeExpiredPassword

Updates a user's password that must be changed at issuer-specified intervals.

Note: Before invoking, validate that the password complies with issuer requirements (retrievePasswordConfigurations) and that the update and confirmed values match.

Element Value
Method Signature -(void)changeExpiredPassword:(NSString *)email olderPassword:(NSString *)expiredPassword newPassword:(NSstring *)aValidPassword confirmNewPassword:(NSString *)sameValidPassword;

email - The email address under which the wallet is registered.
expiredPassword - The user's entry for the current password stored on the profile.
aValidPassword - The user's entry for the new password update.
sameValidPassword - The user's entry to confirm the new password update.
Success void (^ChangeExpiredPasswordCompletionBlock)(NSString *message);

message - An update confirmation message from the server.
Failure void (^ChangeExpiredPasswordFailureBlock)(PDPaydiantError*userEnrollmentError);

Configure user error messages for this call with the key kUserErrorChangePasswordDomain.

Error Description
400 One or more parameters in the request is not valid.
406 The new password is not unique within the issuer defined period.
416 The current password value provided is not correct.
417 The new password and the confirmed password values do not match.
419 The new password does not met the minimum requirements set by the issuer.
421 The user is deactivated due to consecutive incorrect current password entries.
424 The call cannot be completed because the account is locked.
500 An unknown error occurred internally in the server.

resetForgottenPassword

Trigger an email containing a link to a secure portal through which the user can verify their identity via an MFA question/answer and reset the password for the wallet.

Element Value
Method Signature -(void)resetForgottenPassword:(NSString *)email;

email - The email address to which the reset link will be sent as provided by the user.
Success void (^SendForgotCredentialsRequestCompletionBlock)(NSString *message, NSArray *mfaQuestions);

message - An update confirmation message from the server.
mfaQuestions - For security purposes, this value will be null and will instead be asked in the secure portal to which the user will be directed.
Failure void (^SendForgotCredentialsRequestFailureBlock)(PDPaydiantError*userEnrollmentError);

Configure user error messages for this call with the key kUserErrorResetForgottenCredentialsDomain.

Error Description
400 One or more parameters in the request is not valid.
410 The email address provided does not match that of any registered wallet for the issuer.
500 An unknown error occurred internally in the server.

resetForgottenPasscode

Triggers an email that contains a link to a secure portal through which the user can verify their identity via an MFA question/answer and reset the PIN for the wallet.

Element Value
Method Signature -(void)resetForgottenPasscode:(NSString *)email;

email - The email address to which the reset link will be sent as provided by the user.
Success void (^SendForgotCredentialsRequestCompletionBlock)(NSString *message, NSArray *mfaQuestions);

message - An update confirmation message from the server.
mfaQuestions - For security purposes, this value will be null and will instead be asked in the secure portal to which the user will be directed.
Failure void (^SendForgotCredentialsRequestFailureBlock)(PDPaydiantError*userEnrollmentError);

Configure user error messages for this call with the key kUserErrorResetForgottenCredentialsDomain.

Status Code Description
400 One or more parameters in the request is not valid.
410 The email address provided does not match that of any registered wallet for the issuer.
500 An unknown error occurred internally in the server.