Fraud API Response

The endpoint returns a JSON structured response carrying SEON's enriched data, the rules that fired and the resulting score. See Fraud API Request for the call that produces it.

Envelope
Response attributes
Example response
Error responses

Envelope

Every response is wrapped in the same three fields:

Attribute	Type	Description
`success`	boolean	`true` when the request was processed. On `false`, read `error` and ignore `data`.
`error`	object	Empty on success. On failure it carries the SEON error `code` and `message` — see Error responses.
`data`	object	The enrichment and scoring result, described below.

Response attributes

The attributes of the data object. Which ones appear depends on the modules you enabled in config and on config.response_fields.

idstring

A unique identifier. Equals the transaction_id sent in the request, or a generated value if none was sent.

statestring

Transaction state, indicating the action to take. Score thresholds are configurable on the Settings page.

One of APPROVE, REVIEW, DECLINE

fraud_scorenumber

Likelihood that the transaction is fraudulent. Anything above 10 is risky. See Scoring Engine & Rules.

min 0, max 100

blackbox_scorenumber

Likelihood that the transaction is fraudulent according to SEON's Blackbox machine learning models. Must be activated to appear in the response — see Blackbox machine learning.

min 0, max 100

ip_detailsobject

Details about the IP address. Contains the full IP API response; its applied_rules are merged into the Fraud API's applied_rules.

email_detailsobject

Details about the email address. Contains the full Email API response; its applied_rules are merged into the Fraud API's applied_rules.

phone_detailsobject

Details about the phone number. Contains the full Phone API response; its applied_rules are merged into the Fraud API's applied_rules.

aml_detailsobject

AML screening details for the user. Contains the full AML API response; its applied_rules are merged into the Fraud API's applied_rules.

bin_detailsobject

Details about the payment card.

11 child attributes

card_binstring

The first 6 digits of the card number.

bin_bankstring

Card's bank name.

bin_cardstring

Card's network.

bin_typestring

Card's type: CHARGE CARD, CREDIT or DEBIT.

bin_levelstring

Card's level, for example ATM CARD, BUSINESS, CORPORATE, PLATINUM.

bin_countrystring

Card's country.

bin_country_codestring

Card's two-character ISO 3166-1 country code.

bin_websitestring

The owner bank's website.

bin_phonestring

The owner bank's phone number.

bin_validboolean

Whether the card is valid.

card_issuerstring

Card's issuer name.

device_detailsobject

The decrypted device fingerprint — the full Device Intelligence SDK response, as collected by the JavaScript Agent, iOS SDK or Android SDK. A field can be null when the browser does not support or return that data point; otherwise types are preserved.

73 child attributes

typestring

Source of the fingerprint — web for the JavaScript Agent.

sourcestring

The SDK version that produced the payload. Example: js-6.5.1.

session_idstring

Unique identifier generated for the session when the fingerprint was created.

true_device_idstring

Unique and persistent device identifier.

device_hashstring

Unique identifier of the device at hardware level, based on SEON's algorithm.

browser_hashstring

Unique identifier of the browser, based on SEON's algorithm.

cookie_hashstring

Unique identifier of the user's current session.

spoofing_hashstring

Hash of the detected fingerprint spoofing attempts. Only populated when some form of spoofing is detected.

suspicious_flagsarray of string

Fraud indicators raised for this session. See Suspicious flags for the full list and the default rule scores.

osstring

Operating system of the user's device.

platformstring

Platform reported by the user's browser.

browserstring

Name of the user's browser.

browser_versionstring

Version of the user's browser.

browser_version_ageinteger

Age of the browser version, in years.

user_agentstring

The user agent string of the user's browser.

unpopular_user_agentboolean

true when the user agent is not among the widely used ones.

user_agent_dataobject

User Agent Data API values. Chromium-based browsers only.

7 child attributes

architecturestring

CPU architecture, for example arm.

bitnessstring

CPU bitness, for example 64.

mobileboolean

Whether the browser reports itself as mobile.

modelstring

Device model, where reported.

platformstring

Platform name, for example macOS.

platform_versionstring

Platform version.

ua_full_versionstring

Full browser version.

device_typestring

Type of device: desktop, phone, tablet, TV, and so on.

device_memoryinteger

Size of the device memory, in gigabytes.

