Payment Wallet

Payment Wallet is a feature that lets customers manage their payment information during the checkout process and use those payment methods to complete payment for their order. Customers can view the details of their wallet, add new payment tenders of various tender types, update existing payment tenders, and remove payment tenders. The wallet supports various tender types for credit cards and gift cards.

The payment wallet API comprises several synchronous API calls. In case of a timeout during a payment wallet API call, the store should retry the transaction until the number of attempts reaches the configured maximum number. The suggested maximum value is 3. If the timeout persists, please contact Radial support.

Supported Tender Types

The payment wallet supports the following tender types

Tender Name Supported for Payment Wallet Can Be Used as Default Payment Method Can be Used for Subscription Orders
Visa Yes Yes Yes
Mastercard Yes Yes Yes
Discover Yes Yes Yes
American Express Yes Yes Yes
Gift Card Yes No No

Workflows

The payment wallet API supports a set of workflows for saving, managing, and using stored payment methods.

There are two workflows through which a customer adds a payment method for future use. Both are illustrated on the following flow diagram. In Flow 1, the customer has already entered the payment information for a current transaction and opts to save that payment method for future use. In Flow 2, the customer is managing their digital wallet separate from a current purchase and chooses to add a new payment method.

Save a Payment Method for Future Use (Flow 1)

  1. The customer has already performed any of the actions listed below. This means that the payment details are already validated.
    • The customer does a successful authorization of a credit card with response returned as APPROVED only.
    • The customer does a valid balance inquiry for a gift card, and there is balance available.
    • The customer does a valid redeem for a gift card, and there is still a balance available.
  2. The customer is presented with and chooses the option to save their payment method for future use. (Continue with Step 3 in Flow 2, below.)

Save a Payment Method for Future Use (Flow 2)

  1. The customer enters their payment information.
  2. The customer is presented with and chooses the option to save their payment method for future use. Here the validation is not done yet and the store is expected to validate the details entered by the customer using these API calls:
    • For credit cards, a Validate Card call to validate the card details entered by the customer. The validate card response should be successful without AVS and CSC flag.
    • For gift cards, a Gift Card Balance Inquiry call to validate the card details entered by the customer. The card should have a balance available.
  3. The store does an internal lookup to identify if the customer already has an associated wallet.
  4. If there is no wallet for the customer, the store makes a Create Payment Wallet call to create a new wallet. When successful the reply will contain a unique ID for the wallet. The returned wallet ID must be stored with the customer ID used to create the wallet and used for subsequent API calls.
  5. If a wallet already exists, the store makes a Get Payment Wallet call to get wallet details and the tenders associated with the wallet. All active tenders of the wallet and the respective tender details are provided to store.
  6. The tenders in the wallet are checked to see if a tender already exists with the same token and tender type.
  7. If the tender does not exist, or the wallet is newly created, the store makes an Add Payment Tender call to create a new tender. If the tender added is the first tender added to the wallet, and is eligible to be the default and subscription tender (see supported tender types), it is automatically marked as the default tender and subscription tender for the wallet. A different tender can be chosen later as the subscription tender or default tender.
  8. If the tender exists, the store makes an Update Payment Tender call with the new information.

Note: For error scenarios, refer to the error codes for Create Payment Wallet, Get Payment Wallet, Add Payment Tender, or Update Payment Tender.

Use a Saved Payment Method

When the customer is making payment, the store can present an option to the customer to use a saved payment method. If this option is selected the store will display the existing tender details for the customer to choose any of the available payment methods.

  1. The store does an internal lookup to identify if the customer already has a wallet.
  2. If a wallet already exists, the store makes a Get Payment Wallet call to get wallet details and the tenders associated with the wallet. All active tenders of the wallet and the respective tender details are returned.
  3. Store displays available tenders for the customer to select.

    Note: The store must collect the credit card security code (CVV/CSC) or gift card PIN from the customer before doing further payment operations.

Note: For error scenarios, refer to Get Payment Wallet error codes.

Wallet Management

A customer can visit a wallet management page to manage the payment tenders stored in their wallet. On this page the customer can choose to add new tenders or update or delete existing tenders. These workflows are illustrated in the flow diagram below and detailed in the following sections.

View Saved Payment Methods

  1. The store does an internal lookup to identify the wallet for the customer ID.
  2. If no wallet exists, store displays a message, "No wallet available"
  3. If a wallet exists, the store makes a Get Payment Wallet call to get wallet details and the payment methods associated with the wallet. All active payment methods of the wallet and the respective tender details are returned in this response.
  4. Store displays the existing payment methods to the customer.

Add a New Payment Method

  1. For a credit card, the store makes a Validate Card call to validate the card details entered by the customer. The validate card response should be success without AVS and CSC flag.
  2. For a gift card, the store makes a Gift Card Balance Inquiry call to validate the card details entered by the customer. The card should have a balance available
  3. Store does an internal lookup to identify the wallet for the customer ID.
  4. If there is no wallet for the customer, the store makes a Create Payment Wallet call to create a new wallet. When successful the reply contains a unique ID for the wallet. The returned wallet ID must be stored with the customer ID used to create the wallet for use in subsequent API calls.
  5. The store makes a Add Payment Tender call to create a new payment method within the wallet.

Edit a Payment Method

  1. The customer has already opened the wallet management page and the existing payment methods are displayed.
  2. The customer selects any of the available payment methods to edit.
  3. For a credit card, the store makes a Validate Card call to validate the card details entered by the customer. The validate card response should be success without AVS and CSC flag.
  4. For a gift card, the store makes a Gift Card Balance Inquiry call to validate the card details entered by the customer. The card should have a balance available.
  5. The store makes an Update Payment Tender call to update the payment method.

Delete Payment Method

  1. The customer has already opened the wallet management page and the existing payment methods are displayed.
  2. The customer selects any of the available payment methods to delete.
  3. The store makes a Delete Payment Tender call to delete the payment method.

Delete wallet

  1. The customer has already opened the wallet management page and has an associated wallet.
  2. The customer selects the option to delete the wallet.
  3. The store makes a Delete Payment Wallet call to delete the wallet.

Note: For error scenarios, refer to Delete Payment Wallet error codes.

Error Responses

In case of a timeout during a payment wallet API call, or if a reply is received with a response code of SystemError, the store should retry the transaction until the number of attempts reaches the configured maximum number. The suggested maximum value is 3. If the problem still persists for more than three attempts, please contact Radial support.

For specific error codes, refer to the Error Codes section for each payment wallet API call.

Payment Wallet API Calls

For details of the payment wallet API calls, see the following pages: