Payment & Transaction Fraud Prevention API Documentation

IPQS IP Reputation API and Device Fingerprint Technology support additional parameters for the purposes of scoring transactions or users, detecting payment fraud, and providing real-time fraud prevention. This service is ideal for preventing chargeback fraud and performing advanced user scoring.

User, Payment, & Transaction Fraud Scoring

Additional user data for orders, payments, transactions, lead generation, and personal user information can be analyzed to enhance Fraud Scores. The fields listed below are entirely optional and provide additional data that can be used to detect fraudulent patterns and behavior. Any additional data beyond the IP address greatly improves detecting high risk activity.

Risk analysis on transaction data will be displayed in the "transaction_details" object. If only one address is available for the user or transaction, then please enter the address data into the "billing" or "shipping" variables, rather than entering the same address in both variables. Passing the email address also contributes to detecting fraudulent users, however only a light abusive check will be performed. Using a full lookup with IPQS Email Verification API Documentation is recommended as it will provide greater details and accuracy for email reputation. The transaction variables listed below are optional, any irrelevant variables can be ignored.

Customize Transaction Scoring

Adjust IPQS payment, user, and transaction scoring algorithms to better fit your audience. Premium IPQS clients can adjust your account's Transaction Rules for better performance and more tailored results.

JSON Transaction Example Request

Below you will find an example of using transaction scoring functionality with our Proxy/VPN Detection API. New to IPQS? View our base Proxy Detection API Documentation to get started.

API Lookup with Billing Email Address, Country, & Phone #
The email address & phone # will be checked for recent abuse. The phone number will be validated. Only emails addresses checked with our dedicated Email Verification API will be fully validated.

Key	Expected Values	Description
billing_first_name	String	The customer's billing first name.
billing_last_name	String	The customer's billing last name.
billing_company	String	The customer's billing company.
billing_country	String	The customer's billing country name or billing country ISO-Alpha2. (EG: United States or US)
billing_address_1	String	The customer's billing street address part 1.
billing_address_2	String	The customer's billing street address part 2.
billing_city	String	The customer's billing city.
billing_region	String	The customer's billing region or state.
billing_postcode	String / Number	The customer's billing postcode or zipcode.
billing_email	String	The customer's billing email address.
billing_phone	Number	The customer's billing 11 to 14 digit phone number. (If less than 10 digits provided, the country code will be guessed by our AI.)
shipping_first_name	String	The customer's shipping first name.
shipping_last_name	String	The customer's shipping last name.
shipping_company	String	The customer's shipping company.
shipping_country	String	The customer's shipping country name or shipping country ISO-Alpha2. (EG: United States or US)
shipping_address_1	String	The customer's shipping street address part 1.
shipping_address_2	String	The customer's shipping street address part 2.
shipping_city	String	The customer's shipping city.
shipping_region	String	The customer's shipping region or state.
shipping_postcode	String / Number	The customer's shipping postcode or zipcode.
shipping_email	String	The customer's shipping email address.
shipping_phone	Number	The customer's shipping 11 to 14 digit phone number. (If less than 10 digits provided, the country code will be guessed by our AI.)
username	String	The customer's username.
password_hash	SHA256 / string	For security reasons and following industry best practices, a SHA256 hash of the user's password for better user analysis.
credit_card_bin	Number	First six digits of the credit or debit card, referred to ask the Bank Identification Number.
credit_card_hash	SHA256 / string	For security reasons and following industry best practices, a SHA256 hash of the credit card number is accepted to check against blacklisted cards.
credit_card_expiration_month	Number	Two letter format of the credit card's expiration month. For example, May would be "05".
credit_card_expiration_year	Number	Two letter format of the credit card's expiration year. For example, 2022 would be "22".
avs_code	Number	One letter Address Verification Service (AVS) response code provided by the credit card processor or bank. A full list of acceptable response codes can be viewed here.
cvv_code	Number	One letter Card Verification Value (CVV2) response code provided by the credit card processor or bank. A full list of acceptable response codes can be viewed here.
order_amount	Number	Total balance of the entire order without currency symbols.
order_quantity	Number	Quantity of items for this order.
recurring	Boolean	Is this a recurring order that automatically rebills?
recurring_times	Number	If this is a recurring order, then how many times has this recurring order rebilled? For example, if this is the third time the user is being billed, please enter this value as "3". If this is the initial recurring order, please leave the value as blank or enter "1".

