Skip to main content
Vindicia Knowledge Center

Gather Failed Payments And Prepare For Submission to Vindicia Retain

Gather Failed Payments And Prepare For Submission to Vindicia Retain

User Story

Merchant needs to prepare data on failed transactions for submission to Vindicia Retain for further processing.



  • Failed transaction has exhausted the merchant retry strategy.


  • Transaction values have been mapped to Vindicia Retain transaction fields and are ready for submission to Vindicia Retain.

Basic Scenario

  1. Merchant business user identifies data for failed transactions which will be sent to Vindicia Retain, working with Security or Finance departments as necessary.
  2. Merchant business user provides data for failed transactions to the merchant developer.
  3. Merchant developer maps Vindicia Retain data members to merchant data fields, to prepare data for submission to Vindicia Retain.

Design Approach

  1. The merchant business user should identify the data on failed transactions which will be sent to Vindicia Retain.  This data may be controlled by Security Policy or other IT or Development teams, and may require interaction with the Finance department. Thus, this task should originate with a business user or a project manager, not a developer. 
  2. Transaction data should be identified at the beginning of the project, and should proceed in parallel with the Vindicia Retain integration. Identifying this data is required for launch.
  3. The merchant developer should identify the Vindicia Retain data members that will be populated, and the associated merchant source data fields that will be mapped to the Vindicia Retain data fields.

For information about submitting failed transactions to Vindicia Retain, see Submit Failed Transactions for Recovery (SEL-001).

Sequence Diagram

Not Applicable

Use Case Implementation

The following sections identify the tasks to be performed by the merchant business user and the merchant developer in preparing failed transaction data for submission to Vindicia Retain.

Merchant Business User Identifies Failed Transaction Data

The merchant business user should identify the following information for each failed transaction: 

1. The authorization response code received from the most recent Failed authorization (i.e. decline code such as 302, 530, or other).

2.  Information for a credit card or token used as payment method:

For credit card, include: 

  • The full credit card number.
  • The credit card expiration date.

For a token, include: 

  • The Token or Profile ID which represents the stored credit card.
  • The BIN (first six digits of the stored credit card number). 
    Note For direct connections to Litle/Vantiv, the BIN is required. For other payment processors using tokens, the BIN is not required.
  • The credit card expiration date, if available.

3. The last time that authorization was attempted for the Failed Transaction.

4. The Billing Frequency, such as monthly or annual.

5. The billing address for the credit card.

6. The number of prior completed billings for the subscription.

7. A unique identifier for the Customer.

8. A unique identifier for the Subscription.

9. A unique identifier for the Failed Transaction.

The unique identifiers specified in numbers 7 through 9 should map to data fields in the merchant system. The most critical is the identifier for the Failed Transaction. Vindicia Retain will process a unique Failed Transaction only once, and will return the same unique identifier for the Failed Transaction with the results.  This enables the merchant to maintain the final status for the Failed Transaction in the merchant system.

Provide the additional data values as specified below, if available.

10. The date of the most recent completed billing for the subscription.

11. The date the subscription originally started.

12. The AVS (Address Verification) result received for the Billing Address.

13. The CVN (Card Verification) result received from the last Failed attempt.

After identifying the failed transaction data, the merchant business user should provide this data to the merchant developer, for submission to Vindicia Retain.

Merchant Developer Maps Vindicia Retain Data Fields to Merchant Data Values

For each failed transaction, include the Vindicia Retain data fields as specified below, mapped to the corresponding merchant data values. Transactions may use a credit card or tokens as payment method, with differing data values as specified.

The table below identifies the Vindicia Retain data fields and corresponding merchant data values. All values are required, except where designated as 'if available'.

Note The values below include the required WSDL fields, as well as additional fields that assist Vindicia Retain in accurately processing failed transactions.

Vindicia Retain Data Field Corresponding Merchant Data Value
amount Monetary value for the transaction.
authCode The authorization response code (i.e. 302, 530, etc.) returned by payment processor for the most recent Failed authorization decline.

Customer billing address for the payment method. Include the following if available: 

  • billingAddressLine1
  • billingAddressCity
  • billingAddressDistrict
  • billingAddressCountry
  • billingAddressPostalCode
billingFrequency Billing plan period type, such as Month or Year.
creditCardAccount The full credit card number (if payment method is credit card) or the first 6 digits of the credit card number (the BIN) (if payment method is tokens). Note: the BIN is required for transactions using tokens when the payment processor is Litle/Vantiv. The BIN may be omitted with other payment processors if it is not available.
creditCardExpirationDate The credit card expiration date in YYYYMM format. Include for all transactions, whether paid by credit card or tokens.
currency Currency code for Transaction object. Default is USD.
customerId Unique ID of the customer's account.
divisionNumber The merchant's division or group number, used by payment processor when processing the original Transaction. Chase Paymentech refers to this number as the Division Number; Litle calls it the Report Group; MeS calls it the Profile ID. 
merchantTransactionId Unique ID of failed transaction.
paymentMethodId The unique merchantPaymentMethodId assigned to the credit card (if paid with credit card) or the merchantTokenID (if paid with tokens). Note: The paymentMethodId cannot be identical to the credit card number.
paymentMethodIsTokenized False (if paid with credit card) or True (if paid with tokens).
previousBillingCount If available: the number of previous successful billings associated with the subscription.
previousBillingDate If available: the date of the last successful billing (i.e. for a monthly billing plan, previousBillingDate is the month of the most recent successful transaction capture).
status Failed
subscriptionId The unique ID of the customer subscription.
subscriptionStartDate If available: the date the subscription originally started.
timeStamp Time when the last failure of the transaction took place.  

Sample Code

Not Applicable

Scenario Extensions



Certification Not Required


Use Case #: SEL-011


For Users

Learn More
For Users

Vindicia Subscribe Features

Learn More
Vindicia Subscribe Features
Back to Top