# JPMC-PDP Documentation from https://developer.payments.jpmorgan.com

# Obtain a fraud score

A fraud score helps you determine whether an accountholder is a fraud risk. Safetech fraud scoring offered by J.P. Morgan is based on various scoring criteria. Learn how to generate a fraud score with this guide.

## Before you begin

Before you send a fraud analysis only request, be aware of the following:

- The transaction is not sent to the issuer. Your request is passed to the Safetech fraud scoring system for evaluation.

- Based on the fraud score, you determine if you want to proceed with a new payment request (this is your responsibility).

> The fraud check request is supported for [cards](/docs/commerce/online-payments/capabilities/online-payments/payment-methods/cards/index) and [ACH](/docs/commerce/online-payments/capabilities/online-payments/payment-methods/ach) payment methods.
> 

## Generate a fraud score

Send a fraud check request to generate a fraud score. When evaluation of a fraud analysis-only transaction request completes, the Online Payments API synchronously returns the response data, which includes the `riskDecision` and `riskElement` objects.

Use the response information to enhance your current fraud programs, or to customize your approach to risk management.

 
**Fraud score request parameters**

| Field | Description | 
| --- | --- | 
| cardholderBrowserInformation | Consumer's HTTP browser type | 
| isFraudRuleReturn | Indicates if the triggered fraud checking rules are returned. Valid values include the following: - True — Indicates that rules should be returned - False — Indicates that rules should not be returned - — Indicates that rules are not returned | 
| aNITelephoneNumber | Phone number provided by a customer during a transaction with a merchant. Notes: - This field should be sent when the transaction is conducted over the phone - If a customer automatic number identification (ANI) is unsupported by the call center, enter 0123456789 into this field. | 
| fraudCheckShoppingCart | This field can be populated with user-defined values, shopping cart data, or both. Supports up to 999 characters. There can be multiple strings sent in a single record. Notes: - Each item must be separated by a “pipe” (|) character - The “pipe” (|) character cannot be used as part of the data. - To embed ampersands (&), equal signs (=), and/or “pipe” (|) characters within the data itself, the data provided must be Uniform Resource Identifier (URI) encoded. For example: - An ampersand (&) is %26 - A “pipe” (|) character is %7C - An equal sign (=) is %3D - If user-defined data must be previously-defined (e.g., UPROMOCODE=40&|): - U — Constant - PROMOCODE — The previously-defined label - 40 — Rule value - If related to a date, the format is YYYY-MM-DD - If related to time, the format is HH:MM:SS, where HH is in 24-hour format. - & — Constant - For shopping cart data, the following criteria applies: - May be URI-encoded - A “pipe” (|) character indicates the end of a string - Must contain five sub-elements, such as in the following example: T=TV&I=SKU123&D=42 Plasma&Q=1&P=70000&| - T — Type: In the example above, the type is a television. - I — Item: In the example above, the item is the stock keeping unit (SKU) - D — Description: In the example above, the description is a plasma television - Q — Quantity: This value must be numeric. - P — Price: This value must be numeric (two-decimal value implied) | 
| sessionId | Merchant-generated fraud session ID Notes: - Should be unique for a period of 30 days - Only able to support upper- and lower-cased alphabetical (A-Z, a-z) or numeric (0-9) values - Supports a maximum of 32 characters | 
| fencibleItemAmount | Total fencible values of goods sold (two-decimal value implied). | 
| websiteRootDomainName | Short name for the merchant’s website | 
| shippingDescription | Method of shipment selected for an item. Valid values include the following: - C — Lowest cost - D — Carrier designated by customer - E — Electronic delivery* - G — Ground* - I — International - M — Military - N — Next day/overnight* - O — Other/standard - P — Store pickup* - S — Same day* - T — Two-day service* Note: Values marked with an asterisk (*) pertain to American Express. | 

 
**Fraud score response parameters**

