Skip to main content
Vindicia Knowledge Center

Transaction.authCapture

Transaction.authCapture

Transaction.authCapture

The authCapture method combines auth and capture functionality. It authorizes a transaction with your payment processor in real time, and schedules it for capture simultaneously. CashBox performs the capture with your payment processor in batch mode at periodic intervals. AVS and CVN policy settings, and minChargebackProbability scoring can cause this call to fail even if a successful authorization is received.

Note For more information on AVS and CVN Return Codes, please work with your Vindicia Client Services representative.

The authCapture call also adds applicable sales-tax line items to your Transaction before authorizing it and, if it is authorized, scheduling it for capture. Work with Vindicia Client Services to define which state and local governments can legally tax your sales. Be certain to indicate the appropriate tax classification on your transaction items.

The authCapture call will return a qualified success if the otherwise successful Transaction experienced a tax-based timeout, and return a 202 error. Given this error, the automatic capture is postponed by a configurable delay (defaults to one hour) during which you can proceed by taking no action, or you can forcibly cancel the transaction. If you ignore this error and subsequently capture the transaction as is, the related capture will proceed according to your configured handling for Tax Not Available scenarios.To learn about additional options for handling taxes when the tax vendor is off line, see Handling "Tax Service Not Available" Scenarios in the CashBox Programming Guide.

This call is used to process one-time (real-time) transactions through CashBox. Call auth() to preauthorize a customer order before shipment and, after shipment, call capture() to capture the transaction. If the order does not involve shipment of physical goods, you may call authCapture to both authorize and capture the transaction.

This call returns the Transaction object with a TransactionStatus object (first entry in the array in the statusLog attribute) populated with results of the real-time authorization obtained from your payment processor. If the authorization result is positive (Authorized status), CashBox schedules the transaction for capture. Otherwise, CashBox sets the status to Cancelled.

By default, authCapture examines the AVS and CVN return codes, issued by your payment processor in response to the auth call, to determine whether to process the call. To ignore the CashBox evaluation of the AVS/CVN return code, and process the Transaction regardless of their result, set the ignoreAvsPolicy and ignoreCvnPolicy flags to true.

If there is a policy failure, the capture will be aborted.

Note The customer’s Account must exist before any Hosted Page related call references that Account.

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.

transaction: the Transaction object to authorize and capture. Identify this object with either its VID or your transaction ID (merchantTransactionId).

Note PaymentMethods may not be duplicated for an Account. Passing in an existing credit card number and expiration date (in the sourcePaymentMethod for the Transaction) in an attempt to create a new PaymentMethod for an Account will return the pre-existing PaymentMethod instead.

sendEmailNotification: a Boolean flag that, if set to true, triggers an email notification from CashBox to the Account object for the Transaction object. Use the Transaction data member preferredNotificationLanguage to set the language for the notification. (For more information, see Setting the Preferred Language in the CashBox Programming Guide.)

ignoreAvsPolicy: a Boolean flag that, if set to true, will override the AVS policy and update the paymentMethod, regardless of the AVS return code. If set to false or null, the AVS return code will be used to determine whether to update the paymentMethod.

ignoreCvnPolicy: an optional Boolean flag that, if set to true, will override the CVN policy and update the paymentMethod, regardless of the CVN return code. If set to false or null, the CVN return code will be used to determine whether to update the paymentMethod.

campaignCode: the Coupon or Promotion Code used to obtain a discount on this Transaction(applied to all eligible Transaction items and applicable to each individual Transaction item).

dryrun: a Boolean flag that, if set to true, will return the updated Transaction, without recording the result in the CashBox database. Use this method to compute the cost of a Transaction without committing to the change.

If the Transaction did not exist before, it will not exist afterward; if it did exist before, it will not change. (It is not necessary to specify a payment method, as no payment method validations, authorizations or charges will be performed if dryrun is true.)

minChargebackProbability: a number between 0 and 100 by which you specify your fraud risk score tolerance level. A chargeback probability (also called the risk-screening score or risk score) of 100 indicates that CashBox is 100% certain that a transaction is fraudulent and will result in a chargeback. Specify your acceptable threshold for chargeback possibility with this parameter. If the score evaluates to be more than your tolerance level, the authCapture call will fail.

