Skip to main content
Vindicia Knowledge Center

Vindicia Retain Methods

Vindicia Retain Methods

 

The core Select Methods include the following:

  • billTransactions—(required) submit failed transactions to Select for processing
  • fetchBillingResults— (required) retrieve final results of Select processing
  • refundTransactions— (optional) cancel/refund a transaction submitted to Select

Implementations of core Select Methods are evaluated during merchant Select Certification. Refer to the respective Use Cases for what Certification expects of implementations that use these methods.

See the The Transaction Object for information about the values passed to and returned by these Select Methods.

Example programs calling Vindicia Retain Methods

Example programs in C#, Java, PHP and Python that demonstrate using the Select Methods are available on github. An example in Ruby is also available on github.

Pseudo code for calling Vindicia Retain Methods

Although pseudo code for calling Vindicia Retain Methods is provided with the Methods described below, this API Guide is primarily a reference, and as such is more concerned with describing the inputs and outputs of the Methods than with how they should be used in an application. For more information about what  Select Certification expects in your implementation, follow the links to the associated Use Case in each of the required methods. 

The following table summarizes the methods for Vindicia Retain.  

Method Description

billTransactions

(Required to implement Use Case SEL-001)

Submit transactions to Vindicia Retain for processing.

fetchBillingResults

(Required to implement Use Case SEL-002)

Returns the Vindicia Retain results over a specified time period. All transactions that have reached a terminal state during the specified time period are returned.
fetchByMerchantTransactionId Returns the transaction specified by the merchant transaction ID.
fetchChargebacks Returns an array of Chargeback objects received from your payment processor.

refundTransactions

(Required to implement Use Cases SEL-003 and SEL-005)

Sends an array of transactions to Vindicia Retain to be canceled or refunded. Captured transactions are refunded, transactions not captured are canceled. 
reportTransactions

Reports data to Vindicia Retain for use in fighting chargebacks resulting from transactions not processed through Vindicia Retain.

Select.billTransactions

Submits transactions to Vindicia Retain for processing. This call is required to implement Select Use Case SEL-001.

Use fetchBillingResults to retrieve final results of Vindicia Retain processing on transactions submitted via billTransactions; see fetchBillingResults for details

Input

transactions: an array of Transaction objects. For a given transaction that has failed at your payment processor, submit only the final failed attempt to Vindicia Retain. 

Note Do not populate the VID field in any new transaction submitted with this method. Vindicia Retain populates this data member in the fetchBillingResults call.

Output

return: an object of type Return that indicates the success or failure of the call.

response: an object of type TransactionValidationResponse Values, which includes the ID of the Transaction returning an error.

Note An empty TransactionValidationResponse object indicates that the call succeeded without error. For more information, see TransactionValidationResponse Values. 

Note 

Returns

This method returns the codes listed in Select Return Codes

Example

$tx = new Transaction();
$tx->setTimestamp('2012-09-11T22:34:32.265-4:00');
$tx->setAmount('9.90');
$tx->setCurrency('USD');
$tx->setStatus('Failed');

$tx->setDivisionNumber('54321');
// Merchant Transaction ID must be unique for each new
// transaction you want Vindicia to process.
$tx->setMerchantTransactionId('TxPrfx123');
// Merchant Subscription ID should be unique for each new
// transaction-subscription you wish Vindicia to process.
$tx->setSubscriptionId('AbPrfx456');
$tx->setBillingInterval('Yearly');
$tx->setPreviousBillingDate('2011-09-11');
$tx->setPreviousBillingCount('24');
// Merchant Customer ID should be unique for each unique Customer.
$tx->setCustomerId('McPrfx789');
$tx->setPaymentMethodId('PmPrfx012');
$tx->setPaymentMethodIsTokenized(false);
$tx->setCreditCardAccount('4111111111111111');
$tx->setCreditCardExpirationDate('20121212');
$tx->setAccountHolderName('Calvino Hobbes');
$tx->setBillingAddressLine1('Suite 200');
$tx->setBillingAddressLine2('23 George Street');
$tx->setBillingAddressCity('Larkspur');
$tx->setBillingAddressDistrict('CA');
$tx->setBillingAddressPostalCode('94964');
$tx->setBillingAddressCountry('US');

