Submit Failed Transactions to Retain for Recovery

You can submit failed Transactions to Vindicia Retain so that the revenue can be recovered and the subscription preserved, extending the subscription lifetime. To support this functionality, you must use the Retain APIs.

• Use Case: 5-8-01
• Completed By: Software Developer
• Estimated Completion Time: <5 days

​

Basic Scenario

You must regularly collect the set of failed Transactions, typically on a daily basis. You then break up the set of failed Transactions into a number of fixed sized pages, and submit each page to Vindicia Retain in a loop. Vindicia Retain then processes the failed Transactions to recover lost revenue. The following day, you must retrieve the results of the Vindicia Retain processing. For information about retrieving the results of Vindicia Retain Processing of failed Transactions, see Retrieve Results of Retain Processing.

​

Design Approach

You must submit transactions to Vindicia Retain using the billTransactions method, sometime after 6am EDT (3am PDT). Daily cutoff for submitting transactions using billTransactions is 12pm EDT (9am PDT). Provide as much information as possible about the originally failed Transaction to allow Vindicia Retain the best opportunity to recover the Transaction. Specifically, pass your original merchant Transaction ID in the merchantTransactionId data member on the Transaction object, and pass your merchant Subscription ID in subscriptionId. Also pass the following additional data members:

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

Vindicia Retain processes a Transaction only once for the value of merchantTransactionId that you provide. Any duplicate submissions that specify the same value for merchantTransactionId are not processed. As shown in the following diagram, the sequence for submitting failed Transactions is as follows:

1. For the total number of failed Transactions to be submitted in one day, divide the Transactions into separate pages of 200 Transactions each, and submit each page in a separate call to billTransactions.
2. Use the Vindicia Retain billTransactions method to submit a failed Transaction. This method accepts an array of Transactions representing the failed Transactions in your merchant system. Treat this call 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, the recommended pageSize is 200 so that the overall response time remains within 200 seconds. The merchant SOAP client timeout must be longer than 200 seconds to avoid timeouts from occurring. In all cases, the pageSize must be less than 1000, to allow the log information to be viewable by Vindicia without truncation.
3. After a call to billTransactions has returned successfully, inspect the returned TransactionValidationResponse array, if any. Each element in this array indicates that the submission of the referenced Transaction was not successful, and the Transaction is therefore not processed by Vindicia Retain. Remove each such Transaction from the list of successfully submitted Transactions to Vindicia Retain. No response for these Transactions will be returned the next day when you retrieve the results of Vindicia Retain Processing. (For that reason, you can resubmit the same call to billTransactions if you do not know what the original result of the submission had been.)
4. 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.

​

References

• For more information about working with the Vindicia Retain APIs, see the Vindicia Retain API Guide.
• For detailed information about the billTransactions method, see Select.billTransactions in the Vindicia Retain API Guide.
• Submit Failed Transactions Using the Retain APIs

Parent topic:Retain Use Cases

​

Submit Failed Transactions Using the Retain APIs

Fetch the results of the previous day’s Vindicia Retain processing (see Retrieve Results of Retain Processing). Note the following:

• Completed by: Software developer

To submit transactions:

1. Collect the 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. Submit the failed Transactions to Vindicia Retain using the billTransactions method. Once per day (preferably the same time each day), invoke the following code:
   1. The parameters page and pageSize will increment page in the loop; pageSize is a tuning parameter:
      
        page = 0;           // increment for each iteration calls to Select.billTransactions 
        pageSize = 200;    // recommended size, requires > 200 second timeout in soap client
      
      Note: Since the Transactions are in separate pages, you can submit each page on different threads simultaneously, up to a maximum of 10 simultaneous calls to billTransactions. (Exceeding the limit on maximum concurrency results in a 503 error returned from billTransactions.)
   2. 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 Steps a. and b. 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 you can use, or you can use direct WSDL posts 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 you must to first generate the Java library: https://github.com/Vindicia/CashBoxAPISamples/tree/master/Select/Java/BillSelect
3. If it is not clear whether a Transaction was successfully submitted to Vindicia Retain, for example due to timeout, you can resubmit the same billTransactions call again and observe the TransactionValidationResponse array returned:
   • Transactions that were submitted successfully on a prior call return a 400 Duplicate, which you can interpret as successfully submitted.
   • Transactions that were not previously submitted successfully (either due to timeout or due to a previous 503 error) return a result only if it is an error (successful submission of an individual Transaction does not generate a TransactionValidationResponse array element). Error Handling
   The following table provides additional information about potential errors found within individual TransactionValidationResponse array elements:

Provide the Solution Architect with a SOAP ID from one call to billTransactions for review. In the submission, include transactions from a good and a bad card (transactions that result in a final state status of Captured and Cancelled, respectively). When you implement the Cancel and Refund use cases (RET-006 and RET-007), include a third good card transaction that subsequently can be refunded. When a refund call is made the transaction’s status changes from Captured to Refunded. Include the fetch operation performed for your RET-005 Certification for this Refunded transaction. To retrieve the results of Vindicia Retain Processing, see Retrieve Results of Retain Processing. Parent topic:Submit Failed Transactions to Retain for Recovery