> ## 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.score

The `score` method evaluates the chargeback probability score (also called risk score) for the `Transaction` object specified in the input, and stores the object in the Vindicia database.

Scoring a transaction before accepting it is a recommended best practice in the payment industry. It helps keep your costs low by:

* Avoiding payment processor fees for authorization calls to the processor for transactions your processor will not approve.
* Keeping your chargeback rate low. Processing and disputing chargebacks can be expensive. Payment processors typically require that you keep a very low chargeback rate.

The risk score is most applicable if the transaction’s payment method is credit card.

This call evaluates the risk score by examining several elements, including:

* The IP address of the origin of the transaction:
  * Whether the transaction originated from a proxy IP address known to Vindicia as an originator of fraudulent, malicious transactions.
  * How the geolocation of the IP address compares with the transaction’s billing address.
* The billing and shipping addresses:
  * Whether a transaction billing address or shipping address (or both) is known for being a fraudulent mail drop.
  * Whether the country of the address is a country known for the origin of fraudulent transactions.
* The BIN (the first six digits the credit-card number), which provides information on the bank that issued the credit card: whether the country of the billing address matches that of the issuing bank.
* The customer’s email address: whether it is from a free email provider, and if the email address has been associated with high–risk or fraudulent transactions.
* The credit-card account: whether the Vindicia database shows a previous chargeback against the transaction or the credit card used to pay for it. If so, `score()` returns the highest score of 100.

**Note:** The `score` method initiates the Subscribe risk-screening service. Be certain to subscribe to that service before calling `score`.

Call `score()` in these circumstances:

* If you subscribe to ChargeGuard only, that is, if you process your transactions outside of Vindicia and need to report them to Vindicia for chargeback dispute only, call this method to screen a transaction for fraud risk before processing it, and to simultaneously record it in the Vindicia database, saving you a separate reporting step.
* If you process one-time transactions through Subscribe, call this method to screen a transaction before processing it with your payment processor.

This call requires that your transaction contain at least the following information:

* Source IP address
* Billing address:
  * City
  * District (state or province). If states or provinces do not exist in the country in question, fill in the field with `None`.
  * Country

A risk score of `100` indicates that Vindicia is certain that the transaction is fraudulent and will result in a chargeback; a risk score of 0 means that the transaction is sound with a minimal likelihood of chargeback. You must decide the score level that you can tolerate. If you pick a high threshold, you might end up accepting many fraudulent transactions that will result in chargebacks. On the other hand, a low threshold might cause you to reject potentially good transactions and lose revenue. Selecting the right threshold for your risk score takes a bit of work. We recommend that you watch the scores on both the legitimate and fraudulent transactions before setting the threshold.

You can also indirectly screen transactions for risk by calling the `Transaction` object’s `auth()` method or the `AutoBill` object’s `update()` method. See the *minChargebackProbability* parameter supported by these methods.

In addition to returning the risk score, the `score()` method also returns descriptive strings that explain the score. Those strings have associated codes (IDs) called `ScoreCode` objects, listed in the following Score Card Descriptions table. Use these score codes to trigger certain actions in your application, such as in customer messaging, especially if you are rejecting a transaction because of a high risk score.

| Score Code (ID) | Description |
| - | - |
| `14` | The city and state in the shipping address do not match the ZIP code. |
| `15` | The city and state in the billing address do not match the ZIP code. |
| `16` | The shipping address is in the database of known risky mail drops. |
| `21` | The country of the issuing bank does not match the country of the billing address. |
| `31` | The password is in the database of high-risk passwords. |
| `32` | The user name is in the database of high-risk user names. |
| `41` | The email address is in the database of high-risk email addresses. |
| `42` | The email address is from a free email provider. |
| `51` | The IP address is in the database of known transparent proxy servers. |
| `52` | The IP address is an anonymous proxy. |
| `63` | The country of the IP address or billing address is a high-risk country. |
| `64` | The distance between the IP address and billing address is *XX* kilometers. |
| `65` | The IP address and billing address are in different countries. |
| `71` | The `Account` object is associated with known fraudulent (friendly or true-fraud) chargebacks. |

## 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 score.

## Output

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

*transaction*: a copy of the specified `Transaction` object, identified with a VID if not included in the input.

*score*: the `Transaction` object’s fraud 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. In particular, -1 applies to transactions with no originating IP addresses, incomplete addresses, or both. A score of -2 indicates an error; retry later.

If the score is not acceptable, you might want to contact the customer for more information, and then call this method again for another score.

*scoreCodes*: an array of `ScoreCode` objects that explain the score. Each object contains two attributes: `id` and `description`. See the Score Card Descriptions table for details.

## Returns

In addition to those listed in [The Return Object](The_Return_Object), this call returns:

| Return Code | Return String |
| - | - |
| `400` | One of the following: - `Unable to save transactions: *error-description*.` - `Data validation error: *error-description*.` |

## Example

```

$tx = new Transaction();
$tx->setAmount('29.90');
$tx->setCurrency('USD');
$tx->setMerchantTransactionId('txid-123456');
 
// IP is one of required attributes for scoring a transaction
$tx->setSourceIp('35.45.123.158');
 
$account = new Account();
$account->setMerchantAccountId('9876-5432');
$account->setEmailAddress('jdoe@mail.com');
$account->setName('J Doe');
$tx->setAccount($account);
 
$shippingAddress = new Address();
$shippingAddress->setName('Jane Doe');
$shippingAddress->setAddr1('44 Elm St.');
$shippingAddress->setCity('San Mateo');
$shippingAddress->setDistrict('CA');
$shippingAddress->setPostalCode('94403');
$shippingAddress->setCountry('US');
 
$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();
$ccCard = new CreditCard();
$ccCard->setAccount('4111111111111111');
$ccCard->setExpirationDate('201109');
$paymentMethod->setType('CreditCard');
$paymentMethod->setCreditCard($ccCard);
 
// Billing address city, district, country are required for score 
// call to work
$paymentMethod->setBillingAddress($shippingAddress);
 
$tx->setSourcePaymentMethod($paymentMethod); 
 
$response = $tx->score();
 
if ($response['returnCode'] == 200) {
   if($response['score']->score <= 50) {
      print "Acceptable score, processing transaction";
      // process the transaction further here
   }
   else {
      print "High risk of chargeback. Reasons are: \n";
      $scoreCodes = $response['scoreCodes'];
      foreach ($scoreCodes as $scoreCode) {
         print("Score code ". $scoreCode['id'] . " : " . 
         $scoreCode['description'] . "\n");
      }
   }
}
else {
   // the score call did not succeed, check return code 
   // and return string and try to re-submit
}
```

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


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