If you do not set minChargebackProbability, CashBox defaults to 100, indicating that all transactions are acceptable and no risk screening occurs. For more information on CashBox risk screening, see Section 15: Common ChargeGuard Programming Tasks in the CashBox Programming Guide

Output

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

transaction: the Transaction object that contains a TransactionStatus object, which encapsulates the results of real-time authorization (also called online authorization) obtained from the payment processor. If this transaction is approved by the processor, CashBox has already scheduled it for batch capture.

score: the risk score for the payment method used for the AutoBill if you enabled risk scoring by specifying the value of the input parameter minChargebackProbability to be less than 100.

Normally, this value is between 0 and 100, where 100 is the highest risk score, indicating maximum chargeback probability. A value of -1 indicates that CashBox could not evaluate the score because of missing data such as an IP address or a full billing address. A value of -2 indicates an error condition.

scoreCodes: an array of ScoreCode objects, each of which includes a code and corresponding message explaining why the risk score evaluated to a certain value.

Returns

If successful, the authCapture() call returns a returnCode value of 200 along with the transaction status in the first (and latest) entry in the statusLog array. That 200 code does not necessarily mean that your transaction has been approved by the payment processor. For example, if your processor denies the transaction, CashBox sets a status of Cancelled in the latest entry in the statusLog array in the returned Transaction object, but the return code still remains 200.

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

Return Code

Return String

202

Taxes temporarily unavailable.

400

One of the following:

  • Must specify line items in transaction to calculate sales tax for auth!
  • Data validation error error-description.
  • Must specify transaction to authorize!
  • Auth attempt failed to return a valid Transaction.
  • Vindicia fault fault-code encountered.
  • Internal-error-description.
  • Data validation error Failed to create Payment-Type-Specific Payment Record: Credit Card conversion failed: Credit Card failed Luhn check.

402

One of the following:

  • The transaction ID merchantTransactionId collides with reserved Vindicia namespace, which is: namespace.
  • Unable to create transaction ID consistent with reserved Vindicia namespace, which is: namespace.
  • No payment method found in transaction or account.
  • Transaction already previously authorized!

406

Chargeback risk score is higher than minChargebackProbability, transaction not authorized.

409

AVS and CVN policy evaluations failed.

410

AVS and CVN policy evaluations could not be performed.

Examples

The following examples are for credit card, Boleto Bancário, ECP, and PayPal.

Credit Card Payment Method

The following example creates, populates, authorizes, and captures a Transaction object with CreditCard as the payment method. The code checks if the Transaction status after an authCapture() call is Authorized. If so, the payment processor has authorized the transaction, and CashBox has marked it for capture with the processor. However, if the status is Cancelled, it means that the payment processor has denied the transaction.

$tx = new Transaction();
$tx->setAmount('9.90');
$tx->setCurrency('USD');
$tx->setMerchantTransactionId('txid-123456');

$paymentMethod = new PaymentMethod();
$paymentMethod->setBillingAddress($address);
$paymentMethod->setType('CreditCard');

$card = new CreditCard();
$card->setAccount('4444222211113333');
$card->setExpirationDate('xxxxxx'); // Use YYYYMM format for date
$paymentMethod->setCreditCard($card);

$nv = new NameValuePair();
$nv->setName("CVN");
$nv->setValue("123"); // this is the card security code provided by customer

// set the card security code inside the payment method

$paymentMethod->setNameValues(array($nv));

$tx->setSourcePaymentMethod($paymentMethod);

// set other transaction attributes here

// make the authCapture call

$sendEmailNotification = true;
$ignoreAvsPolicy = true;
$ignoreCvnPolicy = true;
$minChargebackProbability = 30; //30 percent max
$response = $tx->authCapture($sendEmailNotification, $ignoreAvsPolicy,

$ignoreCvnPolicy), $minChargebackProbability);

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

if ($tx->statusLog[0]->status == 'Authorized') {

print "Card approved.\n";

}

else ($tx->statusLog[0]->status == 'Cancelled') {

// The transaction did not go through

print "Declined. Reason code received from

payment processor: ";

print $tx->statusLog[0]->status->creditCardStatus->authCode . "\n";

}

}

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

