Vindicia Retain API Overview
Vindicia Retain was created for large clients, selling digital goods on a recurring basis, who manage their own billing system.
Vindicia Retain is designed to perform the billing only for those credit card transactions that the client has been unable to capture, and for which the client will make no further attempts to collect from the customer.
Even with robust, successful billing systems in place, there is a percentage of customers lost every month because the merchant could not collect on the bill. On a monthly subscription service, you can often double your customer lifetime value by maintaining a connection with those customers whose payment method might otherwise have failed. This is critical because these customers want to use your service, and have not actively opted out.
Vindicia Retain analyzes reported data to determine whether a transaction is likely to be successfully captured by ART. Because we understand which transactions have the highest likelihood of success, there is minimal impact to your chargeback volumes or rate, and we will fight those that are submitted on your behalf.
Note While Vindicia Retain clients do not use Vindicia Subscribe itself, they do have access to Vindicia’s ChargeGuard services for any of their Transactions.
Vindicia Subscribe uses Vindicia’s patent pending Advanced Retention TechnologyTM or “ART" to capture these transactions. Vindicia identifies which transactions for any given Vindicia Retain client are eligible for ART using a variety of factors including:
- Transaction history across all Vindicia Subscribe clients,
- Transaction history across clients that are similar to the specific client
- The client’s successful and failed Transaction activity
- Reason codes for the failed transactions
- BIN data and individual bank behaviors
- Chargeback data cross all merchants
- Transaction price point
Using Vindicia Retain not only allows you to capture failed transactions, it also grants you extended lifetime from your subscribers. Instead of a subscriber dropping from your service due to a single failed transaction, Vindicia Retain may capture that transaction, allowing you to continue to bill for subsequent periods, as if you had successfully captured the transaction yourself.
Use the billTransactions method to report an array of Transactions to Vindicia Retain for processing.
Vindicia will run Advanced Retention Technology on the Transactions (described below), which will include Account Updater, retry logic and partial authorization.
Use fetchBillingResults to retrieve Transactions which have completed their Vindicia Retain processing cycle. (The returned results from this call will include any new payment method information available as a result of the Account Updater process. Vindicia Subscribe will encrypt the card using your public key before returning it to you. If the payment method did not change, Vindicia Retain will not pass any value in this field.) Vindicia Retain also allows you to retrieve Chargeback information using the fetchChargebacks call.
Note To use the Vindicia Retain Account Updater, you must submit a PGP public key and encrypt any returned credit card information. Vindicia Retain will use this key to encrypt credit card numbers for return in thefetchBillingResults call. You must also have completed an Attestation of Compliance (AOC) as a declaration of the results of the service provider's assessment with the Payment Card Industry Data Security Standards (PCI DSS).
Work with your Vindicia Client Services representative to enable Account Updater with Vindicia Retain.
Vindicia Retain offers several settings by which merchants may customize billing attempt parameters:
- Partial Authorization Threshold (percentage): for a partial authorization received above this threshold, Vindicia Subscribe will not perform additional logic to attempt to capture the full amount of the Transaction. Vindicia Subscribe will only capture the partial amount.
- Full Deposit Threshold (percentage): for a partial authorization received below this threshold, Vindicia Subscribe will not perform additional logic to attempt to capture the full amount of the transaction, and the transaction attempt will be treated as a failure. For a partial authorization received above this threshold and below the Partial Authorization Threshold, an attempt to capture the full amount will be made.
- Forced Deposit: this flag indicates whether or not Vindicia Retain will attempt to capture the full amount of a transaction, even when the authorization was declined (as opposed to only partially approved).
- ART Attempt Threshold: defines the first attempt upon which Vindicia Retain will apply ART.
Vindicia Retain Objects
Each Vindicia Retain object consists of data members, which fall into one of the following categories:
- Standard, built-in data types, such as integers or strings, that are common to programming languages.
- Enumerations, which are scalar types coded as standard data types, but which are restricted to a specific set of legal values.
- Data structures, which consist of multiple data members, each of which can be of different data types.
- Arrays, containing zero or more data elements, all of which must be the same data type.
Vindicia Retain’s methods are functions which require one or more input arguments. Methods always return a code that indicates the success or failure of the function call. In the event of failure, the code value and description will indicate why the call failed.
The Vindicia Retain API is a structured language, and requires input parameters to be entered in the order shown. Parameters must be place-marked if not specified.
This guide presents Objects, their data members, and methods alphabetically, for ease of reference. Variable parameters for the methods are presented in syntactical order.