Android SDK - Payment Account Management Module

The payment account management module governs the functionality associated with managing the payment accounts registered in the logged-in user’s mobile wallet. This includes adding new accounts, updating or deleting existing accounts, and determining how those accounts are displayed in the app.

This chapter describes the methods available to provide complete payment account administration, including utility methods that facilitate the functionality, such as retrieving account images for a richer display, or retrieving the billing addresses of existing accounts for the purpose of pre-populating address fields for a new account.

Payment Account Metadata

The payment account management module uses a metadata approach for managing payment accounts in order to support variable property requirements for payment accounts of different tender types. For example, credit and debit card payment accounts require the card-holder’s billing address for processor authorization, but gift cards do not. This approach allows the adding and updating of different types of payment accounts to be both more flexible and more accurate, which enhances the usability of the mobile wallet app.

Each tender type element contains a set of one or more metadata elements, each of which represents a predefined property that is recognized and accepted by the Paydiant managed service. Application developers can use these metadata to design appropriate UI controls, field validation, and error handling. The following table describes the attributes that define each metadata property, the values for which can be specified individually for each metadata element when passed in a payment account creation or update method.

Meta data property attributes

Set UI Package Payment Account Service Listeners

To invoke the callback methods returned by the Paydiant service in response to the methods invoked by the Payment Account Management module of the SDK, the developer must set an implementation of the applicable listener interfaces in the UI Service class.

Retrieve All Payment Accounts

Invoke this method from the core or UI service package to request the complete set of payment accounts that are currently registered in the user’s wallet.

Errors

When retrieving payment accounts, the following errors are applicable for the RETRIEVE_ALL_PAYMENT_ACCOUNTS_EVENT:

Retrieve a Single Payment Account

Invoke this method from the core or UI service package to request the details of a specific payment account currently registered in the user’s wallet.

Errors

When retrieving a particular payment account, the following errors are applicable for the RETRIEVE_PAYMENT_ACCOUNT_EVENT:

Retrieve Account Without Balance Refresh

Invoke this method to retrieve the information for a specified payment account while specifically declining any balance update, which sometimes incurs a fee from payment processors. This method is useful when the payment account information is retrieved for the purpose of editing the account rather than for displaying as a payment selection.

Errors

When retrieving a payment account excluding balance refresh, the following errors are applicable for the RETRIEVE_PAYMENT_ACCOUNT_WITHOUT_BALANCE_REFRESH_EVENT:

Refresh an Account Balance

Invoke this method to refresh the balance for the payment or loyalty account specified in the parameter. Developers may want to call this method prior to displaying the payment or loyalty account in the app at the time of payment selection to ensure that the balance is current, particularly since account retrieval does not automatically include a balance refresh operation.

Errors

When refreshing a payment account balance, the following errors are applicable for the REFRESH_PAYMENT_ACCOUNT_BALANCE_EVENT:

Get Payment Account Configurations

Invoke this method to retrieve the properties that are required or relevant for each payment account type so the forms for adding or editing a payment account can be displayed accordingly in the app.

Errors

When retrieving payment account configurations, the following errors are applicable for the PAYMENT_ACCOUNT_CONFIGURATION_RETRIEVAL_EVENT:

Get Payment Account Billing Addresses

Invoke this method to obtain the billing addresses associated with each payment account. This information can be used to pre-populate the wallet owner’s information in the adding a payment account form, for convenience, or may also be used when the user is editing the properties for an existing payment account.

Errors

When retrieving payment account billing addresses, the following errors apply to the PAYMENT_ACCOUNT_BILLINGADDRESS_RETRIEVAL_EVENT:

Get All Tender Types

Invoke this method to retrieve a list of all tender types that are supported by the wallet issuer for the purpose of limiting the types of payment account that the user can register. This method is useful during the adding payment account operation in the app because it returns the metadata elements that define each type so the developer can design the form for each type to display only the fields that are relevant for the selected type.

Errors

When retrieving supported tender types, the following errors apply to the RETRIEVE_ALL_TENDER_TYPES_EVENT:

Get One Tender Type

Invoke this method to obtain the collection of properties that are relevant for a tender type of the specified account and network type values. Call this method when a tender type is selected for payment account addition or update so the requirements specific to that type are upheld.

Errors

When retrieving the details for a particular tender type, the following errors apply to the RETRIEVE_SPECIFIC_TENDER_TYPE_EVENT:

Add Payment Account (Single Step)

Invoke this method to submit payment account information input by the wallet user for the purpose of linking an existing payment instrument, such as a credit card, debit card, gift card, etc., to the wallet as a mobile payments tender.

Do not use emoji characters in the nickname attribute because on some networks it can cause the payment to fail.

Errors

When adding a payment account, the following errors are applicable for the ADD_PAYMENT_ACCOUNT_MAETADATA_EVENT:

Non-Metadata Implementations

To Be Deprecated

Both UI and Core implementations pass values for only the default properties used to define a payment account in the wallet. The properties passed in this method are static and do not vary by tender type and cannot define custom fields of data.

|Core Method|PaymentAccountAdded addPaymentAccount(paymentAccountInfo PaymentAccountInfo);

