Transaction.capture

The capture method schedules a batch of previously authorized transactions for the capture operation with your payment processor. For capture to succeed, the authorization you previously obtained from the processor through the auth() call must still be valid. After a capture() call, actual capture occurs within the next 12 hours when the Vindicia server back-end processes run the regularly scheduled batch capture operation with your payment processor.

Typically, payment processors issue authorizations for only a short duration. If a previously authorized transaction has not been captured within a certain period of time, usually a few days, CashBox sets the transaction status to AuthExpired; the corresponding TransactionStatusType enumerated value is Cancelled. This method will attempt to reauthorize AuthExpired transactions before scheduling a capture.

The business meaning of a successful capture varies according to the transaction’s payment method, as follows:

• For credit card transactions, the payment processor charges the credit card specified in the sourcePaymentMethod data member of the Transaction object for the transaction amount.
• For ECP transactions, capture() executes the payment, that is, a fund transfer is initiated between the banks.
• For PayPal transactions, capturing a previously authorized transaction enables you to receive the customer’s payment.
• For Boleto Bancário transactions, you cannot call capture(). Instead, authorize and capture transactions in the single call authCapture(). (See the Transaction.authCapture method.)

Input

srd: sparse response description, a SOAP string (which must be a JSON object), in which you specify the elements you want returned.This parameter enables the calling system to constrain a method call to return only components you specify. This gives you greater control over returned content, and improves response time within the Vindicia platform by reducing the processing needed for the call.

Some fields are required, either practically or in the WSDL, and will be returned regardless of the srd. A null srd returns the complete response.

transactions: an array of Transaction objects to schedule for capture with the payment processor.

Output

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

qtySuccess: the number of transactions that can be successfully scheduled for capture.

qtyFail: the number of transactions that cannot be scheduled for capture.

results: an array of CaptureResult objects that contain information on the success or failure of the call on each transaction.

The following table lists the CaptureResult object data members.

Table 18-21: CaptureResult Object Data Members

Data Members	Data Type	Description
merchantTransactionId	string	Your unique identifier for this Transaction object. Although you normally assign this value, Vindicia might assign it for the transactions it generates for reauthorization.
originalMerchantTransactionId	string	Your unique identifier for the original Transaction object in the case of a reauthorization.
returnCode	integer	The reason for the success or failure: 200: capture() succeeded. 402: The Transaction object has expired and cannot be reauthorized by capture(). 404: capture() cannot load the Transaction object, likely because the VID or your transaction ID (merchantTransactionId) is invalid. 405: You did not specify an authorized transaction. 500: capture() encountered an internal failure.

Returns

In addition to those listed in Table 1: Standard Return Codes, this call returns:

Return Code	Return String
400	One of the following: Must specify transaction. Unable to save transactions: error-description.
406	There are two conditions under which a 406 response code can be returned on a Transaction.capture() and/or Transaction.authCapture() SOAP method call.  The first condition applies to both calls when the risk score calculated by MaxMind exceeds the minChargebackProbability parameter, which the merchant set in the method call. In this situation, CashBox returns the 406 response code with a returnString value: Chargeback risk score is higher than minChargebackProbability, transaction not authorized. The second condition applies only to the Transaction.capture() method call. It occurs when a merchant calls the method on a transaction that has already been authorized and is pending capture (that is, CashBox is waiting for the billroutd service to initialize a capture cycle to the payment processor that the transaction will be sent to). Repeated capture calls will not speed up the process.

Note A return code of 200 does not mean that all input transactions have been successfully captured. Be sure to verify the number of successfully captured transactions in the qtySuccess output parameter against the number of input transactions. If some transactions have failed to be captured, examine the return codes in the results output parameter for possible explanation.

Example

// to capture a batch of previously authorized transactions
// create an empty transaction object to the make the SOAP calls
// against

$soap_tx = new Transaction();

$tx1 = new Transaction();
$tx2 = new Transaction();

// ids of previously authorized transactions

$merchantTxnId1 = '9876-5432';
$merchantTxnId2 = '9876-5437';

$tx1->setMerchantTransactionId($merchantTxnId1);
$tx2->setMerchantTransactionId($merchantTxnId2);

$txnArray = array($tx1, $tx2);

$response = $soap_tx->capture($txnArray);

if($response['returnCode']==200) {

$captureResults = $response['results'];
foreach ($captureResults as $captureResult) {

if ($captureResult->returnCode == 200) {

print ("Transaction with id " .
$captureResult->merchantTransactionId .
" was successfully captured");

}

}

}