$nv1 = new NameValuePair();
$nv1->setName('CriminalOffense');
$nv1->setValue('Wire Fraud');
$nv2 = new NameValuePair();
$nv2->setName('Sentence');
$nv2->setValue('25 years');
$tx->setNameValues(array{$nv1, $nv2});
$tx->setAuthCode('110');
$select = new select();
$ret = $select->billTransactions(array{$tx});
if($ret['returnCode'] == 200)
{
$failedTransactions = $ret['response'];
if($failedTransactions && (sizeof($failedTransactions) > 0))
{

foreach ($failedTransactions as $transaction)
{
//Evaluate Transaction failure response here.
}
}
}
else
{
//Handle error condition.
}

Select.fetchBillingResults

Returns an array of completed transactions. Only those transactions that have reached a terminal status (Captured, Canceled, Refunded, or Failed) during the time period specified are returned. This call is required to implement Select Use Case SEL-002.

Note Vindicia Retain requires that input parameters be entered in the order shown, and place-marked with null if not specified.

Paging is supported using page and pageSize. Continue calling the function until the length of the resulting array is 0.

Note To use the Vindicia Retain Account Updater during Deployment, contact your Vindicia Solutions Architect; after go-live, contact Vindicia Customer Support. You must also have completed an Attestation of Compliance (AOC) as a declaration of the results of the service provider's assessment with the Payment Card Industry Data Security Standards (PCI DSS).

You must provide a PGP public key to Vindicia to encrypt returned credit card information.

Input

timestamp: the starting timestamp for the range of (terminal state) Transactions you want to retrieve.

endTimestamp: the ending timestamp for the range of (terminal state) Transactions you want to retrieve.

page: the page number, starting at 0, for which to return the results. For example, if the total number of results is 85 and pageSize is 10:

  • Specifying 0 for page gets the results from 1 through 10.
  • Specifying 2 for page gets the results from 21 through 30.

pageSize: the number of records to display per page per call. This value must be greater than 0.

Output

return: an object of type Return that indicates the success or failure of the call.

transactions: an array of Transaction objects that have reached a terminal status during the time period specified with timestamp and endTimestamp.

Note: Each Transaction object returned will identify the original transaction submitted via the merchantTransactionId and the last transaction processed as the selectTransactionId. Thus, terminal results for every transaction submitted on a given day should have been retrieved by or as of the fetch following the final retry. 

Returns

This method returns the codes listed in Select Return Codes.

Example

 

Select.fetchByMerchantTransactionId

Returns the Transaction specified by the input merchantTransactionId. Use this method to fetch specific transactions. Use fetchBillingResults to retrieve all results in a single call.

Use this method also to confirm that Select received a transaction when the merchantTransactionId was provided. It returns the transaction that was submitted, but it does not return the final processing status of the transaction. Use fetchBillingResults to obtain the final processing status. 

When a transactionId, that is, the transaction processing Id of a Select processing step (retry) after submission, is provided, that transaction is returned. Note that the only way to find out the final state of a transactionId is by by using the fetchBillingResults call. This means that you should already have received all final state results. Making this call with a transactionId that you got from fetchBillingResults would only provide the same results.

This method is not required to implement any Use Case. Per SEL-002, you must use fetchBillingResults for regular fetches in Production.

Input

merchantTransactionId: the merchantTransactionId for the transaction to fetch.

Output

return: an object of type Return that indicates the success or failure of the call.

transaction: the transaction identified by the TransactionId.

Returns

This method returns the codes listed in Select Return Codes.

Example

$select = new select();
//Assume we have a merchantTransactionId 'TxPrfx123'
//that we want to retrieve information on.
$merchantTxId = 'TxPrfx123';
$ret = $select->fetchByMerchantTransactionId($merchantTxId);
if($ret['returnCode'] == 200)
{
$fetchedTransaction = $ret['transaction'];
//Process fetched transaction here...
}
else
{
//Handle error condition.
}

 

Select.fetchChargebacks

Returns a list of Chargeback objects that have changed status since the input timestamps. Paging is supported using page and pageSize. Continue calling the function until the length of the resulting array is 0.