hardware_concurrencyinteger

Number of logical processor cores.

price_rangestring

Estimated price range of the user's device.

One of low, medium, high

mobile_detailsobject

Factory device information for the mobile device used — model, resolution, battery size, average price.

privateboolean

Whether the user is browsing in private mode.

vpnboolean

Whether the user is using a VPN.

proxyboolean

Whether the user is using a proxy.

adblockboolean

Whether an ad blocker is installed in the user's browser.

extensionsarray of string

Installed extensions detected against SEON's extension list.

device_ipstring

IP address the session data came from.

device_ip_ispstring

ISP of the device IP.

device_ip_countrystring

Country of the device IP.

device_ip_regionstring

Region of the device IP. Currently US states only.

dns_ipstring

User's DNS IP address.

dns_ip_ispstring

ISP of the DNS IP.

dns_ip_countrystring

Country of the DNS IP.

dns_ip_regionstring

Region of the DNS IP. Currently US states only.

webrtc_activatedboolean

Whether WebRTC is turned on.

webrtc_ipsarray of string

WebRTC IPs found in the user's browser.

webrtc_countinteger

Number of WebRTC IPs found.

device_locationobject

Location data for the device. Returned only when config.device.include requests device_location or extended_device_location. The base form carries latitude, longitude, accuracy, is_simulated and status; the extended form adds the reverse-geocoded country_code, region, city and zip.

9 child attributes

latitudenumber

Latitude reported by the device.

longitudenumber

Longitude reported by the device.

accuracynumber

Accuracy of the reported position, in metres.

is_simulatedboolean

Whether the position appears to be simulated.

statusstring

Outcome of the geolocation collection, for example SUCCESS.

country_codestring

Reverse-geocoded country code. Extended device location only.

regionstring

Reverse-geocoded region. Extended device location only.

citystring

Reverse-geocoded city. Extended device location only.

zipstring

Reverse-geocoded postal code. Extended device location only.

timezonestring

Timezone of the user, for example Europe/Budapest.

timezone_offsetstring

The device's timezone setting as a UTC offset.

timezone_countrystring

ISO country code of the detected timezone.

localestring

The user's language, region and any special variant preferences.

languagesarray of string

The user's preferred languages.

keyboard_layout_namestring

Keyboard layout language of the user.

keyboard_layout_hashstring

Hash of the keyboard's key mapping.

canvas_hashstring

Identifier generated from the browser's canvas rendering.

audio_hashstring

Identifier built on the browser's audio capabilities. Helps separate regular browsers from fraud tools and privacy browsers.

math_hashstring

Hash of high-precision math function outputs. Browser engines implement these differently, so the value narrows down the engine.

mime_types_hashstring

Hash of the media types and formats the browser supports.

system_colors_hashstring

Hash of the built-in base fonts' colours and sizes.

webglobject

WebGL rendering data points.

9 child attributes

webgl_hashstring

A single hash of all WebGL-related information.

webgl_image_hashstring

Hash of an object drawn with WebGL.

webgl_parameters_hashstring

Hash of the WebGL API parameters.

webgl_parameters_noiseboolean

true when noise was detected while hashing the WebGL parameters.

webgl_2_image_hashstring

Hash of an object drawn with WebGL 2.

webgl_2_parameters_hashstring

Hash of the WebGL 2 parameters.

webgl_2_parameters_noiseboolean

true when noise was detected while hashing the WebGL 2 parameters.

webgl_rendererstring

Renderer string of the graphics driver.

webgl_vendorstring

Vendor string of the graphics driver.

font_hashstring

Unique identifier of the user's installed fonts.

font_listarray of string

Names of the fonts installed on the user's device.

font_countinteger

Number of accessible fonts in the user's browser.

font_noiseboolean

Whether font noising was detected — a technique for spoofing the installed font list to defeat fingerprinting.

pluginsobject

Installed browser plugins.

3 child attributes

plugin_countinteger

Number of accessible plugins in the user's browser.

plugin_hashstring

Unique identifier of the user's installed plugins.

plugin_listarray of string

Names of the plugins installed on the user's device.

screen_dataobject

Screen and window measurements — screen_width, screen_height, screen_available_width, screen_available_height, screen_color_depth, screen_pixel_depth, device_pixel_ratio, orientation_type, orientation_angle, is_extended, window_inner_*, window_outer_*, window_screen_*, window_scroll_*, document_width and document_height.

