Skip to main content
Vindicia Knowledge Center

Transaction.auth

Transaction.auth

Transaction.auth

The auth method sends a transaction to a payment processor for authorization before a capture operation. Call this method for one-time transactions when you want to bill a customer for a specific purchase. Used with the capture() call, this call is useful if the purchase involves shipping of physical goods. For such purchases and in some other situations, payment processors typically mandate that you not receive payment until you have shipped the goods to the customer. Before shipping or beginning the delivery, call auth() to determine the customer’s ability to pay and, after shipment, call capture() to receive payment.

You may also call auth() to simply validate a payment method, because the call does not charge the customer. However, because auth() requires CashBox to call your payment processor on your behalf, a cost is involved. For each transaction authorized, the payment processor typically charges a fee as stipulated in your contract. To avoid this fee, Vindicia recommends that you prescreen transactions for fraud risk before authorizing them with your payment processor. You can do so by specifying an acceptable risk score (less than 100) in the minChargebackProbability parameter of this call. For details on fraud risk screening, see ChargeGuard in the CashBox Programming Guide and the Transaction.score method.

Note The chargeback risk score is evaluated first, and, if it fails, is returned first.

This call only authorizes the transaction with your payment processor. The processor’s approval, indicated by the Authorized status set in the Transaction object returned by this call, means that the payment processor will initiate a fund transfer when you make a call to capture the transaction.

The Authorized status does not mean that the customer will be charged for this transaction. If a transaction involves the shipment of goods, call auth() after receiving the order. The Authorized status indicates that the customer will be able to pay. After shipping the order, call capture() (typically in batch mode, to process multiple transactions authorized over a period of time) to charge the customers in question.

Calling auth() also enables you to further validate a transaction before its capture. For example, for credit-card-based one-time transactions, auth() returns a Transaction object that contains a TransactionStatus object, which not only indicates whether the payment processor has approved the transaction, but also includes the processor’s responses to AVS (address verification) and CVN (credit-card security code) verifications, assuming that you have enabled those services with the processor. If the responses are not satisfactory to you, you can make a call to cancel the transaction and thus never capture it.

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

The meaning of a transaction’s authorization varies from payment method to payment method. For example:

  • If you are conducting an ECP-based inbound transaction, the authorization returned by your payment processor in response to the auth() call means that the processor has only verified that the bank account and routing number specified by the customer on the payment method are not in the negative file (“blacklist”) maintained by the processor. auth() does not guarantee that the customer has enough funds in their bank account to pay for the transaction.
  • CashBox does not support the auth() call for one-time transactions whose payment method is Boleto Bancário.
  • For PayPal-based transactions, the auth() call returns a PayPal URL in the TransactionStatus object, which you must present to your customer. The transaction is considered authorized only after the customers has visited the URL, and successfully completed the payment process required by PayPal.

The authorization that you obtain from your payment processor through the auth() call is usually valid for only a few days. To charge the customer and collect the funds associated with an authorized transaction, you must call capture() on it. For some payment processors, CashBox explicitly voids authorized transactions that have not been captured within a certain period of time.

The auth call will return a qualified success if the otherwise successful transaction experienced a tax-based timeout, and return a 202 error. Given this error, you can proceed with the Transaction as is or re-attempt the billing with a new 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.

Note: Transaction.auth allows you to set your own minChargebackProbability threshold, whileTransaction.authCapture uses the built-in CashBox AVS/CVN policy evaluation. Use Transaction.auth, rather than Transaction.authCapture, only with compelling reason.

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 for preauthorization. Identify this object using 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.

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 auth call will fail.

If you do not specify this parameter, it defaults to a value of 100, meaning no risk screening, in which case the Transaction is always acceptable to you (unless it fails). In order for Vindicia to successfully evaluate a transaction’s risk score, the transaction must have certain minimum information, such as the IP address, billing city, state, and country. For details on Vindicia’s risk-screening features, see ChargeGuard in the CashBox Programming Guide. 

sendEmailNotification: a Boolean flag that, if set to true, triggers an email notification from CashBox to the Account object for this 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.)

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

Output

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

transaction: the original Transaction object, with several attributes added by CashBox during processing, including the Transaction’s latest status, which will list the success or failure of the auth.

score: the Transaction object’s risk score, which represents the estimated probability that this transaction will result in a chargeback. This number ranges from 0 (best) to 100 (worst). It can also be -1, meaning that Vindicia has no opinion. (-1 indicates a transaction with no originating IP addresses, an incomplete addresses, or both. -2 indicates an error; retry later.)

If the score is not acceptable, contact the customer for more information and then re-call this method for a new score.

scoreCodes: an array of ScoreCode objects that explain the score. Each object contains two attributes:id and description. See Score Code Descriptions.

Returns

If successful, the auth() call returns a returnCode value of 200 along with the transaction status in the first (and latest) entry in the statusLog array. A 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.

407

Failed AVS policy evaluation.

408

Failed CVN policy evaluation.

402

One of the following:

  • Can't call auth on Boleto associated transaction. Please call authCapture!
  • 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.

(Vindicia saves the unauthorized transaction as a cancelled transaction, and returns a SOAP transaction object in $rc.)

Example

// to authorize a credit card-based transaction
// with risk screening enabled

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

// Reference an existing account by its ID

$account = new Account();
$account->setMerchantAccountId('9876-5432');
$tx->setAccount($account);

// Different shipping address from Account?

$shippingAddress = new Address();
$shippingAddress->setName('Jane Doe');
$shippingAddress->setAddr1('44 Elm St.');
$shippingAddress->setAddr2('Apt 55');
$shippingAddress->setCity('San Mateo');
$shippingAddress->setDistrict('CA');
$shippingAddress->setPostalCode('94403');
$shippingAddress->setCountry('US');
$shippingAddress->setPhone('650-555-3444');
$shippingAddress->setFax('650-555-3445');

$tx->setShippingAddress($shippingAddress);

// The line items of the transaction

$tx_item = new TransactionItem();
$tx_item->setSku('sku-1234');
$tx_item->setName('Widget');
$tx_item->setPrice('3.30');
$tx_item->setQuantity('3');
$tx->setTransactionItems(array($tx_item));

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

// Populate rest of the payment method object here.
// Make sure payment method has full billing address
// in it or the risk screen will not work.

$tx->setSourcePaymentMethod($paymentMethod);

// make the auth call here. We can tolerate a risk score below
// 70 and do not want to send an email notification to
// the customer

$response = $tx->auth(70, false);

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

$ret_tx = $response['data']->transaction;

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

print "Transaction approved";

}

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

print "Transaction not approved \n";
print "Reason code is: ";
print $ret_tx->statusLog[0]->creditCardStatus->authCode;
print "\n";

}
else {

print "Error: Unexpected transaction status\n";

}

}

else if ($response['returnCode']==403) {

print "Transaction cannot be processed due to high fraud potential\n";

}

else {

print "Error while making call to Vindicia CashBox\n";

}

For Users

Learn More
For Users

Cashbox Features

Learn More
Cashbox Features
Back to Top