Note Vindicia Retain requires that input parameters be entered in the order shown, and place-marked with null if not specified.

Input

timestamp: the starting timestamp (lower limit) for the range of Chargebacks you want to retrieve.

endTimestamp: the ending timestamp (upper limit) for the range of Chargebacks you want to retrieve. A null end time stamp defaults to now (the current time).

page: the page number, starting at 0, for which to return results. For example, if the total number of results is 85 and pageSize is 10:

  • Specifying 0 for page returns results from page 1 through 10.
  • Specifying 2 for page returns results from page 21 through 30.

pageSize: the number of records to display per page per call. This value must be greater than 0.
 

Output

return: an object of type Return that indicates  success or failure of the call.

chargebacks: an array of Chargeback objects that were updated during the time period specified in timestamp and endTimestamp.

Returns

This method returns the codes listed in Select Return Codes.

Example  

 

$select = new select();
$page = 0;
$pageSize = 50;

// Assume we have a function available to us that gives us
// the timestamp for the last time we ran this call:
$since = getLastCallTime();

do {

$ret = $select->fetchChargebacks($since, null, $page, $pageSize);
$count = 0;
if($ret['returnCode'] == 200)
{

$fetchedChargebacks = $ret['chargebacks'];
if($fetchedChargebacks != null)
{

$count = sizeof($fetchedChargebacks)
foreach ($fetchedChargebacks as $chargeback)
{
//Process a fetched chargeback here...
}
$page++;

}

}
else
{
//Handle error condition.
}

} while ($count == $pageSize);

 

Select.refundTransactions

Directs Vindicia Retain to discontinue further attempts to capture a transaction, or to refund a captured transaction. A call to refund.Transactions might be needed when a customer has canceled a subscription, or has paid a bill. This call results in Select either ceasing  attempts (retries) to capture a transaction, or refunding one that was captured. 

If a submitted transaction fails to validate it is returned in the response array, along with information indicating the validation issue.

After Select processes the refundTransactions call, the next call to fetchBillingResults, or to fetchByMerchantTransactionId, will return the status of the refundTransactions call.  

Input

refunds: an array of merchantTransactionIds to refund/cancel.

Output

return: an object of type Return indicating success or failure of the call.

response: an object of type TransactionValidationResponse, which includes the merchantTransactionID of each transaction that returned an error.

Note An empty TransactionValidationResponse object indicates that the call succeeded without error. For more information, see TransactionValidationResponse Values.

Returns

This method returns the codes listed in Select Return Codes.

Example

 

//Given existing (i.e. already billed)
//merchantTransactionIds TxPrfx123, TxPrfx234, and TxPrfx345:

$select = new select();
$ret = $select->refundTransactions(array{'TxPrfx123', 'TxPrfx234',
'TxPrfx345'});
if($ret['returnCode'] == 200)
{
$failedTransactions = $ret['response'];
if($failedTransactions && (sizeof($failedTransactions) > 0))
{
foreach ($failedTransactions as $transaction)
{
//Evaluate Transaction failure response here
}
}
}
else
{
//Handle error condition.
}

Select.reportTransactions

Use this method to report data to Vindicia Retain for use in fighting Chargebacks resulting from transactions not processed through Vindicia Retain.

Input

transactions: an array of Transaction objects to submit for billing.

Output

return: an object of type Return that indicates success or failure of the call.

response: an object of type TransactionValidationResponse, which includes the ID of a  emh transaction returning an error.

Note: An empty TransactionValidationResponse object indicates that the call succeeded without error. For more information, see TransactionValidationResponse Values.

Returns

This method returns the codes listed in Select Return Codes.

Example

 

$tx = new Transaction();
// Populate the Transaction object as illustrated above
// for credit card based billTransactions call.
$select = new select();
$ret = $select->reportTransactions(array{$tx});
if($ret['returnCode'] == 200)
{
$failedTransactions = $ret['response'];
if($failedTransactions && (sizeof($failedTransactions) > 0))
{

foreach ($failedTransactions as $transaction)
{
//Evaluate Transaction failure response here.
}
}
}
else
{
//handle error condition
}

For Users

Learn More
For Users

Vindicia Subscribe Features

Learn More
Vindicia Subscribe Features
Back to Top