unpopular_device_resolutionboolean

true when the user's screen resolution is not among the widely used ones.

media_devicesobject

The device's media devices.

3 child attributes

audio_input_countinteger

Number of audio input devices, such as microphones.

audio_output_countinteger

Number of audio output devices, such as speakers and headphones.

video_input_countinteger

Number of video input devices, such as webcams.

batteryobject

Battery charge state and level.

2 child attributes

battery_chargingboolean

Whether the device is currently charging.

battery_levelinteger

Current battery level.

min 0, max 100

permissionsobject

The browser's permission states.

3 child attributes

grantedarray of string

Browser APIs for which the user granted permission.

promptarray of string

Browser APIs the user has neither granted nor denied — the user will be prompted on first use.

deniedarray of string

Browser APIs for which the user denied permission.

drm_key_systemsarray of string

Available Digital Rights Management providers.

touch_supportboolean

Whether the user's browser supports a touch screen.

max_touch_pointsinteger

Maximum number of simultaneous touch contact points the device supports.

mouse_movedboolean

Whether the mouse moved during fingerprinting — that is, between seon.init() and seon.getSession().

has_focusboolean

Whether the current page's content has focus.

cookie_enabledboolean

Whether cookies are enabled in the user's browser.

do_not_trackboolean

Whether the browser's Do Not Track feature is turned on.

java_enabledboolean

Whether Java applets are turned on. No modern major browser supports them.

flash_enabledboolean

Whether the browser supports Flash.

referrerstring

The URL of the page that linked to the current page.

window_locationstring

URL of the page where the fingerprint was generated, including path and query parameters.

geolocation_detailsobject

Distances between the locations SEON knows about. By default only the IP, POS and custom-coordinate distances are calculated; the user, billing and shipping address distances need to be enabled by SEON. Add geolocation_details to config.response_fields to receive it.

15 child attributes

user_billing_distancenumber

Distance between the user's address and the billing address, in kilometres.

user_shipping_distancenumber

Distance between the user's address and the shipping address, in kilometres.

billing_shipping_distancenumber

Distance between the billing and shipping addresses, in kilometres.

ip_user_distancenumber

Distance between the IP location and the user's address, in kilometres.

ip_billing_distancenumber

Distance between the IP location and the billing address, in kilometres.

ip_shipping_distancenumber

Distance between the IP location and the shipping address, in kilometres.

pos_ip_distancenumber

Distance between the POS location and the IP-derived geolocation, in kilometres.

pos_user_distancenumber

Distance between the POS location and the user's registered address, in kilometres.

pos_shipping_distancenumber

Distance between the POS location and the shipping address, in kilometres.

pos_billing_distancenumber

Distance between the POS location and the billing address, in kilometres.

pos_custom_distancenumber

Distance between the POS location and the custom coordinate, in kilometres.

custom_ip_distancenumber

Distance between the custom coordinate and the IP-derived geolocation, in kilometres.

custom_user_distancenumber

Distance between the custom coordinate and the user's registered address, in kilometres.

custom_shipping_distancenumber

Distance between the custom coordinate and the shipping address, in kilometres.

custom_billing_distancenumber

Distance between the custom coordinate and the billing address, in kilometres.

applied_rulesarray of object

The rules configured in the Scoring Engine that fired for this action.

4 child attributes

idstring

Unique identifier of the rule.

namestring

Name of the rule.

operationstring

The rule's operation.

One of null, +, -, APPROVE, REVIEW, DECLINE, BLACKLIST, WHITELIST, LIST

scorenumber

Score contributed by the rule.

rule_category_detailsarray of object

Per-category results. Not included by default: enable Category score or Category state under the category settings in the Admin Panel and add rule_category_details to config.response_fields. See the step-by-step guide.

5 child attributes

category_idinteger

Unique identifier of the rule category.

category_namestring

Name of the rule category.

category_statestring

State derived from the rules applied in this category. Present according to your category settings.

One of APPROVE, REVIEW, DECLINE

category_scorenumber

Score derived from the rules applied in this category. Present according to your category settings.

min 0, max 100

applied_rulesarray of string

IDs of the rules applied within the category.