print "Transaction not authorized, Chargeback score is " . $response['score'] . "%\n";

}

Boleto Bancário Payment Method

For the Boleto Bancário payment method, the transaction success status after an authCapture() call is Authorized. That means that CashBox has validated the fiscal number and the payment processor has accepted it. In response, the payment processor returns a URL in the TransactionStatus object. That URL contains further instructions for completing the transaction and is actually a payment document the customer must print and take to their bank. After the call is complete, CashBox changes the transaction status to AuthorizedPending to indicate that CashBox is awaiting customer action and further response from the payment processor.

Present the URL returned by this call to your customer. When the transaction is complete, the payment processor notifies CashBox, which then updates the status to Captured or Cancelled, depending on the success or failure of the transaction. This step might take several days, because it requires that the customer physically present the payment document to the bank.

The following example creates, populates, and sets a fiscal number for a Transaction object with Boleto Bancário as the payment method.

$txn = new Transaction();

// Populate the transaction as shown in the previous example.
// When associating a customer account with this transaction ensure
// that the account has language preference indicated. This will set
// the language to be used in the payment instructions
// displayed to the customer

$tx->setAccount($account);

$paymentMethod = new PaymentMethod();

// For Boleto payment make sure country is specified in the address

$paymentMethod->setBillingAddress($address);
$paymentMethod->setType('Boleto');
$blt = new Boleto();
$blt->setFiscalNumber('123456789');
$paymentMethod->setBoleto($blt);

// populate payment method billing address, country must be specified

$tx->setSourcePaymentMethod($paymentMethod);
$sendEmailNotification=false;
$minChargebackProbability = 30; // 30 percent max
$response = $tx->authCapture($sendEmailNotification, $minChargebackProbability);

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

$ret_tx = $response['data']->transaction;
if($ret_tx->statusLog[0]->status=='Authorized') {

print "Successful\n";
display(print $ret_tx->statusLog[0]->status->boletoStatus ->uri);

}

else if($ret_tx->statusLog[0]->status=='Cancelled') {

// The transaction was denied

}

}

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

print "Transaction not authorized, Chargeback score is " . $response['score'] . "%\n";

}

Note For the Boleto Bancário payment method, be certain to specify the country in the payment method billing address, and the language preference in the customer account. Those two attributes set the language used in customer communications.

ECP Payment Method

For the ECP payment method, the status of a Transaction immediately after an authCapture() call is Authorized, which means that the payment processor has performed a real-time validation of the payment information to ensure, for example, that the bank routing number is not blacklisted. To configure this validation for a more thorough check, contact Vindicia Client Services.

Next, CashBox submits the transaction to the payment processor for deposit or withdrawal from the specified bank, and changes Transaction status to AuthorizedPending, meaning that processing of the Transaction has begun.

Six banking days must elapse before CashBox sets the status to Captured. During that time, if CashBox receives notice from the payment processor that the transaction has failed, CashBox changes the Transaction status to Cancelled.

If the reason code indicates that the payment processor will attempt a retry (for example, due to insufficient funds), CashBox changes the Transaction status to RetryPending. The retry date depends on the retry schedule that the payment processor has previously defined with you according to your division ID. Be certain to provide Vindicia with your division ID’s retry schedule.

If CashBox does not receive any decline codes for six banking days after the retry, CashBox sets the Transaction status to Captured. The following code example creates and populates a Transaction object with ECP as the payment method.

$txn = new Transaction();

// populate the transaction as shown in the previous example

$paymentMethod = new PaymentMethod();
$paymentMethod->setBillingAddress($address);
$paymentMethod->setType('ECP');

$ecp = new ECP();

// specify account number where funds will be with withdrawn from

$ecp->setAccount('123456789');

// specify bank routing number

$ecp->setRoutingNumber('3409284043');
$ecp->setAccountType('ConsumerChecking');
$paymentMethod->setECP($ecp);

// If this is an inbound payment i.e. a withdrawal from specified
// bank account and deposit into merchant's account set source
// payment method in the transaction.
// For paying out i.e. a deposit into specified bank account
// and withdrawal from merchant's bank account, set destination
// PaymentMethod attribute of the transaction

