Skip to main content
Vindicia Knowledge Center

Mapping Request Data Fields for Vindicia Retain

Mapping Request Data Fields for Vindicia Retain

User Story

Merchant Developer or Architect needs to identify the Vindicia Retain Transaction data members to populate when submitting Failed Transactions to Vindicia Retain, and the associated source Transaction data from the merchant system which will be used to populate the Vindicia Retain Transaction data members in order to submit Failed Transactions to Vindicia Retain.



  • Failed Transactions will be submitted to Vindicia Retain for recovery.
  • Source data in the merchant system identified by Merchant Business User.
  • Merchant Developer identified mapping from source data to Vindicia Retain Transaction data members.

Basic Scenario

Check with Merchant Business User for availability of source data in merchant system.

Identify Vindicia Retain Transaction data members that will be populated from source data and the associated mapping from merchant source data fields to Vindicia Retain Transaction data

Design Approach

Below are the Required data fields for Vindicia Retain, which is a superset of the data fields that are required in the WSDL, and includes additional data fields marked as optional in the
WSDL, but which provide additional detail on the Failed Transaction to Vindicia Retain to assist in optimal processing decisions by Vindicia Retain:

These 3 fields always need to be specified. Below is what should be provided for each:

1) authCode: This is the authorization response code (i.e. decline code such as 302, 530 etc.) received from the most recent Failed authorization decline.

2) paymentMethodId: This is a unique identifier in your system for this form of payment. When you are passing the full credit card number (i.e. not using tokens), this can be any id value in your system that uniquely identifies this form of payment or card for the customer, other than the actual credit card number:

If you are passing the full Credit Card Number & not using Tokens:

You specify creditCardAccount as the Full Credit Card Number.
The creditCardExpirationDate should contain the Credit Card Expiration Date.
Your unique identifier for this payment method is specified in the paymentMethodId data member.
paymentMethodIsTokenized = False should be specified.

If using Tokens:

When you are using Tokens, paymentMethodId must be the Token Id that references the Payment
Profile/Credit Card at the Payment Processor or Payment Gateway, i.e. Cybersource. You also need to specify
paymentMethodIsTokenized = True & provide the BIN (first 6 digits of the card) in the creditCardAccount
parameter when using Tokens.

For Direct connections to Litle, it is necessary to provide the BIN in creditCardAccount when using Tokens.
For other gateways/processors using Tokens, including Cybersource, this means the BIN is not required.

It is a Best Practice to provide the BIN for Tokens, but can be ok to not provide the BIN if not found in your
database.  A direct connection to Litle is the one that we need the BIN when using Tokens however.  If your
Vindicia Retain integration will not directly connect to Litle, and will use a different Payment Processor or a Payment
Gateway, this requirement does not apply, but it is preferred that you pass the BIN anyway if you do have it
in your database.

You can specify creditCardAccount as an empty string if you don’t have the BIN, otherwise, please specify
the BIN (first 6 digits of the card) in this field.

The creditCardExpirationDate should still be provided if you have it.
The Token value is specified in the paymentMethodId data member.
paymentMethodIsTokenized = True should be specified.

3) Status: You should pass the Hard coded value Status = Failed as this indicates you are provided a Failed
transaction to Vindicia Retain for recovery. There is no case where you would pass a different value than Failed for
this data member to Vindicia Retain.

The rest of the required Data Members for Failed Transaction Submission:

Below are the rest of the data members & the values that should be provided for each, which is the same
information whether Full Credit Card Numbers are specified or if Tokens are used:

The timestamp value should be the (last) time that the Failed Transaction was attempted.

billingFrequency needs to be specified (i.e. 'Monthly', ' Annual', etc.)

The billing address should be provided as well, and the previous billing count for the subscription.

So below are the values that should be specified in the request:

authCode = declined authorization response code of last failure (i.e. 302, 530, etc.)
customerId = unique id of the Customer's account
divisionNumber = divisionId for Paymentech, merchantId for Litle, etc.
merchantTransactionId = unique id of Failed Transaction
paymentMethodId = Token at Payment Processor/gateway (Your unique identifier for the payment method w/o Tokens)
creditCardAccount = BIN, first 6 digits of Card (Full Credit Card Number if testing w/o Tokens)
status = 'Failed'
subscriptionId = unique id of the Customer's subscription
timestamp = timestamp of last failure
billingFrequency = ‘Monthly’, ‘Annual’ etc.
paymentMethodIsTokenized = True (False if testing without Tokens)

In addition, the following fields should be provided if possible:


previousBillingDate = date of last successful billing (i.e. for Monthly, this is last month’s successful Capture date)
previousBillingCount = number of previous successful billings associated with the subscription
subscriptionStartDate = date the subscription originally started


Note that the WSDL has a set of fields marked as required, but the above data members that are listed may include additional fields which are possibly marked as optional in the WSDL. We want the superset described above so that the application has available all of the data to be in position to make the best possible decision in recovering the Failed Transactions with the least risk of Chargeback.

  • Online Soap/WSDL Documentation:

  • Vindicia Retain WSDL File:

Sequence Diagram

Not Applicable

Use Case Implementation

Not Applicable

Sample Code

Not Applicable

Scenario Extensions



No Certification Required

Use Case #: SEL-006

For Users

Learn More
For Users

Vindicia Subscribe Features

Learn More
Vindicia Subscribe Features
Back to Top