string_analysesobject

Analytical functions applied to the email, user_name and user_fullname values from the request — the same figures shown in the Email Information and Identity widgets of the Transaction view. Add string_analyses to config.response_fields to receive it.

3 child attributes

emailobject

Character-composition metrics for one input string.

15 child attributes

lengthinteger

Total number of characters.

count_of_alphanumericinteger

Number of alphanumeric characters.

count_of_non_alpha_numericinteger

Number of non-alphanumeric characters.

count_of_vowelsinteger

Number of vowels.

count_of_consonantinteger

Number of consonants.

count_of_numbersinteger

Number of digits.

count_of_consecutive_numbersinteger

Number of runs of consecutive digits.

count_of_capitalsinteger

Number of capital letters.

count_of_plusinteger

Number of + characters.

count_of_dotsinteger

Number of . characters.

vowel_rationumber

Vowels divided by length.

consonant_rationumber

Consonants divided by length.

alpha_numeric_rationumber

Alphanumeric characters divided by length.

non_alpha_numeric_rationumber

Non-alphanumeric characters divided by length.

fullcaps_rationumber

Capital letters divided by length.

user_nameobject

Character-composition metrics for one input string.

15 child attributes

lengthinteger

Total number of characters.

count_of_alphanumericinteger

Number of alphanumeric characters.

count_of_non_alpha_numericinteger

Number of non-alphanumeric characters.

count_of_vowelsinteger

Number of vowels.

count_of_consonantinteger

Number of consonants.

count_of_numbersinteger

Number of digits.

count_of_consecutive_numbersinteger

Number of runs of consecutive digits.

count_of_capitalsinteger

Number of capital letters.

count_of_plusinteger

Number of + characters.

count_of_dotsinteger

Number of . characters.

vowel_rationumber

Vowels divided by length.

consonant_rationumber

Consonants divided by length.

alpha_numeric_rationumber

Alphanumeric characters divided by length.

non_alpha_numeric_rationumber

Non-alphanumeric characters divided by length.

fullcaps_rationumber

Capital letters divided by length.

user_fullnameobject

Character-composition metrics for one input string.

15 child attributes

lengthinteger

Total number of characters.

count_of_alphanumericinteger

Number of alphanumeric characters.

count_of_non_alpha_numericinteger

Number of non-alphanumeric characters.

count_of_vowelsinteger

Number of vowels.

count_of_consonantinteger

Number of consonants.

count_of_numbersinteger

Number of digits.

count_of_consecutive_numbersinteger

Number of runs of consecutive digits.

count_of_capitalsinteger

Number of capital letters.

count_of_plusinteger

Number of + characters.

count_of_dotsinteger

Number of . characters.

vowel_rationumber

Vowels divided by length.

consonant_rationumber

Consonants divided by length.

alpha_numeric_rationumber

Alphanumeric characters divided by length.

non_alpha_numeric_rationumber

Non-alphanumeric characters divided by length.

fullcaps_rationumber

Capital letters divided by length.

ekyc_resultstring

Status of the eKYC request. See the eKYC payload examples.

One of SUCCESS, PARTIAL_SUCCESS, REVIEW, NO_MATCH, FAILED, FAILED_PROCESSING

ekyc_dataobject

The full eKYC data response for the user. See the eKYC payload examples.

versionstring

Version of the SEON API that produced the response.

calculation_timeinteger

Time taken to calculate the score, in milliseconds.

seon_idinteger

Unique identifier generated by SEON.

Example response