| Field | Description | 
| --- | --- | 
| fraudRiskScore | Fraud scoring is based on various scoring criteria, and is a numerical representation of the relative risk of each transaction screened. | 
| fraudRuleAction | The decision response code for a given rule based on the rules configuration. Valid values include the following: - A — Approve - D — Decline - E — Manager review - R — Review - — No decision response code is returned | 
| digitalAlertRuleName | Provides a comma-delimited list of the rules triggered Notes: - The first four positions in the list are the number of rules returned, followed by an equal (=) sign - If more rules are triggered than can fit in the record, the last character in this field is a plus (+) sign - If no rules are triggered, 0000= is returned | 
| fraudStatus | A unique code that indicates the fraud status of a transaction (for example, Y001) | 
| fraudStatusDescription | Description of the fraud status | 
| fraudRiskResponse | A fraud status is returned for every fraud inquiry once the transaction is approved or declined. The first character type of fraudStatus is one of the following: - X — Pre-authorization check - Y — Post-authorization check | 
| fraudEvaluatorTransactionId | Unique ID used to identify fraud assessment | 
| highestRiskCountry | Related country with highest probability of fraud. Note: This is the two-character country code, as defined in the International Organization for Standardization (ISO) 3166. | 
| highestRiskRegion | Estimated region of a customer. Examples: - ca — California - CA — Canada Note: If the region is returned as lowercase, it is a state or province. If the region is returned as uppercase, it is a country. | 
| cardType | Payment method brand identified during Safetech fraud scoring. Valid values include the following: - AMEX — American Express - AUBC — Australian Bankcard - CHEK — Check - CHIN — China Pay - DISC — Discover - DNRS — Diner’s Club - JCB — Japan Credit Bureau (JCB) International - MSRO — Maestro - MSTR — Mastercard - VISA — Visa - VISE — Visa Electron - UNKN — Other - — May be returned | 
| fourteenDaysTransactionCount | Total number of prior sales by this customer in the last 14 days | 
| sixHoursTransactionCount | Total number of prior sales by this customer in any six hour window over the last 14 days | 
| fourteenDaysCardRecordCount | Number of cards associated with transaction that the fraud system has recorded | 
| fourteenDaysDeviceRecordCount | Number of devices associated with the transaction that the fraud system has recorded | 
| fourteenDaysEmailRecordCount | Number of emails associated with the transaction that the fraud system has recorded | 
| deviceLayers | The device layers are as follows: - Operating system — The network, operating system, and secure sockets layer (SSL) return definite information - Flash settings — Queries the device to determine if it is Flash-capable. If so, device data is gathered via Flash. - JavaScript settings — Queries the device to determine if it is JavaScript capable. If so, device data is gathered via JavaScript. - Cookie settings — Queries HTTP headers for a number of device-associated data. - Browser — Queries the high-level browser to collect information about the browser, such as the user-agent string and browser type. Note: Each layer is delimited by periods (e.g., 329B0D35C3.41111A0B4A) | 
| sessionMatchIndicator | Indicates a corresponding Kaptcha record. Valid values include the following: - Y — Yes - N — No - — May be returned | 
| hashedDigitalDeviceFingerprintIdentifier | Unique fingerprint of the device used to place an order | 
| deviceTimestamp | Local date/time setting of the device in YYYY-MM-DD+HH:MM format | 
| deviceLocalTimeZone | Time zone of the device. The value listed represents the number of minutes from Greenwich Meantime. Divide by 60 to get number of hours | 
| deviceRegion | The region or state where the customer’s device resides. Examples: - ca — California - CA — Canada Note: If the region is returned as lowercase, it is a state or province. If the region is returned as uppercase, it is a country. | 
| deviceCountry | Country where the consumer’s device resides. Note: This is the two-character country code, as defined in the ISO 3166 standard. | 
| digitalDeviceType | Device placing the order of a mobile nature (e.g., iPhone™, Android™, Blackberry™, iPad™, etc.) | 
| deviceNetworkType | Network type associated with customer. Valid values include the following: - A — Anonymous - H — High School - L — Library - N — Normal - O — Open Proxy - P — Prison | 
| deviceProxyServer | Indicates whether the device is using a proxy. Valid values include the following: - Y — Yes - N — No - — May be returned | 
| browserJavaScriptEnabled | Indicates whether the device’s browser allows JavaScript. Valid values include the following: - Y — Yes - N — No - — May be returned | 
| browserAdobeFlashEnabled | Indicates whether the device’s browser allows Flash. Valid values include the following: - Y — Yes - N — No - — May be returned | 
| browserCookiesEnabled | Indicates whether the device’s browser allows cookies. Valid values include the following: - Y — Yes - N — No - — May be returned | 
| deviceBrowserCountry | Country where the browser resides Note: This is a two-character country code, as defined in the ISO 3166 standard. | 
| deviceBrowserLanguage | Indicates the language of the browser Note: This is a two character language code, as defined in the ISO 639-1 standard. | 
| mobileDevice | Indicates whether the device is a mobile device. Valid values include the following: - Y — Yes - N — No - — May be returned | 
| deviceWirelessCapability | Indicates whether the device has wireless capabilities. Valid values include the following: - Y — Yes - N — No - — May be returned | 
| deviceVoiceControlled | Indicates whether the device is voice controlled. Valid values include the following: - Y — Yes - N — No - — May be returned | 
| deviceRemotelyControlCapability | Indicates whether the device is a remotely controlled computer. Valid values include the following: - Y — Yes - N — No - — May be returned | 

