Skip to main content
Vindicia Knowledge Center

Retrieve Results of Vindicia Retain Processing

Retrieve Results of Vindicia Retain Processing

User Story

Merchant needs to retrieve results of Vindicia Retain processing as a result of yesterday's submission of failed Transactions in order to determine which failed Transactions were recovered. Subscriptions for recovered failed transactions can be saved and customer access restored, extending the subscription lifetime.

Prerequisites

Pre-Condition

Post-Condition

  • Failed Transactions processed by Vindicia Retain have been retrieved and local entitlement status has been updated accordingly.

Basic Scenario

The merchant collects the set of failed Transactions on a regular basis, perhaps daily.  The set of final Transactions processed by Vindicia Retain (corresponding to the failed Transactions submitted the day before) is retrieved one page at a time until no results are returned on a page.

Design Approach

  • Merchant uses the Vindicia Retain fetchBillingResults method to retrieve results from Vindicia Retain Processing each day after 6am EDT/ 3am PDT, immediately followed by submission of Transactions to Vindicia Retain. Daily cutoff for submitting transactions is 12pm EDT/ 9am PDT.
  • Results are obtained the next morning after submission of transactions to Vindicia Retain.

For information on submitting failed Transactions, see Submit Failed Transactions for Recovery.

Sequence Diagram

Use Case Implementation

Call Vindicia.Soap.Select.fetchBillingResults to retrieve results of Vindicia Retain Processing.

Vindicia.Soap.Select.fetchBillingResults is a paged call, which accepts a start and end time that defines a window during which Vindicia Retain Processing has determined final Transaction statuses corresponding to the failed Transactions previously submitted to Vindicia Retain for processing by the call to billTransactions.

As Vindicia Retain batches are processed once per day, the time interval during which changes will be reported is 24 hours. It is recommended that merchants choose a similar time each day when the retrieval process is invoked, usually in the morning . (It is acceptable to choose a time interval shorter than 24 hours, but in that case it will be necessary to 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.)

The call to Vindicia.Soap.Select.fetchBillingResults is a paged call, so an appropriate pageSize should be selected 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 (saved in variables) will perform the initial query which will be 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) will access the cached database query results, pull out the results for the requested page, and return that page of results. When no results are returned on a requested page, the loop of paged calls completes and all results have been retrieved.

As the initial call to fetchBillingResults (for page 0) performs the database query and causes the query results to be cached, this call may be repeated on 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, the same call may be resubmitted on timeout.

Note that timeouts due to the pageSize used can be recovered only by reducing the pageSize or by increasing the local timeout. Timeouts due to the query duration may be recovered by a simple resubmission. The query results will be cached from the initial call, and that query will likely have completed by the time the resubmission occurs.

Each Transaction returned will contain:

  • the value of merchantTransactionId, corresponding to the merchant's unique 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 Select Transaction can be identified by first reversing the value of selectTransactionId and then typically  sent to the Payment Processor in an Order Number or other field. For example, selectTransactionId=ABC123456, and 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 should be satisfactory for overall completion time, as this is a batched call that runs only once per day to pickup results of the prior day's Vindicia Retain processing.  If this is deemed too restrictive based on other timing constraints, it is ok to request each page on different threads simultaneously after the initial call to fetch page 0 has successfully completed, up to a maximum of about 10 simultaneous calls to fetchBillingResults.  Exceeding the limit on maximum concurrency will result in a 503 error being returned from fetchBillingResults.

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 back.

Error Handling

The error 503 User Over Global Capacity indicates that thenumber 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 back 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, after a short delay the same request may be re-submitted, and the results should then be 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, it is ok to resubmit the same request on timeout. As long as another timeout does not occur, the same information will be returned. This may be treated the same as no error, and the full date including all of yesterday's Vindicia Retain results will be returned when the full loop of pages is completed until 0 results returned.

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

1) Initialize start time once; will be updated each day:

    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 & 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

a) The parameters page, pageSize: will increment page in the loop; pageSize is 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.

b) Loop through each page, using same start & end times for efficiency in 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 );

c) Update start time for next call (o be used in tomorrow'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 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 today's failed Transactions to Vindicia Retain for processing.  See Submit Failed Transactions 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 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/FetchSelect

Certification

Please provide the Deployment Consultant with SOAP IDs from two calls to fetchBillingResults from a single loop execution for review: 

  1. SOAP ID #1:  one for the first page (that is, page 0).
  2. SOAP ID #2: for the final page in the loop (with 0 results returned).

Use Case #: SEL-002

For Users

Learn More
For Users

Vindicia Subscribe Features

Learn More
Vindicia Subscribe Features
Back to Top