Transaction Scoring Response Field Definitions

The following variables are returned through the Proxy Detection API which provides risk analysis for users and transactions. You can also treat "billing" or "shipping" variables as a user's primary or secondary information group, even when billing is not involved, such as for lead generation or user scoring purposes.

Field

Description

Possible Values

transaction_details

These variables are populated when at least 1 transaction data parameter is present in the initial API request. The following transaction variables are "null" when the necessary transaction parameters are not passed with the initial API request. For instance, not passing the "billing_email" will return "valid_billing_email" as null.

Key	Expected Values	Description
valid_billing_address	Boolean	Physical address validation and reputation analysis.
valid_shipping_address	Boolean	Same as above.
valid_billing_email	Boolean	Light abusive check and reputation analysis for the email address. It is recommended to use our dedicated Email Validation API for deeper analysis.
valid_shipping_email	Boolean	Same as above.
leaked_billing_email	Boolean	Indicates if the email address has recently been exposed or compromised in a database breach.
leaked_shipping_email	Boolean	Same as above.
leaked_user_data	Boolean	Indicates if the user's data (including phone & address) have recently been exposed or compromised in a database breach.
risky_billing_phone	Boolean	Reputation analysis for abusive activity associated with the phone number.
risky_shipping_phone	Boolean	Same as above.
valid_billing_phone	Boolean	Valid & active phone number with the phone carrier (not disconnected).
valid_shipping_phone	Boolean	Same as above.
billing_phone_carrier	String	Phone number provider company such as "AT&T" or "Bell Canada".
shipping_phone_carrier	String	Same as above.
billing_phone_line_type	String	Phone number line type such as "Landline", "Wireless", "Toll Free", or "VOIP".
shipping_phone_line_type	String	Same as above.
billing_phone_country_code	Integer	Country dial code associated with the phone number.
shipping_phone_country_code	Integer	Same as above.
bin_country	String	Country associated with the credit card BIN.
risky_username	Boolean	Username frequently associated with fraudulent behavior.
is_prepaid_card	Boolean	Status of the credit card as prepaid.
fraudulent_behavior	Boolean	Indicates high risk behavior patterns and a high chance of fraud.

object

Example Code

// Your API Key.
$key = 'YOUR_API_KEY_HERE';

/*
* Retrieve the user's IP address. 
* You could also pull this from another source such as a database.
* 
* If you use cloudflare change REMOTE_ADDR to HTTP_CF_CONNECTING_IP
*/
$ip = isset($_SERVER['REMOTE_ADDR']) ? $_SERVER['REMOTE_ADDR'] : $_SERVER['HTTP_CLIENT_IP'];


// Retrieve additional (optional) data points which help us enhance fraud scores.
$user_agent = $_SERVER['HTTP_USER_AGENT']; 
$user_language = $_SERVER['HTTP_ACCEPT_LANGUAGE'];

// Set the strictness for this query. (0 (least strict) - 3 (most strict))
$strictness = 1;

// You may want to allow public access points like coffee shops, schools, corporations, etc...
$allow_public_access_points = 'true';

// Reduce scoring penalties for mixed quality IP addresses shared by good and bad users.
$lighter_penalties = 'false';

// Create parameters array.
$parameters = array(
	'user_agent' => $user_agent,
	'user_language' => $user_language,
	'strictness' => $strictness,
	'allow_public_access_points' => $allow_public_access_points,
	'lighter_penalties' => $lighter_penalties
);

/* User & Transaction Scoring
* Score additional information from a user, order, or transaction for risk analysis
* All transaction parameters are optional, please remove any that are not used
* Non paid actions such as lead generation and user scoring can be substituted into the "billing" or "shipping" variables
* This feature requires a Premium plan or greater
* Premium users can also adjust transaction scoring rules: https://www.ipqualityscore.com/user/transaction/weights
*/

//  All variables below are optional to supplement risk analysis and fraud scoring
	$transaction_parameters = array(
		'billing_first_name' => '',
		'billing_last_name' => '',
		'billing_company' => '',
		'billing_country' => '',
		'billing_address_1' => '',
		'billing_address_2' => '',
		'billing_city' => '',
		'billing_state' => '',
		'billing_zipcode' => '',
		'credit_card_hash' => '',
		'billing_phone' => '',
		'billing_email' => '',
		'shipping_first_name' => '',
		'shipping_last_name' => '',
		'shipping_company' => '',
		'shipping_country' => '',
		'shipping_address_1' => '',
		'shipping_address_2' => '',
		'shipping_city' => '',
		'shipping_state' => '',
		'shipping_zipcode' => '',
		'shipping_email' => '',
		'shipping_phone' => '',
		'username' => '',
		'password_hash' => '',
		'credit_card_bin' => '',
		'recurring' => '',
		'recurring_times' => '',
		'credit_card_expiration_month' => '',
		'credit_card_expiration_year' => '',
		'avs_code' => '',
		'cvv_code' => '',
		'order_amount' => '',
		'order_quantity' => ''
);

// Format Parameters
if(is_array($transaction_parameters)){
	$formatted_parameters = http_build_query(array_merge($parameters, $transaction_parameters));
} else {
	$formatted_parameters = http_build_query($parameters);
}

// Create API URL
$url = sprintf(
	'https://www.ipqualityscore.com/api/json/ip/%s/%s?%s', 
	$key,
	$ip, 
	$formatted_parameters
);

// Fetch The Result
$timeout = 5;

$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, $url);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($curl, CURLOPT_FOLLOWLOCATION, 1);
curl_setopt($curl, CURLOPT_CONNECTTIMEOUT, $timeout);

$json = curl_exec($curl);
curl_close($curl);

// Decode the result into an array.
$result = json_decode($json, true);

// Check to see if our query was successful.
if(isset($result['success']) && $result['success'] === true){
	// NOTICE: If you want to use one of the examples below, remove
	// any lines containing /*, */ and *-, then remove * from any of the
	// the remaining lines.
	
	/*
	*- Transaction Scoring Example 1: We'd like to block users with a risky phone number or invalid physical address
	* 
	* if($result['transaction_details']['valid_billing_address'] === false || $result['transaction_details']['valid_shipping_address'] === false || $result['transaction_details']['valid_billing_phone'] === false || $result['transaction_details']['valid_shipping_phone'] === false || $result['transaction_details']['risky_billing_phone'] === true || $result['transaction_details']['risky_shipping_phone'] === true){
	*		exit(header("Location: https://google.com"));
	* }
	*/
	
	/*
	*- Transaction Scoring Example 2: We'd like to block users with any occurrence of high risk behavior, invalid user data, or an overall Fraud Score >= 85
	* 
	* if($result['fraud_score'] >= 85 || $result['transaction_details']['valid_billing_address'] === false || $result['transaction_details']['valid_shipping_address'] === false || $result['transaction_details']['valid_billing_email'] === false || $result['transaction_details']['valid_shipping_email'] === false || $result['transaction_details']['risky_billing_phone'] === true || $result['transaction_details']['risky_shipping_phone'] === true || $result['transaction_details']['valid_billing_phone'] === false || $result['transaction_details']['valid_shipping_phone'] === false || $result['transaction_details']['risky_username'] === true || $result['transaction_details']['fraudulent_behavior'] === true){
	*		exit(header("Location: https://google.com"));
	* }
	*/
	
	/*
	*- Transaction Scoring Example 3: We'd like to block users with an overall Fraud Score >= 85, or users with tor connections, or users with abusive email addresses
	* 
	* if($result['fraud_score'] >= 85 || $result['tor'] === true || $result['transaction_details']['valid_billing_email'] === false || $result['transaction_details']['valid_shipping_email'] === false){
	*		exit(header("Location: https://google.com"));
	* }
	*/

	/*
	* If you are confused with these examples or simply have a use case
	* not covered here, please feel free to contact IPQualityScore's support
	* team. We'll craft a custom piece of code to meet your requirements.
	*/
}