The following example shows the required fields of a fraud check request:

**HTTP method**: `POST`
 **Endpoint**: `/fraudcheck ` 

```json
{
    "amount": 100,
    "currency": "USD",
    "fraudScore": {
        "cardholderBrowserInformation": "MOZILLA/4.0",
        "isFraudRuleReturn": true,
        "aNITelephoneNumber": "5131234567",
        "fraudCheckShoppingCart": "T=Tickets&I=FridayNightBaseballGame&D=SeatsBehindHomePlate&Q=2&P=20000&|",
        "sessionId": "d38e582e27e147483811b79281fnakdlsq",
        "websiteRootDomainName": "MERCHANT",
        "fencibleItemAmount": 1230
    },
    "accountHolder": {
        "deviceIPAddress": "127.0.0.1",
        "birthDate": "2000-09-20",
        "driverLicenseNumber": "G123-123-12-123-1",
        "addressCountryCode": "US",
        "email": "example@example.com",
        "firstName": "John",
        "lastName": "Doe",
        "referenceId": "12122012",
        "consumerIdCreationDate": "2021-09-01",
        "phone": {
            "countryCode": 1,
            "phoneNumber": "1235551234"
        },
        "billingAddress": {
            "line1": "1 NORTHEASTERN",
            "line2": "BLVD",
            "city": "BEDFORD",
            "state": "NH",
            "postalCode": "03109",
            "countryCode": "US"
        }
    },
    "paymentMethodType": {
        "card": {
            "expiry": {
                "month": 5,
                "year": 2040
            },
            "accountNumber": "5204740000001002"
        }
    },
    "shipTo": {
        "shippingAddress": {
            "line1": "123 Some Street",
            "line2": "Apartment 3b",
            "city": "Clearwater",
            "state": "FL",
            "postalCode": "33607",
            "countryCode": "USA"
        },
        "fullName": "John Doe",
        "shippingDescription": "Overnight",
        "phone": {
            "countryCode": 1,
            "phoneNumber": "1235557890"
        }
    },
    "merchant": {
        "merchantSoftware": {
            "companyName": "Payment Company",
            "productName": "Application Name",
            "version": "1.0"
        },
        "merchantCategoryCode": "4899"
    }
}
```

Response:

Regardless of the `fraudRiskScore` value, you are solely responsible for evaluating the risk before proceeding with a transaction.

```json
{
    "transactionId": "91659309-b78a-4075-a18b-84f7e7a54b21",
    "requestId": "543ba35f-70d8-4370-97dd-9e602cf41b38",
    "riskDecision": {
        "fraudRiskScore": "34",
        "fraudRuleAction": "A",
        "digitalAlertRuleName": "0000=",
        "fraudStatus": "A000",
        "fraudStatusDescription": "Fraud score successful",
        "fraudRiskResponse": "A"
    },
    "riskElement": {
        "fraudEvaluatorTransactionId": "K9SD0RKS4VYV",
        "highestRiskCountry": "US",
        "highestRiskRegion": "mn",
        "cardType": "AX",
        "fourteenDaysTransactionCount": 0,
        "sixHoursTransactionCount": 0,
        "fourteenDaysCardRecordCount": 1,
        "fourteenDaysDeviceRecordCount": 1,
        "fourteenDaysEmailRecordCount": 1,
        "deviceLayers": "BE5170F6F4..23EA1C3E4B.7D240F5823.2FB5A18D3",
        "sessionMatchIndicator": false,
        "hashedDigitalDeviceFingerprintIdentifier": "OE445516POI154F34E1A3151BCE70C19",
        "deviceTimestamp": "2022-08-18+11:25",
        "deviceLocalTimeZone": "300",
        "deviceRegion": "mn",
        "deviceCountry": "US",
        "digitalDeviceType": "Android",
        "deviceNetworkType": "N",
        "deviceProxyServer": "N",
        "browserJavaScriptEnabled": "N",
        "browserAdobeFlashEnabled": "N",
        "browserCookiesEnabled": "N",
        "deviceBrowserCountry": "US",
        "deviceBrowserLanguage": "EN",
        "mobileDevice": "N",
        "deviceWirelessCapability": "N",
        "deviceVoiceControlled": "N",
        "deviceRemotelyControlCapability": "N"
    },
    "hostReferenceId": "5hOQTa9S8l8GqINboAbLa4",
    "responseStatus": "SUCCESS",
    "responseCode": "ACCEPTED",
    "responseMessage": "Transaction Accepted",
    "hostMessage": "Successful Action Requested"
}
```