$tx->setSourcePaymentMethod($paymentMethod);
$tx->setEcpTransactionType('Inbound');

$sendEmailNotification = false;
$minChargebackProbability = 30; // 30 percent max
$response = $tx->authCapture($sendEmailNotification, $minChargebackProbability);

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

$ret_tx = $response['data']->transaction;
if($ret_tx->statusLog[0]->status=='Authorized') {

print "Successful\n";

}

else if($ret_tx->statusLog[0]->status=='Cancelled') {

// The transaction did not go through

print "Declined.

Reason code received from payment processor: ";

print $ret_tx->statusLog[0]->status->ecpStatus->authCode

. "\n";

}

}

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

print "Transaction not authorized, Chargeback score is " . $response['score'] . "%\n";

}

 

PayPal Payment Method

For the PayPal payment method, the transaction status after an authCapture() call is AuthorizationPending. The payment flow for PayPal-based real-time transactions proceeds as follows:

  1. When a customer clicks the PayPal button on your site, create a Transaction object that specifies PayPal as the payment method and makes a Transaction>authCapture() call to CashBox.
  2. When that call returns, examine the status of the returned Transaction object. If the status is not a failure (Cancelled), it is AuthorizationPending, meaning that the transaction is in the CashBox and PayPal systems, and that it requires further action from the customer for completion.
  3. PayPal notifies CashBox of the successful creation of the transaction by issuing a PayPal token, which keeps the transaction valid for the next few hours.
  4. The returned Transaction object contains a PayPal-specific status along with a URL, which contains the token information. Redirect the customer to that URL to complete PayPal’s payment sequence.
  5. Depending on the customer’s success or failure in completing the payment process, PayPal redirects the customer to a success or failure URL on your site. (Provide CashBox with the success and failure URLs as attributes named returnUrl and cancelUrl, respectively, of the PayPal payment method for the Transaction.) From this page, make a call to CashBox to finalize the PayPal authorization so that CashBox can update the status of the Transaction. This call requires you to pass in the ID of the Transaction, which you can find in redirected URL. It is value associated with the name vindicia_vid in the redirect URL.

The following example illustrates the process.

$tx = new Transaction();

// populate the transaction as shown in earlier examples

$paymentMethod = new PaymentMethod();
$paymentMethod->setType('PayPal');

$payPal = new PayPal();

// This is the URL the customer will be redirected to after they
// arrive at the Vindicia landing page after completing the payment
// process at PayPal's site

$payPal->setReturnUrl('http://myshoppingcart.merchant.com');

// specify bank routing number

$payPal->setCancelUrl('http://tryagain.merchant.com');
$paymentMethod->setPayPal($payPal);
$tx->setSourcePaymentMethod($paymentMethod);
$sendEmailNotification = false;
$minChargebackProbability = 30; // 30 percent max
$response = $tx->authCapture($sendEmailNotification, $minChargebackProbability);

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

if($tx->statusLog[0]->status=='AuthorizationPending') {

$payPalUrl = $tx->statusLog[0]->payPalStatus->redirectUrl;

// send customer to a URL for completion of payment
// process at PayPal's site

}

}

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

print "Transaction not authorized, Chargeback score is " . $response['score'] . "%\n";

}

After successfully completing the payment process, the customer is redirected to the URL www.myshoppingcart.merchant.com, which is the return URL in the PayPal-based PaymentMethod object. From this page, finalize the Transaction so that CashBox will acquire its status.

$soap_caller = new Transaction();

// obtain id of the PayPal transaction from the redirect URL.
// It is the value associated with name 'vindicia_vid'

$payPalTxId = … ;

// if calling from the return URL reached when the PayPal
// transaction is successfully authorized, set the
// success input parameter to true, from the cancelUrl, set the
// success input parameter to false. Let's assume success here:

$success = true;
$response =

$soap_caller->finalizePayPalAuth($payPalTxId, $success);

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

printLog "Transaction authorized";

}

Upon completion, CashBox updates the Transaction status to Authorized, which changes to Captured after CashBox batch-processes this and other PayPal transactions.

For Users

Learn More
For Users

Cashbox Features

Learn More
Cashbox Features
Back to Top