Retrieve Results of Retain Processing

You can retrieve the results of Vindicia Retain processing as a result of the previous day’s submission of failed Transactions to determine which Transactions were recovered. Subscriptions for recovered transactions can be saved and customer access restored, extending the subscription lifetime. To support this functionality, you must use the Retain APIs.

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

​

Basic Scenario

You must regularly retrieve the set of failed Transactions processed by Vindicia Retain, typically on a daily basis. You retrieve the final statuses of the Transactions that you submitted the day before. You must retrieve the processing results one page at a time, until no results are returned on a page.

​

Design Approach

• You must use the Vindicia Retain fetchBillingResults method to retrieve results from Vindicia Retain Processing each day after 6am EDT (3am PDT). Immediately after you retrieve results, you can submit the set of new Transactions to Vindicia Retain. Daily cutoff for submitting transactions is 12pm EDT (9am PDT).
• You retrieve the results of the current day’s submission the following morning.

​

Use Case Implementation

As shown in the following diagram, you must call Vindicia.Soap.Select.fetchBillingResults to retrieve the results of Vindicia Retain Processing. Vindicia.Soap.Select.fetchBillingResults accepts a start and end time that defines the time window of processing results to retrieve from the previous day’s submission of failed Transactions to billTransactions. As Vindicia Retain batches are processed once per day, the time interval during which changes are reported is 24 hours. Vindicia recommends that you choose a similar time each day to invoke the retrieval process, usually in the morning. (It is acceptable to choose a time interval shorter than 24 hours, but in that case you must invoke the retrieval process more times within the day to ensure complete coverage of the full time window, as the time the final status is determined varies throughout the day.) Given that the call to Vindicia.Soap.Select.fetchBillingResults is a paged call, select an appropriate pageSize to keep the response size and resulting response time down to a manageable value. For this purpose, a pageSize of 200-500 is reasonable, based on the total number of Transactions to be retrieved and the daily submission volume. The initial call to fetchBillingResults using the start and end timestamps performs the initial query which is cached from the database, and therefore typically takes the most time to respond. Each call to fetchBillingResults on subsequent pages using the identical start and end timestamps (saved in variables initially) accesses the cached database query results, pulls out the results for the requested page, and returns that page of results. When no results are returned on a requested page, the loop of paged calls completes and all results are retrieved. As the initial call to fetchBillingResults (for page 0) performs the database query and causes the query results to be cached, you can repeat this call on a timeout. The second time the same call comes in, the cached results may be available and returned without a timeout. For this reason, if any timeouts are experienced in the fetchBillingResults call for any page, you can resubmit the same call. Note that for timeouts due to the pageSize used, you can recover them only by reducing the pageSize or by increasing the local timeout. You can recover timeouts due to the query duration by a simple resubmission. The query results are cached from the initial call, and that query will likely have completed by the time the resubmission occurs. Each Transaction returned contains:

• The value of merchantTransactionId, corresponding to the unique merchant identifier of the original failed Transaction.
• A value in selectTransactionId, which is the unique identifier for the Vindicia Retain Transaction corresponding to the reprocessing of the Transaction, assigned by Vindicia Retain and sent to the Payment Processor for the final attempt. The value returned in selectTransactionId is sent to the Payment Processor in reverse order. When viewing any Transactions in the Payment Processor Online access, the Retain Transaction can be identified by first reversing the value of selectTransactionId and then providing it to the Payment Processor in an Order Number or other field. For example, for selectTransactionId=ABC123456, 654321CBA is sent to the Payment Processor.
• The final status for the Vindicia Retain Transaction is returned for each Transaction in the status field, and will be either Captured or Failed, depending on whether Vindicia Retain was able to recover the Transaction or not.

​

Performance and Concurrency

