iOS SDK - Payment Accounts Module
Last updated: Sept 19th, 9:26pm
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:
- Create a new request object for the relevant coordinator.
- Implement the delegate for the coordinator to handle responses.
1self.managePaymentInstrumentsCoordinator = [[PDManagePaymentInstrumentsCoordinator alloc] init];2self.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, WLW 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 WLW'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 WLW 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 WLW'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 WLW 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. |
Variable Step Account Enrollment (4 related calls)
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 WLW'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 WLW'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, WLW 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, WLW 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. |