Raw output for the added payment account or relevant exception.|

Provision a Payment Account (Single Step)

Invoke this method to submit the relevant data supplied in the app by the wallet owner for the purpose of generating a new payment account in the wallet user’s name that is automatically registered in the wallet.

Errors

When provisioning a new payment account, the following errors are applicable for the PROVISION_ACCOUNT_EVENT:

Start Payment Account Enrollment (Variable Steps)

Invoke this method to initialize the process for designating a payment account as a mobile payments tender in the wallet. This process is applicable to both existing payment accounts (credit cards, debit cards, gift cards, etc.) and newly-issued accounts (a new gift card, loyalty card, private label credit card, etc.). Depending on the type of payment account being enrolled in the wallet and the specifications from the processing service, the response may indicate that the enrollment is complete or that additional information is required in order to further process the enrollment. In the latter case, collect the additional information to pass in the Continue Payment Account Enrollment (Variable Steps) call.

Errors

The following error states are applicable in the PaydiantException instance returned for the START_PAYMENT_ACCOUNT_ENROLLMENT_EVENT.

See Variable-Step Payment Account Enrollment Statuses 790 - 809 for relevant ErrorInformation.errorCode status and values.

Continue Payment Account Enrollment (Variable Steps)

Invoke this method to submit additional information required in the enrollment process for an enrollment event with a state of MORE_INFO. The enrollment process can have a variable number of steps depending on the information required and submitted throughout the process. Therefore, the properties required in this call will have been specified in the response to either the Start Payment Account Enrollment (Variable Steps) call or the immediately previous instance of this call.

This call should continue to be invoked until the enrollmentState in the response is END.

Errors

The following error states are applicable in the PaydiantException instance returned for the CONTINUE_PAYMENT_ACCOUNT_ENROLLMENT_EVENT. See Variable-Step Payment Account Enrollment Statuses 790 - 809 for relevant ErrorInformation.errorCode status and values.

Retrieve Payment Account Enrollments

Invoke this method to retrieve a list of enrollments that are still pending completion so the user can select one to resume or cancel the enrollment, if desired.

Errors

The following error states are applicable in the PaydiantException instance returned for the PAYMENT_ACCOUNT_ENROLLMENT_RETRIEVAL_EVENT.

Cancel Payment Account Enrollments

Invoke this method to delete an incomplete payment account enrollment that is still active.

Errors

The following error states are applicable in the PaydiantException instance returned for the CANCEL_PAYMENT_ACCOUNT_ENROLLMENT_EVENT.

Delete Payment Account

Invoke this method to remove a payment account from the wallet application so a user can suspend wallet use of that account. Note that this operation does not cancel the card associated with the payment account.

Errors

When deleting a payment account, the following errors are applicable for the DELETE_PAYMENT_ACCOUNT_EVENT:

Verify Payment Account

Invoke this method when a payment account has been added to the wallet that requires double deposit verification in order to submit the deposit values, as provided by the wallet owner, for verification. This verification step is often required for debit accounts and must be completed before the payment account can be activated for use in the wallet.

Errors

When verifying a payment account, the following errors are applicable for the VERIFY_PAYMENT_ACCOUNT_EVENT:

Update Payment Account

Implements the function to invoke this method to apply property edits (for example, account nickname) made to a payment account by the wallet owner from within the app.

Errors

When adding a payment account, the following errors are applicable for the UPDATE_PAYMENT_ACCOUNT_MAETADATA_EVENT:

Gift Account Management Services

The following methods deal specifically with GIFT-type payment accounts and are exposed through separate services to manage the unique nature of gift accounts.

Set UI package gift account service listeners

In order to invoke the callback methods returned by the Paydiant service in response to the methods invoked by the Gift Account services, the developer must set an implementation of the applicable listener interfaces in the UI Service class.

Get account load configuration

Invoke this method to obtain the specifications relevant to loading or reloading the balance of a gift account of the account and networks types specified. This method should be called prior to the Load a New Payment Account method so the configuration values returned can be applied to the load options presented in the app.

Errors

When retrieving load configurations, the following errors are applicable for the RETRIEVE_LOAD_CONFIGURATION_EVENT:

Load a new payment account

Invoke this method to specify a starting balance for a newly provisioned payment account (a GIFT account), the tender for which is procured from another existing payment account.

|Success|void onLoadPaymentInstrumentSuccess (loadPaymentAccountResponse LoadPaymentAccountResponse);

The success callback returns the response object that details the results of the load operation.| |Failure|void onGiftAccountManagementError (PaydiantException exception);

The failure callback returns an instance of PaydiantException for the LOAD_PAYMENT_INSTRUMENT_EVENT, detailing the nature of the failure identified by relevant error codes.| |Core Method|loadPaymentAccountResponse loadPaymentInstrument (LoadPaymentAccountParameters loadPaymentAccountParameters);

loadPaymentAccountParameters - The object instance that specifies the details for the loading event, such as the payment account from which the load funds will be transfered and the amount and currency type.

Returns raw output for the account load results or relevant exception.|

Errors

When retrieving load configurations, the following errors are applicable for the LOAD_PAYMENT_INSTRUMENT_EVENT: