Skip to main content
Vindicia Knowledge Center

Transaction.score

Transaction.score

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 which 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’s 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 CashBox 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 CashBox, 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 table below. 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 table above for Score Code Descriptions. 

Returns

In addition to those listed in Standard Return Codes, 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

}

For Users

Learn More
For Users

Cashbox Features

Learn More
Cashbox Features
Back to Top