Integrating with Vindicia Retain
Vindicia Retain Overview
Vindicia Retain is a SaaS-based recurring billing solution that resolves failed payment transactions. Vindicia Retain provides access to new functionality while minimizing the technical footprint within the Client’s environment. Rather than a “rip and replace” implementation, which can require several months of effort, Vindicia Retain enables the merchant to keep the existing billing system in place. Only the Vindicia Vindicia Retain retry logic operates outside of the existing billing system. Results for all transactions are passed back to the existing billing system and all customer management remains unchanged.
This approach has just two notable touch points: sending transactions out from the Client, and receiving updates back into the same system. The rest of the flow utilizes the existing Client infrastructure. Email notifications should come from the Client, entitlements continue to be managed by Client, and so on. Vindicia touches as little Client functionality as possible.
Vindicia Retain implementation uses either the Client's in-house resources or external resources provided by Vindicia. If Vindicia Retain is implemented using Vindicia resources, Vindicia makes code modifications in combination with Client internal resources. Implementation should be thoroughly tested. To ensure a smooth transition into production, Vindicia recommends that the Client deliver the code modifications into a standard Client QA sequence before releasing into production.
Client Billing Run Output
At the end of a batch billing run, the Client reports the results of the run to Vindicia. All failed transactions that have run through the Client's current retry attempts should be reported for retries using Vindicia Retain.
The reporting API call is Select.billTransactions(). The SOAP call allows the merchant to send a batch of transactions to Vindicia, with the following key information:
- Merchant Transaction ID
- Transaction Amount
- Processor Response code
- Payment Method
- Additional information as needed
Vindicia will work with Client personnel to identify the appropriate place in the batch flow to report these transactions. This may be directly within the flow, or it may be a simple standalone batch job that runs at the end of a billing run. In either case, the process generates a list of transactions and makes a SOAP call to Vindicia to report the transactions to Vindicia Subscribe. For efficiency, transactions should be grouped into batches of hundreds or thousands per SOAP call.
Upon receipt, Vindicia stores the transactions in the Vindicia Subscribe database. For each transaction, Vindicia Subscribe uses Vindicia Retain to make one or more attempts to successfully process the transaction. It is possible to receive a partial authorization in processing. This occurs typically with a credit card near the credit limit or a debit card or gift card that is nearly out of funds. Vindicia combines the partial authorization data with additional data gleaned from analysis of over $4B in digital commerce, in order to decide an appropriate course of action. Those actions may include:
- Accept the partial value available.
- Obtain the full value of the transaction, regardless of partial amount available.
- Decline to process the transaction.
Vindicia uses Client-specific configuration parameters to set thresholds and provide other guidance to the processing logic, working directly with Client personnel to determine the specific parameter settings to use.
After transactions are received by Vindicia, Vindicia Subscribe processes the failed transactions as described above. All transaction results are stored in the Vindicia Subscribe database.
Vindicia or the Client writes a small batch job to run within the Client environment and collect the results of those transactions. This process uses Select.fetchBillingResults() to retrieve information on transactions which have changed status since the input timestamp. Return information includes:
- Subscriber Identifier
- Merchant Transaction ID (for the new transaction)
- Transaction Amount
- indicator of partial or full capture
- Processor Response code
- Additional relevant information
For transactions that were successfully processed, the batch job needs to tell the Client system that the user was successfully billed and should remain entitled to service. If the transaction is processed as a partial authorization, the Client may send a notification to the user announcing that the user has received an "instant discount”, or similar marketing message. If the transaction fails, the user should be disentitled. The Client may send a notification to the user indicating that billing was unsuccessful, and ask the user to resubscribe. In either case, updates and notifications should be handled via existing methods within the Client billing system.
This diagram shows the workflow for submitting transactions to Vindicia and fetching the results.
Additional Design Considerations
Additional design considerations are addressed during implementation. Some examples include race conditions and entitlement handling during retries, as described below.
In some situations, a user may update card information at the same moment that Vindicia Subscribe is processing the user's payment via Vindicia Retain. In this situation, the user is billed twice: once on the existing card, and once on the new card. In such cases, the return processing job issues a refund against the transaction using Select.refundTransactions(). The original transaction from the Client billing system remains and no further action is required.
Vindicia recommends that the Client call Refund.Transactions() after receiving updated payment method information from a customer. If a transaction has not yet been successfully processed, Vindicia Retain automatically cancels the pending retry to ensure that the customer is not billed twice.
Entitlement Handling During Retries
Vindicia recommends that the Client allow a customer to remain entitled while retries take place in Vindicia Subscribe. This ensures that the customer is not charged after being denied access.
The Client may also choose to implement a failsafe strategy. For example, the Client might disentitle any user following a specified number of hours after the last retry, unless Vindicia provides confirmation that the billing was successful. Such a strategy would allow adequate time for any retry to succeed, and still ensure that the Client terminates any customer who is not successfully processed.
If the Client architecture requires some other method to turn off entitlements (such as a proactive call), Vindicia can design an appropriate mechanism during deployment.
Either Vindicia or the Client can lead appropriate testing of the two technical interfaces described here. Because the implementation must be tested to ensure that it works fully with the rest of the Client infrastructure, Vindicia and the Client should plan the testing to enter an appropriate release cycle and go through a full test suite within Client’s normal release process. Vindicia can provide documented test cases and data prep to facilitate this testing.