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:
- Create a new request object for the relevant coordinator.
- 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 ofPDUserProfile
with the exact number of required MFA question/answer values, as specified in thePDRetrieveMFAQuestionsWithMetadataResponse
returned in theretrieveMFAQuestionsWithMetadata
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. |