For most cases, even with sufficiently high daily volume, a single thread or process using a single sequential loop is typically satisfactory for overall completion time. This is because the call to fetchBillingResults is a batched call that runs only once per day to pick up results of the prior day’s Vindicia Retain processing. If you deem this too restrictive based on other timing constraints, you can request each page on different threads simultaneously, after the initial call to fetch page 0 has successfully completed, up to a maximum of 10 simultaneous calls to fetchBillingResults. Exceeding the limit on maximum concurrency results in a 503 error being returned. Between each call to fetchBillingResults 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 API, see the Vindicia Retain API Guide.
• For detailed information about the fetchBillingResults method, see Select.fetchBillingResults. in the Vindicia Retain API Guide.
• Retrieve Processing Results Using the Retain APIs

Parent topic:Retain Use Cases

​

Retrieve Processing Results Using the Retain APIs

Submit failed transactions to Retain (see Submit Failed Transactions to Retain for Recovery.) Note the following:

• Completed by: Software developer

To retrieve results from Retain, see the following sample steps using Select.fetchBillingResults :

1. Initialize the start time once:
   
       next_start = now() - 1 day;   // (or set to before initial call to billTransactions) 
   
   
   Save the variable next_start in your database, as it will be used and updated each day.
2. Once per day (preferably the same time each day), invoke the following code:
   
   start = next_start; // do not set to now() - 1 day, as it might have been longer than a day
   end = now();        // time window requested is between most recent call and current time
   
   1. The parameters page, and pageSize will increment page in the loop; pageSize is a tuning parameter:
      
      page = 0; // increment for each iteration calls fetchBillingResults
      pageSize = 10; // can be larger, such as 100 if higher volume expected. Can be tuned.
      
   2. Loop through each page, using the same start and end times for efficiency in the query time:
      
          do {
              return, transactions = fetchBillingResults(start, end, page, pageSize);
              if ( return.returnCode == 200 ) {
      
              // check results, update local entitlement statuses here
      
              // the returned array of transactions contains one Vindicia Retain Transaction
              // object for each Transaction which has reached a final status in 
              // Vindicia Retain Processing, such as Captured or Cancelled. 
      
          }
          count = array_size(transactions); // # of Transaction objects returned
          page++; // to next page
          }
          while ( count > 0 );
      
      
      
   3. Update the start time for the next call (to be used in the following day’s execution):
      
          // only update if no errors occurred (i.e. return.returnCode == 200) in the loop above
          next_start = end - 1 minute; // to be inclusive of any updates to db in the last minute
      
          // Note: To be inclusive of all time windows for which a Transaction result may come
          // back, it is important to handle the case where a duplicate Transaction is returned.
          // To handle this case, if a Transaction result is already in your database, then
          // the Transaction result for that Transaction should be ignored.
      
          // The next_start variable is only updated when no errors occurred. This causes the
          // same window to be included on the next execution to pick up results covering the
          // window where a prior error occurred.
      
      
      
3. Execute the code in Step 2 the next day and every day, so the time window includes all calls to billTransactions submitted on the prior day and the results for all Transactions submitted.
4. Submit the current day’s failed Transactions to Vindicia Retain for processing. See Submit Failed Transactions to Retain for Recovery. 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 first generate the Java library: https://github.com/Vindicia/CashBoxAPISamples/tree/master/Select/Java/FetchSelect Error Handling The error 503 User Over Global Capacity indicates that the number of simultaneous calls to Vindicia Retain (using 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 to the pool, and/or reduce the number of running threads that are making calls to Vindicia Retain. If a timeout occurs on page 0, you can resubmit the same request after a short delay. The results are then returned in a much shorter timeframe due to the cached results available. For timeouts on any other page after the first, it is likely that the pageSize is too large, or that the local timeout is too short. However, you can resubmit the same request on timeout. As long as another timeout does not occur, the same information is returned. This can be treated the same as no error, and the full date including all of the previous day’s Vindicia Retain results are returned when the full loop of pages is completed, until 0 results are returned. Certification Provide the Solution Architect with SOAP IDs from two calls to fetchBillingResults from a single loop execution for review:
   • SOAP ID #1: one for the first page (that is, page 0)
   • SOAP ID #2: for the final page in the loop (with 0 results returned)

Parent topic:Retrieve Results of Retain Processing