iOS SDK - Payment Accounts Module

Use the endpoints of this module to manage the forms of payment that are available in the wallet.

Initialize Payment Instruments Management Facade

Prior to invoking any payment accounts module endpoints:

  1. Create a new request object for the relevant coordinator.
  2. Implement the delegate for the coordinator to handle responses.
self.managePaymentInstrumentsCoordinator = [[PDManagePaymentInstrumentsCoordinator alloc] init];
self.managePaymentInstrumentsCoordinator setDelegate:self];

retrievePaymentAccountConfigurations

Gets the wallet issuer's rules for how payment account data is handled, such as whether users can select their own image for each registered tender and whether months are represented as abbreviations, numbers, or spelled out.

Element Value
Method Signature -(void) retrievePaymentAccountConfigurations;
Success (^FetchAccountConfigurationCompletionBlock;(PDPaymentAccountConfigurations*accountConfigurations);

accountConfigurations - The set of issuer specifications relevant to payment account data formats and handling.
Failure (^FetchAccountConfigurationFailureBlock(PDPaydiantError*managePaymentInstrumentsError);

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

Error Description
403 The user must be logged in to make this call.
500 An unknown error occurred internally in the server.

retrieveBillingAddresses

Gets the billing addresses associated with each payment account registered in the wallet. Invoke this call when the wallet initializes to minimize performance impact during a transaction or if pre-populating form data during account updates.

Element Value
Method Signature -(void) retrieveBillingAddresses;
Success (^FetchBillingAddressesCompletionBlock: (NSArray *)billingAddresses;

billingAddresses - An array of PDAddressInformation instances representing the billing address for each payment account registered in the wallet.
Failure (^FetchBillingAddressesFailureBlock(PDPaydiantError*managePaymentInstrumentsError);

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

Error Description
403 The user must be logged in to make this call.
500 An unknown error occurred internally in the server.

retrieveAllPaymentAccounts

Gets the set of all payment accounts registered in the wallet. Invoke this call when the wallet initializes in order to minimize performance impact during a transaction or account management operations.

Element Value
Method Signature -(void) retrieveAllPaymentAccounts:(PDRetrieveAllPaymentAccountsRequest*)aRetrieveAllPaymentAccountsRequest;

aRetrieveAllPaymentAccountsRequest - Specifies whether the returned account instances should include metadata for each property, such as data type, supported characters, size limits, requirement, etc.
Success (^FetchAllPaymentAccountsCompletionBlock: (NSArray *paymentAccounts,PDRetrieveAllPaymentAccountsResponse*response);

paymentAccounts - An array of PDPaymentAccount instances that represents all payment accounts registered in the wallet.>
response - The set of payment account instances, plus status information related to the outcome of the call.
Failure (^FetchAllPaymentAccountsFailureBlock(PDPaydiantError*managePaymentInstrumentsError);

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

Error Description
403 The user must be logged in to make this call.
500 An unknown error occurred internally in the server.

retrieveSpecificPaymentAccount

Gets the details related to a specific payment account registered in the wallet.

Note: This call does not refresh the account balance, as that information is not required for account updating and sometimes incurs a fee from the processor.

Element Value
Method Signature -(void) retrieveSpecificPaymentAccount:(PDRetrieveSpecificPaymentAccountRequest*)aRetrieveSpecificPaymentAccountRequest;

aRetrieveSpecificPaymentAccountRequest - Identifies the account to retrieve and specifies whether the response should include the metadata for each property, such as data type, supported characters, size limits, requirement, etc.
Success (^FetchSpecificPaymentAccountCompletionBlock: (PDPaymentAccount*aPaymentAccount,PDRetrieveSpecificPaymentAccountResponse*response);

aPaymentAccount - The payment account and data requested.
response - The payment account instance, plus status information related to the outcome of the call.
Failure (^FetchSpecificPaymentAccountFailureBlock(PDPaydiantError*managePaymentInstrumentsError);

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

Error Description
400 BAD_REQUEST - The specified account could not be found.
403 The user must be logged in to make this call.
500 An unknown error occurred internally in the server.

refreshPaymentAccountBalance

Gets the current balance for the specified account from the processor.

Element Value
Method Signature -(void) refreshPaymentAccountBalance:(PDAccountIdentifier*)anAccountIdentifier;

anAccountIdentifier - Uniquely identifies the account by its card number, Paydiant URI, and account type.
Success (^RefreshPaymentAccountBalanceCompletionBlock: (PDAccountBalance*paymentAccountBalance);

accountBalance - The balance details as related to the card type. For example, a gift card is the amount left to spend while a credit card is the amount that has been charged.
Failure (^RefreshPaymentAccountBalanceFailureBlock(PDPaydiantError*managePaymentInstrumentsError);

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

Error Description
400 BAD_REQUEST - The specified account could not be found.
403 The user must be logged in to make this call.
405 Balance retrieval is temporarily unavailable.
406 Balance retrieval is not supported for this account type.
500 An unknown error occurred internally in the server.
503 The specified account does not exist.

refreshPointsBalance

Gets the current points accrued for the specified account from Paydiant's loyalty manager.

Note: Implement a programmatic delay when calling this method upon completion of a transaction to ensure that the server has time to apply the accrual and avoid an inaccurate "no accrual activities detected" response.

Element Value
Method Signature -(void) refreshPointsBalance:(NSString *)loyaltyProgramUri;

loyaltyProgramUri - Uniquely identifies the program account by its Paydiant URI.
Success (^RefreshPointsBalanceCompletionBlock: (NSInteger *pointsBalance);

pointsBalance - The total number of points accrued for the specified loyalty account.
Failure (^RefreshPointsBalanceFailureBlock(PDPaydiantError*managePaymentInstrumentsError);

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

Error Description
403 The user must be logged in to make this call.
404 NOT_FOUND - The specified loyalty account could not be found.
500 An unknown error occurred internally in the server.

retrieveLoadConfiguration

Gets the issuer specifications related to loading and reloading payment accounts through the wallet, such as supported denominations and amount minimums/maximums.

Element Value
Method Signature -(void) retrieveLoadConfiguration:(PDRetrieveLoadConfigurationRequest*)loadConfigRequest;

loadConfigRequest - Specifies the tender type for which the load configuration is relevant.
Success (^FetchLoadConfigurationCompletionBlock: (PDRetrieveLoadConfigurationResponse*response);

response - Contains the set of issuer-defined rules related to balance loading for the specified tender type.
Failure (^FetchLoadConfigurationFailureBlock(PDPaydiantError*managePaymentInstrumentsError);

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

Error Description
400 BAD_REQUEST - The specified tender type could not be found.
500 An unknown error occurred internally in the server.

addPaymentAccount

Adds a source of payment to the wallet. This is a single call that adds the payment account to Paydiant's secure repository.

Note: Do NOT submit the account type and account network type attribute values in the request if IIN resolution is enabled (an issuer onboarding setting). Submitted values, even if incorrect, will override the automatic resolution, which will cause the operation to fail.

Element Value
Method Signature -(void) addPaymentAccount:(PDAddPaymentAccountRequest*)anAddPaymentAccountRequest;

anAddPaymentAccountRequest - encapsulates all the properties required to authorize the payment account as a valid tender for the wallet.
Note: Different payment types have different authorization requirements. For example, a credit card might require the holder's zip code, while a gift card might not. Call retrievePaymentAccountConfigurations before presenting the input form to the user to ensure collection of all required data for the payment type.
Success (^AddPaymentAccountCompletionBlock: (PDPaymentAccount*newPaymentAccount,PDAddPaymentAccountResponse*response);

newPaymentAccount - The object containing the details of the newly created payment account, including its unique identifier in the Paydiant system.
response - Contains the payment account object and status information related to the outcome of the call.
Failure (^AddPaymentAccountFailureBlock(PDPaydiantError*managePaymentInstrumentsError);

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

Error Description
400 One or more parameters is invalid.
402 The entered payment account in not valid.
403 The user must be logged in to call this method.
406 The entered expiration date is not valid.
410 The entered payment account is already linked to the wallet.
414 The entered payment account has insufficient funds for validation.
419 The specified account type does not match that of the account number.
420 The specified network type does not match that of the account number.
421 The payment account could not be added.
426 The IIN for the specified account is not supported for this wallet.
500 An unknown error occurred internally in the server.

loadNewAccount

Adds a reloadable source of payment to the wallet and simultaneously initiate a funds transfer from another account in the wallet to front-load the new card with a starting balance.

Element Value
Method Signature -(void) loadNewAccount:(PDLoadNewAccountRequest*)loadNewAccountRequest;

loadNewAccountRequest - Encapsulates all the details related to the new account, the funding source account, and the amount to transfer.
Success (^LoadNewAccountCompletionBlock: (PDLoadNewAccountResponse*loadNewAccountResponse);

loadNewAccountResponse - Returns the newly added account and details of the load event, plus status information related to the outcome of the call.
Failure (^LoadNewAccountFailureBlock(PDPaydiantError*managePaymentInstrumentsError);

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

Error Description
400 One or more parameters is invalid.
403 The user must be logged in to call this method.
409 Account loading limit exceeded.
410 Invalid amount specified.
414 Account loading failed.
420 The amount specified exceeds the maximum balance for the account.
421 The amount specified exceeds the maximum load permitted for the account.
426 Fund loading is not supported for the specified account.
500 An unknown error occurred internally in the server.
501 The service is temporarily unavailable.

Adds a source of payment to the wallet through one or more calls, depending on the dynamic response from the account's authorization network. This option results in a link to the payment account in its original system of record, but does not store the payment credentials in Paydiant's repository.

startPaymentAccountEnrollment

Initiates the process to register a payment account as valid tender in the wallet.

Note: Do NOT submit the account type and account network type attribute values in the request if IIN resolution is enabled (an issuer onboarding setting). Submitted values, even if incorrect, will override the automatic resolution, which will cause the operation to fail.

Element Value
Method Signature -(void) startPaymentAccountEnrollment:(PDStartPaymentAccountEnrollmentRequest*)request;

request - Passes the initial level of information required to request enrollment authorization for the specified account type.
Success (^StartPaymentAccountEnrollmentCompletionBlock: (PDStartPaymentAccountEnrollmentResponse*response);

response - Contains the new enrollment instance and status information related to the outcome of the call. If the enrollmentState value is END, the registration is complete. If the value is MORE_INFO, collect the additional data requested and pass it through the continuePaymentAccountEnrollment method.
Failure (^StartPaymentAccountEnrollmentFailureBlock(PDPaydiantError*managePaymentInstrumentsError);

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

Error Description
400 BAD_REQUEST
- Required additional data values are missing.
- The enrollmentType is not specified.
- Supported tender types could not be located.
- Payment account already exists in wallet. Duplicates are not allowed.
403 The user must be logged in to make this call.
500 INTERNAL_SERVER_ERROR

- An unknown error occurred internally in the server.
- The transaction is not supported.

continuePaymentAccountEnrollment

Submits additional information requested by the processor to continue registering a payment account as valid tender in the wallet.

Element Value
Method Signature -(void) continuePaymentAccountEnrollment:(PDContinuePaymentAccountEnrollmentRequest*)request;

request - Passes needed additional information as indicated by the response to the immediately previous enrollment step.
Success (^ContinuePaymentAccountEnrollmentCompletionBlock: (PDContinuePaymentAccountEnrollmentResponse*response);

response - Contains the updated enrollment instance and status information related to the outcome of the call. If the enrollmentState value is END, the registration is complete. If the value is MORE_INFO, collect the additional data requested and pass it through another instance of this method.
Failure (^ContinuePaymentAccountEnrollmentFailureBlock(PDPaydiantError*managePaymentInstrumentsError);

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

Error Description
400 BAD_REQUEST
- PaydiantCorrelationId not found.
- Payment account already exists in wallet. Duplicates are not allowed.
403 The user must be logged in to make this call.
500 INTERNAL_SERVER_ERROR

- An unknown error occurred internally in the server.

retrieveIncompletePaymentAccountEnrollments

Gets the list of enrollments that are still pending completion so the user can choose to resume or cancel them.

Element Value
Method Signature -(void) retrieveIncompletePaymentAccountEnrollments:();
Success (^RetrieveIncompletePaymentAccountEnrollments: (PDRetrieveIncompletePaymentAccountEnrollmentsResponse*response);

response - Contains the set of PDPaymentAccountEnrollment instances for all enrollments that are still in a PENDING state.
Failure (^RetrieveIncompletePaymentAccountEnrollmentsFailureBlock(PDPaydiantError*managePaymentInstrumentsError);

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

Error Description
403 The user must be logged in to make this call.
500 INTERNAL_SERVER_ERROR

- An unknown error occurred internally in the server.

cancelPaymentAccountEnrollment

Deletes a pending payment account enrollment instance, thereby canceling the registration.

Element Value
Method Signature -(void) cancelPaymentAccountEnrollment:(PDCancelPaymentAccountEnrollmentRequest*)request;

request - Identifies the enrollment instance to be canceled by its PaydiantCorrelationId.
Success (^CancelPaymentAccountEnrollmentCompletionBlock: (void);
Failure (^CancelPaymentAccountEnrollmentFailureBlock(PDPaydiantError*managePaymentInstrumentsError);

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

Error Description
403 The user must be logged in to make this call.
500 INTERNAL_SERVER_ERROR - An unknown error occurred internally in the server.

verifyAccount

Submits double-deposit verification values to verify and activate a payment account registered in Paydiant's repository, but still designated with a currentStatus of PENDING_VERIFICATION.

Element Value
Method Signature -(void) verifyAccount:(PDAccountIdentifier*)anAccountIdentifier amountOne:(NSDecimalNumber *)firstAmount amountTwo:(NSDecimalNumber *)secondAmount;

- anAccountIdentifier - Uniquely identifies the account by its card number, Paydiant URI, and account type.
- firstAmount - A dollar amount input by the user to representing the first of two nominal deposits added to the payment account by the processor for the purpose of positively identifying the user's ownership of the account.
- secondAmount - A dollar amount input by the user representing the second of the two verification deposits.
Success (^VerifyAccountCompletionBlock: (NSString *message);

message - A response from the server confirming the successful verification.
Failure (^VerifyAccountFailureBlock(PDPaydiantError*managePaymentInstrumentsError);

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

Error Description
400 BAD_REQUEST
- The specified account could not be found.
- The amounts provided are not valid.
403 The user must be logged in to call this method.
410 The allowed time period for verification has expired.
414 The entered amounts do not match the deposit amounts.
417 The specified account is already verified/activated.
426 Account verification failed.
500 An unknown error occurred internally in the server.

updateExistingPaymentAccount

Submits changes to editable property values for a specified payment account.

Note: Do NOT submit the account type and account network type attribute values in the request if IIN resolution is enabled (an issuer onboarding setting). Submitted values, even if incorrect, will override the automatic resolution, which will cause the operation to fail.

Element Value
Method Signature -(void) updateExistingPaymentAccount:(PDUpdatePaymentAccountRequest*)updatePaymentAccountRequest;

updatePaymentAccountRequest - Identifies the payment account to update and defines the properties to be modified with new values.
Success (^UpdateExistingPaymentAccountCompletionBlock: (PDUpdatePaymentAccountResponse*updateAccountResponse);

updateAccountResponse - Contains the set of updated values for the identified account, plus status details related to the outcome of the call.
Failure (^UpdateExistingPaymentAccountFailureBlock(PDPaydiantError*managePaymentInstrumentsError);

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

Error Description
400 One or more parameters is not valid.
403 The user must be logged in to call this method.
417 The account information provided is not valid.
500 An unknown error occurred internally in the server.
507 AVS_MISMATCH - The billing address does not match the network record.

loadExistingAccount

Transfers funds from one account in the wallet to reload the balance of another account in the wallet.

Element Value
Method Signature -(void) loadExistingAccount:(PDLoadExistingAccountRequest*)loadExistingAccountRequest;

loadExistingAccountRequest - Encapsulates all the details related to the funding source account, the receiving target account, and the amount to transfer.
Success (^LoadExistingAccountCompletionBlock: (PDLoadExistingAccountResponse*loadExistingAccountResponse);

loadExistingAccountResponse - Returns the results of the payment authorization and the updated balance of the loaded account.
Failure (^LoadExistingAccountFailureBlock(PDPaydiantError*managePaymentInstrumentsError);

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

Error Description
400 One or more parameters is invalid.
403 The user must be logged in to call this method.
409 Account loading limit exceeded.
410 Invalid amount specified.
414 Account loading failed.
420 The amount specified exceeds the maximum balance for the account.
421 The amount specified exceeds the maximum load permitted for the account.
426 Fund loading is not supported for the specified account.
500 An unknown error occurred internally in the server.
501 The service is temporarily unavailable.

deletePaymentAccount

Remove the specified payment account as a tender source in the wallet.

Note: This operation does not cancel or deactivate the payment instrument itself, i.e. the credit or gift card; it only disassociates the card from the mobile wallet.

Element Value
Method Signature -(void) deletePaymentAccount:(PDAccountIdentifier*)aPaymentAccountIdentifier;

aPaymentAccountIdentifier - Uniquely identifies the account by its card number, Paydiant URI, and account type.
Success (^DeletePaymentAccountCompletionBlock: (NSString *message);

message - Confirms the successful operation.
Failure (^DeletePaymentAccountFailureBlock(PDPaydiantError*managePaymentInstrumentsError);

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

Error Description
403 The user must be logged in to make this call.
500 INTERNAL_SERVER_ERROR - An unknown error occurred internally in the server.