{
  "success": true,
  "error": {},
  "data": {
    "id": "67c2810c2de1",
    "state": "DECLINE",
    "fraud_score": 95.75,
    "blackbox_score": 93.25,
    "bin_details": {
      "card_bin": "414141",
      "bin_bank": "VERMONT NATIONAL BANK",
      "bin_card": "VISA",
      "bin_type": "CREDIT",
      "bin_level": "CLASSIC",
      "bin_country": "UNITED STATES",
      "bin_country_code": "US",
      "bin_website": "www.vermontnationalbank.com",
      "bin_phone": "+1 802 476 0030",
      "bin_valid": true,
      "card_issuer": "VISA"
    },
    "version": "v2",
    "applied_rules": [
      {
        "id": "1000702",
        "name": "Phone possible is equal to true",
        "operation": "+",
        "score": 1.11
      },
      {
        "id": "P106",
        "name": "Customer is using a datacenter ISP",
        "operation": "+",
        "score": 10
      },
      {
        "id": "1000715",
        "name": "Temp ARC 2 category specific rule",
        "operation": null,
        "score": 0
      }
    ],
    "device_details": {
      "type": "web",
      "os": "macOS 10.15 Catalina",
      "browser": "CHROME",
      "device_type": "desktop",
      "device_hash": "c92d19d5c29dbd2834e2281d28b35fd5",
      "true_device_id": "0195943f-b231-7c7c-9586-b3b0cccb039a",
      "session_id": "14e671a5f503b0d0d8d978a67de0866b",
      "source": "js-6.5.1",
      "vpn": false,
      "proxy": false,
      "suspicious_flags": [
        "bots_and_automation"
      ]
    },
    "geolocation_details": {
      "ip_user_distance": 4.13,
      "pos_ip_distance": 2.87
    },
    "calculation_time": 2327,
    "seon_id": 12602,
    "aml_details": null
  }
}

Error responses

On failure success is false and the error object carries the SEON error code and message.

HTTP status	Error code	Description
`400`	`1000`	Empty request body. The request reached SEON but carried no payload. Check the request for formatting errors.
	`1001`	Incorrect config object: `[data_field_name]` should be sent as `[format]`. The named `config` field is formatted incorrectly.
	`1006`	Invalid input json. The body is not valid JSON.
	`1009`	Invalid email address. The `email` value is not an email address — for example the `@` sign or the TLD is missing.
	`1016`	Lookup limit for your plan has been reached. Contact Technical Services to raise the limit.
	`1018`	Invalid card_last format. `card_last` must contain only the last four digits of the card number.
	`2006`	Requested feature `[feature_name]` is not enabled — for example HLR or CNAM lookup. Contact Technical Services to enable it.
	`3000`	Incorrect type: `[data_field_name]` should be sent as `[format]`. The named field has the wrong JSON type.
	`3001`	Incorrect value: `[data_field_name]` is invalid. Check the field name and value against the request attributes above.
	`3002`	Incorrect value: `[data_field_name]` should be sent as one of `[value-1]`, `[value-2]`. The value is outside the accepted set.
	`3003`	Length error: `[data_field_name]` size must be between `[minimum_value]` and `[maximum_value]`. Also returned as Invalid `transaction_amount` input parameter when the amount contains non-numeric characters.
	`3004`	Error: `[error_message]`. The value is invalid for a reason other than `3001`/`3003` — for example `transaction_amount` sent without `transaction_currency`.
	`3005`	Unrecognized property: `[data_field_name]`. The request contains an unsupported property. Check for typos.
	`3007`	Invalid `action_type` input parameter. Check for stray spaces or special characters.
	`4001`	System error. See the status page or contact SEON.
`401`	`1017`	Invalid authorization IP. The request came from an IP that is not authorised for your account.
	`1019`	Your trial has expired. Contact SEON to continue.
	`2001`	Missing license key. The `X-API-KEY` header is absent. Also returned as System database error when SEON cannot reach its database.
	`2002`	Invalid license key. The key in `X-API-KEY` is incorrect — check the Organization page.
	`2003`	Your subscription has ended.
	`2004`	Inactive license. The license has expired or has not been activated yet.
`429`	`4004`	Too many requests.
`500`	`4001`	Unexpected server error. Check the status page or contact SEON with the `transaction_id`.

Next steps

Sub-API references

The *_details objects contain the full response of the corresponding sub-API:

IP API — the full contents of ip_details
Email API — the full contents of email_details
Phone API — the full contents of phone_details
AML API — the full contents of aml_details
eKYC payload examples — ekyc_result and ekyc_data

Additional topics

Fraud API Request — request attributes and code samples
JavaScript Agent v6 — the web device_details payload
Scoring Engine & Rules — how applied_rules and state are produced
Blackbox machine learning — activating blackbox_score
Rule categories — enabling rule_category_details
Errors — the complete SEON error code reference across all APIs

For additional support, contact your SEON representative.

Fraud API Response

Table of Contents

Envelope

Response attributes

Example response

Error responses

Next steps

Sub-API references

Additional topics