> ## Documentation Index
> Fetch the complete documentation index at: https://docs.slm.m1amdocs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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 can also call `auth()` to simply validate a payment method, because the call does not charge the customer. However, because `auth()` requires Subscribe 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 this by specifying an acceptable risk score (less than 100) in the `minChargebackProbability` parameter of this call. For details on fraud risk screening, see Common ChargeGuard Programming Tasks in the Subscribe Programming Guide and the [Transaction.score](Transaction_score#) method.

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

Note that 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.

**Note:** 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, 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 sufficient funds are available to pay for the transaction.
* Subscribe 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, Subscribe explicitly voids authorized transactions that have not been captured within a certain period of time.

The `auth()` call also adds applicable sales-tax line items to your `Transaction` before authorizing it and, if it is authorized, scheduling it for capture. For tax calculation, work with Vindicia Client Services to define and capture your tax nexus, that is, the state and local governments that can legally tax your sales. Also, be certain to indicate the appropriate tax classification on your `Transaction` items.

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 may choose to 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 Subscribe Programming Guide.

**Note:** `Transaction.auth` allows you to set your own `minChargebackProbability` threshold, while `Transaction.authCapture` uses the built-in Subscribe 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 Subscribe 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 Common ChargeGuard Programming Tasks in the Subscribe Programming Guide.

*sendEmailNotification*: a Boolean flag that, if set to `true`, triggers an email notification from Subscribe 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 Subscribe 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 Subscribe 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.)

*enable3ds*: Disable 3DS authentication flow for this transaction if false; if true or undefined, the 3DS authentication flow will be determined by the merchant option flag `use3ds`.

## 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 Subscribe 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 [Table 1](Transaction_score#table_yfv_3jh_nlb).

## 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, Subscribe 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 [The Return Object](The_Return_Object#), 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.` - `This Credit Card already exists—Policy Violation" (eradicate the newly created but failed one or ensure it is set INACTIVE).` You receive this error message when you have the Credit\_Card\_Constraints merchant option enabled on your site. This message means that someone is attempting to use a credit card that is already being used as the payment method on an existing account. This is not allowed. |
| `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
$chargebackProbability = 70;
$response = $tx->auth($chargebackProbability, 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";
}
```

**Parent topic:**[Transaction Methods](../topics/Transaction_Methods)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.