## Retrieve fraud check details

After making a fraud check request, you can retrieve the verification details. Complete the following steps to retrieve fraud check verification details.

1. Send a GET request to the /fraudcheck endpoint one of two ways:
  1. Use the requestId returned in the original response as a query parameter in a new GET request.
  2. Use the transactionId returned in the original response as a path parameter in a new GET request.

## Fraud check status codes

The Safetech service returns a response code for any approved or declined request. This is returned in the `fraudStatus` element of the response message.

The first character of the `fraudStatus` element can be used to identify the type of response returned from the Safetech service. The following table lists the possible fraud status codes:

 
**Fraud status codes**

| Fraud status code | Description | 
| --- | --- | 
| A000 | Fraud score is successful | 
| K201 | Version number is missing. Internal to Merchant Services. | 
| K202 | Mode is missing | 
| K203 | Merchant ID is missing | 
| K204 | Session ID is missing | 
| K205 | Risk inquiry service (RIS) transaction ID is missing | 
| K211 | Currency code is missing | 
| K212 | Total authorization amount is missing | 
| K221 | Email address is missing | 
| K222 | Phone number is missing | 
| K223 | Website ID is missing | 
| K231 | Payment type is missing | 
| K232 | Payment type of card is missing | 
| K233 | Payment type of magnetic ink character recognition (MICR) is missing | 
| K235 | Payment token (amount) is missing | 
| K241 | Customer internet protocol (IP) address is missing | 
| K251 | Merchant acknowledgement flag is missing | 
| K261 | POST is missing | 
| K271 | Product type code is missing | 
| K272 | Product item code is missing | 
| K273 | Product description is missing | 
| K274 | Product quantity is missing | 
| K275 | Product price is missing | 
| K301 | Version number is invalid | 
| K302 | Mode is invalid | 
| K303 | Merchant ID is invalid | 
| K304 | Session ID is invalid | 
| K305 | RIS transaction ID is invalid | 
| K311 | Currency code is invalid | 
| K312 | Total authorization amount is invalid | 
| K321 | Consumer’s email address is invalid | 
| K322 | Consumer’s phone number is invalid | 
| K323 | Website ID is invalid | 
| K324 | RIS response format is invalid | 
| K331 | Transaction type is invalid | 
| K332 | Card used as payment is invalid | 
| K333 | Payment type of MICR is invalid | 
| K335 | Google checkout account ID is invalid | 
| K341 | Consumer IP address is invalid | 
| K351 | Merchant acknowledgement flag is invalid | 
| K362 | Shopping cart data is invalid | 
| K371 | Product type code is invalid | 
| K372 | Product item code is invalid | 
| K373 | Product description is invalid | 
| K374 | Product quantity is invalid | 
| K375 | Product price is invalid | 
| K399 | Label either does not exist in the agent web console (AWC), or was associated with the wrong data type | 
| K401 | Extra data was included in the transaction | 
| K402 | Payment types were mismatched | 
| K403 | Customer phone number was sent, but was unnecessary | 
| K404 | Payment token was sent, but was unnecessary | 
| K501 | Scoring request was sent, but was not authorized | 
| K502 | Merchant ID was sent, but was not authorized | 
| K503 | IP address was sent, but was not authorized | 
| K504 | A time-out of fraud detection service occurred | 
| K601 | System error has occurred | 
| K602 | Submission of data that appears to be a security breach. This may come from a bad IP, email address, etc. | 
| K701 | Header is missing from transaction | 
| T998 | Internal server error where the fraud system is unreachable | 
| T999 | Fraud system is unreachable | 
| X001 | Merchant is not enabled for Safetech fraud scoring | 
| X002 | Method of payment is unsupported for Safetech scoring | 
| X003 | Action code is unsupported for Safetech fraud scoring | 
| X004 | Transaction type is unsupported for Safetech fraud scoring | 
| X005 | Safetech merchant ID is not sent on transaction | 
| X006 | Safetech merchant ID supplied does not match the division setup on file | 
| X008 | Invalid shopping cart data. RIS inquiry was not attempted. | 
| X009 | Invalid user-defined field data. RIS inquiry was not attempted | 
| Y001 | Authorization timed out. RIS inquiry not attempted. | 

## Related

[Online payments response codes](/api/commerce/online-payments/online-payments/error-codes)