Skip to main content
Vindicia Retain is a Software as a Service (SaaS)-based recurring billing solution that resolves failed payment transactions, while also minimizing the technical footprint within your environment. The Vindicia Retain retry logic operates outside of your existing billing system, passing the results for all transactions back to your billing system so that all of your internal customer management remains unchanged. Rather than a “rip and replace” implementation, which can require several months of effort, Vindicia Retain enables you to keep your existing billing system in place. This approach has two touch points: sending transactions out from your system, and receiving updates back into your system. The rest of the flow uses your existing merchant infrastructure to manage entitlements, send email notifications, and so on. Vindicia touches as little of your system’s functionality as possible.

​
Vindicia Retain Implementation

To staff the Vindicia Retain implementation, you can use either your in-house personnel or external resources provided by Vindicia. If you choose Vindicia resources, they will implement the required code modifications in coordination with your internal team. The implementation must be thoroughly tested. To ensure a smooth transition into production, Vindicia recommends that you deliver the code modifications into a standard QA sequence before releasing to production.

​
Billing Run Output

At the end of a batch billing run, you report to Vindicia Retain all transactions that have failed your final internal retry attempts. The SOAP reporting API call is Select.billTransactions(), which allows you to send a batch of transactions to Vindicia. Vindicia will work with your team to identify the appropriate point in the batch flow to report these transactions, either directly within the flow or as part of 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 report the transactions to Vindicia Retain. For efficiency, group the transactions into batches of hundreds or thousands per SOAP call.

​
Vindicia Processing

Upon receipt, Vindicia stores the transactions in the Vindicia database. For each transaction, Vindicia Retain makes one or more attempts to successfully process the transaction.

​
Partial Authorization

When Vindicia Retain processes the transaction, it can receive a partial authorization. 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 digital commerce analysis to determine an appropriate course of action. These actions can include:
  • Accept the partial value available.
  • Obtain the full value of the transaction, regardless of the partial amount available.
  • Decline to process the transaction.
Vindicia uses your merchant-specific configuration parameters to set thresholds and provide guidance to the processing logic, working directly with your personnel to determine the specific parameters to use.

​
Vindicia Returns

All transaction results are stored in the Vindicia database. Your team (or Vindicia) must write a small batch job to run within your environment to collect the results of the transactions you previously submitted to Select.billTransactions(). This process uses Select.fetchBillingResults() to retrieve information about transactions that have changed status since the input timestamp. For each transaction that is successfully processed, the batch job must update your system to indicate that the subscriber was successfully billed and can remain entitled to the service. If the transaction is processed as a partial authorization, you can send a notification to the subscriber announcing that they have received an instant discount, or similar marketing message. If the transaction fails, the subscriber must be disentitled. Your system can send a notification to the subscriber indicating that billing was unsuccessful, and ask the subscriber to resubscribe. Regardless of the scenario, updates and notifications are handled using existing methods within your merchant billing system.

​
Sequence Diagram

The following diagram shows the workflow for submitting transactions to Vindicia Retain and fetching the results.

​
Testing

Either your team or Vindicia can lead appropriate testing of the two technical interfaces described here. The implementation must be tested to ensure that it works fully with the rest of your infrastructure. Your team must plan the testing with Vindicia to enter an appropriate release cycle and go through a full test suite within your normal release process. Vindicia can provide documented test cases and data preparation to facilitate this testing.

​
Additional Design Considerations

Additional design considerations are addressed during implementation. Some examples include race conditions and entitlement handling during retries, as described in the following sections.

​
Race Conditions

In some cases, a subscriber may update their card information at the same moment that Vindicia Retain is processing the subscriber’s payment. In this situation, the subscriber is billed twice: once on the existing card, and once on the new card. As a result, if a subscriber provides you with updated payment method information after you submit a transaction to Retain, Vindicia recommends that you call Refund.Transactions (). In this case, if the transaction was already successfully processed, Vindicia issues the necessary refund of the duplicate transaction. And if the transaction was not yet processed, Vindicia Retain cancels the pending retry to ensure that the customer is not billed twice.

​
Entitlement Handling During Retries

Vindicia recommends that you allow a customer to remain entitled while retries take place in Vindicia Retain. This ensures that the customer is not charged after being denied access. You can also choose to implement a fail-safe strategy. For example, you can disentitle any subscriber following a specified number of hours after the last retry, unless Vindicia provides confirmation that the billing was successful. Such a strategy provides adequate time for any retry to succeed, and still ensures that you terminate any customer who is not successfully processed. If your system architecture requires some other method to turn off entitlements (such as a proactive call), Vindicia can design an appropriate mechanism during deployment.

​
Getting Started with Retain Use Cases

The Retain Use Cases describe how you can integrate Vindicia Retain with your merchant system and submit failed transactions for recovery. However, before you can perform the Retain Use Cases, you must first complete the following prerequisites: