Skip to main content
Vindicia Knowledge Center

Submit Failed Transactions for Recovery

Submit Failed Transactions for Recovery

User Story

Merchant needs to submit failed Transactions to Vindicia Retain so that the revenue may be recovered and the subscription preserved, extending the subscription lifetime.

Prerequisites

Pre-Condition

  • Transactions have failed and merchant has need to recover the revenue.

Post-Condition

  • Failed Transactions are received by Vindicia Retain, and are in process for possible recovery.

Basic Scenario

The merchant collects the set of failed Transactions on a regular basis, perhaps daily.  The set of failed Transactions is broken up into a number of fixed sized pages, and each page is submitted to Vindicia Retain in a loop.

For information on retrieving the results of Vindicia Retain Processing of failed Transactions, see Retrieve Results of Vindicia Retain Processing.

Design Approach

The merchant should submit transactions to Vindicia Retain via the billTransactions method, sometime after 6am EDT/ 3am PDT. Daily cutoff for submitting transactions via billTransactions is 12pm EDT/ 9am PDT.

As much information as possible about the originally failed Transaction should be provided to allow Vindicia Retain the best opportunity to recover the Transaction.  Specifically, the merchant's original Transaction Id should be passed in the merchantTransactionId data member on the Transaction object, and the merchant's Subscription Id should be passed in subscriptionId.

Additional data members that should be passed are:

  • previousBillingDate 
  • previousBillingCount 
  • customerId 
  • creditCardAccount
  • creditCardExpirationDate 
  • billingAddress
  • authCode, avsCode, and cvnCode (the auth, avs, and cvn result values for the original failed Transaction)

Vindicia Retain will only process a Transaction once for the value of merchantTransactionId that is provided.  Any duplicate submissions are therefore not processed assuming the same value for merchantTransactionId was specified.

Sequence Diagram

Use Case Implementation

Use the Vindicia Retain billTransactions method to submit a failed Transaction. This method accepts an array of Transactions representing the failed Transactions in the merchant system.  This call should be treated as a paged call, to reduce the bandwidth used and resulting timeout period required for a response.  Each Transaction submitted adds about 1 second to the response time.  Therefore, a pageSize of 200 is recommended so that the overall response time will be within 200 seconds, and the merchant SOAP client timeout needs to be larger than 200 seconds to avoid timeouts from occurring. In all cases, the pageSize should be less than 1000, to allow the log information to be viewable by Vindicia without truncation.  

Flow for Submitting Failed Transactions

Follow this flow when submitting failed Transactions. 

  1. For the total number of failed Transactions to be submitted in one day, divide up Transactions into separate pages of 200 Transactions each, and submit each page in a separate call to billTransactions.  Since the Transactions are in separate pages, it is ok to submit each page on different threads simultaneously, up to a maximum of 10 simultaneous calls to billTransactions.  (Exceeding the limit on maximum concurrency will result in a 503 error returned from billTransactions.)
     
  2. Once a call to billTransactions has returned successfully, the returned TransactionValidationResponse array, if any, should be inspected.  Each element in this array indicates that the submission of that Transaction was not successful, and the Transaction will therefore not be processed by Vindicia Retain.  Each such Transaction should be removed from the list of successfully submitted Transactions to Vindicia Retain. Thus, no response for these Transactions will be returned the next day when the results of Vindicia Retain Processing are fetched back. (For that reason, it is ok to resubmit the same call to billTransactions if it is not known what the original result of submission had been.)
     
  3. Between each call to billTransactions on each thread (or in the main process/single thread), insert a short delay to allow the prior call to completely release the resource handle to Vindicia Retain, so the Concurrency for that thread is released back.

 For information on retrieving the results of Vindicia Retain Processing of failed Transactions, see Retrieve Results of Vindicia Retain Processing.

Error Handling

