> ## Documentation Index > Fetch the complete documentation index at: https://docs.vindicia.com/llms.txt > Use this file to discover all available pages before exploring further. # 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](5802_retrieveResultsRetainProcessing#). ## 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](/portal/Retain_V1.5_API_Reference_Guide/topics/Vindicia_Retain_API_Guide_Preface). * For detailed information about the billTransactions method, see [Select.billTransactions](/portal/Retain_V1.5_API_Reference_Guide/topics/billTransactions) in the [Vindicia Retain API Guide](/portal/Retain_V1.5_API_Reference_Guide/topics/Vindicia_Retain_API_Guide_Preface). * **[Submit Failed Transactions Using the Retain APIs](../topics/5801_submitFailedTransactions#)** **Parent topic:**[Retain Use Cases](../topics/r_useCases) ## Submit Failed Transactions Using the Retain APIs Fetch the results of the previous day's Vindicia Retain processing (see [Retrieve Results of Retain Processing](5802_retrieveResultsRetainProcessing#)). 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](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: | Error | Description | | - | - | | `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. You can consider this 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 will cause up to 8 authorizations (instead of the normal number of up to 4), which can easily trip some fraud alerts or otherwise degrade Vindicia Retain results. If you must submit more than one billing on a subscription to Vindicia Retain, you must resubmit the second billing which returned the error above to Vindicia Retain the next day. This error will be returned on the next day, since no other billings on that subscription will be 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. | | **Certification** | | 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](5803_cancelSubmittedTransactions#) and [RET-007](5804_refundTransaction#)), 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](5802_retrieveResultsRetainProcessing#) Certification for this `Refunded` transaction. To retrieve the results of Vindicia Retain Processing, see [Retrieve Results of Retain Processing](5802_retrieveResultsRetainProcessing#). **Parent topic:**[Submit Failed Transactions to Retain for Recovery](../topics/5801_submitFailedTransactions#) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.