For any errors found within individual TransactionValidationResponse array elements:

  • 400 Duplicate indicates that Vindicia Retain has already received this Transaction with the merchantTransactionId indicated. Two scenarios can return a 400 Duplicate error, as described in the following examples:
  1. "Billing has already been attempted for Transaction ID TEST123414."

    This error indicates that merchantTransactionId=TEST123414 has already been received by Vindicia Retain for processing, and this is a duplicate submission. This may be considered a successful submission.

  2. "Failed to schedule billing attempts: Attempt to bill Transaction ID TEST1234_14 with a subscriptionId (SUBS123414) that has already been processed by Vindicia Subscribe Vindicia Retain."

    This error indicates that merchantTransactionId=TEST1234_14 was not accepted by Vindicia Retain for processing because subscriptionId=SUBS123414 has already been submitted to Vindicia Retain on another Transaction which was accepted for processing on the same day.  This error is in place to avoid the inadvertent submission of more than one billing cycle per subscription on the same day, which would cause up to 8 authorizations (instead of the normal number of up to 4), which could easily trip some fraud alerts or otherwise degraded Vindicia Retain results.

    If more than one billing on a subscription needs to be submitted to Vindicia Retain, the second billing which returned the error above should be resubmitted to Vindicia Retain the next day. This error should not be returned on the next day, since no other billings on that subscription would have been submitted on that day.

  • 503 User Over Global Capacity indicates that the number of simultaneous calls to Vindicia Retain (that is, billTransactions and fetchBillingResults) has exceeded the Maximum allowed Concurrency limit.  To address this error code, introduce a short delay between sequential calls to give time for that connection to be released back to the pool, and/or reduce the number of running threads that are making calls to Vindicia Retain. 

If it is not clear whether a Transaction has been submitted to Vindicia Retain successfully, perhaps due to timeout, it is ok to resubmit the same billTransactions call again, and observe the TransactionValidationResponse array returned:  

  • Transactions that were submitted successfully on a prior call will return a 400 Duplicate, which may be interpreted as successfully submitted.  
  • Transactions that were not previously submitted successfully (either due to timeout or due to a previous 503 error) will return a result only if it is an error (successful submission of an individual Transaction will not generate a TransactionValidationResponse array element).

Sample steps and pseudo code using Select.billTransactions is listed below for reference:

0) Fetch the results of the previous day's Vindicia Retain processing. 

 For information on retrieving the results of Vindicia Retain Processing of failed Transactions, see Retrieve Results of Vindicia Retain Processing.

1) Collect Failed Transactions into pages of 200 each:

    n=(total Failed Transactions)/200 + (total Failed Transactions) % 200;

// + 1 for last page < 200

  transactions[0..n-1][200];             // n pages of 200 Transactions per page

2) Once per day (preferably the same time each day,) invoke the following code:

a) The parameters page, pageSize: will increment page in the loop; pageSize is tuning parameter:

  page = 0;           // increment for each iteration calls to Select.billTransactions 
  pageSize = 200;    // recommended size, requires > 200 second timeout in soap client

b) Loop through each page:

    do {

     return, transactionValidationResponse = Select.billTransactions ( transactions[page] );

     if ( return.returnCode == 200 ) {

           // check results, evaluate any TransactionValidationResponse array elements:
           // 400 Duplicate: Treat as successfully submitted (i.e. on a prior call)
           // Other errors, remove from list of successfully submitted to Vindicia Retain
           // (do not expect results tomorrow)

       }

   } 
   while ( page++ < n ); 

3) Execute the code in 1) and 2) the following day and every day.

Sample Code

Note that client libraries are not provided for Vindicia Retain.  The WSDL endpoint is used by the development
environment to generate a library that may be used, or direct WSDL posts may be used to submit
requests to Vindicia Retain.

This sample was built against a java library that was generated using the Axis wsdl2java
utility against the WSDL endpoint shown. 

To run this sample it is required to first generate the java library:

https://github.com/Vindicia/CashBoxAPISamples/tree/master/Select/Java/BillSelect

Certification

Please provide the Deployment Consultant with a SOAP ID from one call to billTransactions for review.

The submission should include transactions from a good and a bad card (i.e. transaction that will result in final state status of "Captured" and  "Cancelled", respectively.

When Cancel/Refund (SEL-003/SEL-005) is implemented include a third "good card" transaction that subsequently can be refunded. When a refund call is made the transaction's status will change from "Captured" to "Refunded".  The fetch operation performed for your SEL-002 Certification should include this "Refunded" transaction. 

Use Case #: SEL-001

For Users

Learn More
For Users

Vindicia Subscribe Features

Learn More
Vindicia Subscribe Features
Back to Top