Deprecated versions
Fraud API v1.0
Request
SEON’s Fraud API is the core end-to-end solution designed to reduce fraud. It includes all our module APIs, but you can enable or disable them such as the Email API or the device fingerprint function via JavaScript snippet. It supports business-specific data fields for scores, using the user_label.
JSON Attributes | Type | Required | |
---|---|---|---|
ip | string | no | |
action_type | string | no | |
transaction_id | string | no | |
affiliate_id | string | no | |
affiliate_name | string | no | |
user_order_memo | string | no | |
run_email_api | boolean | no | |
string | no | ||
email_domain | string | no | |
password_hash | string | no | |
user_fullname | string | no | |
user_name | string | no | |
user_id | string | no | |
user_created | integer | no | |
user_country | string | no | |
user_city | string | no | |
user_region | string | no | |
user_zip | string | no | |
user_street | string | no | |
user_street2 | string | no | |
session_id | string | no | |
device_id | string | no | |
payment_mode | string | no | |
card_fullname | string | no | |
card_bin | string | no | |
card_hash | string | no | |
card_last | string | no | |
avs_result | string | no | |
cvv_result | boolean | no | |
phone_number | string | no | |
transaction_type | string | no | |
transaction_amount | float | no | |
transaction_currency | string | no | |
items | array of item objects | no | |
shipping_country | string | no | |
shipping_city | string | no | |
shipping_region | string | no | |
shipping_zip | string | no | |
shipping_street | string | no | |
shipping_street2 | string | no | |
shipping_phone | string | no | |
shipping_fullname | string | no | |
shipping_method | string | no | |
billing_country | string | no | |
billing_city | string | no | |
billing_region | string | no | |
billing_zip | string | no | |
billing_street | string | no | |
billing_street2 | string | no | |
billing_phone | string | no | |
discount_code | string | no | |
gift | boolean | no | |
gift_message | boolean | no | |
merchant_id | string | no | |
merchant_created_at | integer | no | |
merchant_country | string | no | |
details_url | string | no | |
user_label | object | no | |
Response
The endpoint returns JSON structured response.
JSON Attributes | Type | |
---|---|---|
id | string | |
state | string | |
fraud_score | number | |
proxy_score | number | |
ip_details | object | |
email_details | object | |
bin_details | object | |
phone_details | object | |
version | string | |
applied_rules | array of object | |
device_details | object | |
calculation_time | integer | |
seon_id | integer | |
Errors for Fraud API v1.0
Error Code | Explanation |
---|---|
1000 | Empty request body. |
1001 | IP address is missing. |
1002 | IP address is invalid. |
1003 | License key is missing. |
1004 | License key is invalid. |
1005 | Invalid public key. |
1006 | JSON input is invalid. |
1008 | Missing email address. |
1009 | Invalid email address. |
1010 | Invalid authorization header. |
1011 | Inactive license. |
1012 | Your subscription has ended. |
2001 | System database error. |
3000 | [data_field_name] size must be between [minimum_value] and [maximum_value] . |
3001 | Invalid ‘user_created’ input parameter. |
3002 | Invalid ‘cvv_result’ input parameter. |
3003 | Invalid ‘transaction_amount’ input parameter. |
3004 | Invalid ‘items_quantity’ input parameter. |
3005 | Invalid ‘items_price’ input parameter. |
3006 | Invalid ‘merchant_created_at’ input parameter. |
3007 | Invalid ‘action_type’ input parameter. |
3008 | ‘transaction_amount’ not provided along with ‘transaction_currency’. |
3009 | Invalid ‘gift’ input parameter. |
3010 | Invalid ‘gift_message’ input parameter. |
Migration from Fraud API v1.0 to v2.0
New config object for Fraud API
run_email_api
field in input is deprecated for v2.0, Email API should be set inconfig
object (setemail_api: true
).- IP API won’t be executed by default, need to set explicitly in
config
object. (setip_api: true
). - Device fingerprint won’t be enabled by default, need to set explicitly in
config
object. (setdevice_fingerprinting: true
). - Phone API is supported for Fraud API. (set
phone_api: true
).
Session Handling
- Instead of the
session_id
you need to send the encrypted payload returned by the SDK (supported by JS Agent v4, iOS SDK 3.0.0, Android SDK 3.0.0). Thesession_id
parameter is still required for the configuration, the change affects the data that you need to send in the Fraud API request related to the Device Fingerprint module. - The previous SDK versions are still supported with the
session_id
field, but we highly recommend to migrate the Device Fingerprint module. - The public key is no longer necessary with the latest SDK versions.
- You must set
device_fingerprinting: true
in the config object to enable the feature.
Keep in mind the following input fields were renamed in Fraud API v2.0:
user_label
->custom_fields
item_user_label
->item_custom_fields
user_order_memo
->order_memo
Response changes: Please find the full data field mapping from Fraud API v1.0 to v2.0 here.
Email API v1.0
Request
JSON Attributes | Type | Required | |
---|---|---|---|
string | yes | ||
Response
The endpoint returns JSON structured response.
JSON Attributes | Type | |
---|---|---|
string | ||
email_score | number | |
email_exists | boolean | |
disposable | boolean | |
free | boolean | |
domain_exists | boolean | |
email_domain_details | object | |
email_account_details | object | |
Email API v2.0
Request
The [email_address]
in the request URI should include the full email address, for example: example@example.com
Optional query string parameters
Add the following parameters to the request URL for more control over the returned data, as seen in the example URL below.
Request Attributes | Value | Required | |
---|---|---|---|
include | history | no | |
include | flags | no | |
include | id | no | |
flags_timeframe_days | [number of days] | no | |
timeout | [number of milliseconds] | no | |
Response
The endpoint returns JSON structured response.
JSON Attributes | Type | |
---|---|---|
string | ||
score | number | |
deliverable | boolean | |
domain_details | object | |
account_details | object | |
breach_details | object | |
applied_rules | array of object | |
history | object | |
flags | array of object | |
id | string | |
Email API v2.1
Request
The [email_address]
in the request URI should include the full email address, for example: example@example.com
Optional query string parameters
Add the following parameters to the request URL for more control over the returned data, as seen in the example URL below.
Request Attributes | Value | Required | |
---|---|---|---|
include | history | no | |
include | flags | no | |
include | id | no | |
flags_timeframe_days | [number of days] | no | |
timeout | [number of milliseconds] | no | |
Response
The endpoint returns JSON structured response.
JSON Attributes | Type | |
---|---|---|
string | ||
score | number | |
deliverable | boolean | |
domain_details | object | |
account_details | object | |
breach_details | object | |
applied_rules | array of object | |
history | object | |
flags | array of object | |
id | string | |
Phone API v1.0
Request
The [phone_number]
in the request URI should include the full phone number, including country code. Cannot contain hyphens or spaces, the + sign is optional. The maximum length for the [phone_number]
is 19 characters. For example: 36301234567
Optional query string parameters
In order to request additional or receive less information, use following parameters in the request URL as in the example below:
JSON Attributes | Value | Required | |
---|---|---|---|
include | history | no | |
include | flags | no | |
include | id | no | |
include | cnam_lookup | no | |
include | hlr_details | no | |
flags_timeframe_days | [number of days] | no | |
exclude | photo | no | |
exclude | last_seen | no | |
timeout | [number of milliseconds] | no | |
Response
The endpoint returns JSON structured response.
JSON Attributes | Type | |
---|---|---|
number | integer | |
valid | boolean | |
type | string | |
country | string | |
carrier | string | |
score | number | |
account_details | object | |
applied_rules | array of object | |
hlr_details | object | |
cnam_details | object | |
history | object | |
flags | array of object | |
id | string | |
Phone API v1.1
Request
The [phone_number]
in the request URI should include the full phone number, including country code. Cannot contain hyphens or spaces, the + sign is optional. The maximum length for the [phone_number]
is 19 characters. For example: 36301234567
Optional query string parameters
In order to request additional or receive less information, use following parameters in the request URL as in the example below:
JSON Attributes | Value | Required | |
---|---|---|---|
include | history | no | |
include | flags | no | |
include | id | no | |
include | cnam_lookup | no | |
include | hlr_details | no | |
flags_timeframe_days | [number of days] | no | |
exclude | photo | no | |
exclude | last_seen | no | |
timeout | [number of milliseconds] | no | |
Response
The endpoint returns JSON structured response.
JSON Attributes | Type | |
---|---|---|
number | integer | |
valid | boolean | |
type | string | |
country | string | |
carrier | string | |
score | number | |
account_details | object | |
applied_rules | array of object | |
hlr_details | object | |
cnam_details | object | |
history | object | |
flags | array of object | |
id | string | |
Phone API v1.2
Request
The [phone_number]
in the request URI should include the full phone number, including country code. Cannot contain hyphens or spaces, the + sign is optional. The maximum length for the [phone_number]
is 19 characters. For example: 36301234567
Optional query string parameters
In order to request additional or receive less information, use following parameters in the request URL as in the example below:
JSON Attributes | Value | Required | |
---|---|---|---|
include | history | no | |
include | flags | no | |
include | id | no | |
include | cnam_lookup | no | |
include | hlr_details | no | |
flags_timeframe_days | [number of days] | no | |
exclude | photo | no | |
exclude | last_seen | no | |
timeout | [number of milliseconds] | no | |
Response
The endpoint returns JSON structured response.
JSON Attributes | Type | |
---|---|---|
number | integer | |
valid | boolean | |
type | string | |
country | string | |
carrier | string | |
score | number | |
account_details | object | |
applied_rules | array of object | |
hlr_details | object | |
cnam_details | object | |
history | object | |
flags | array of object | |
id | string | |
IP API v1.0
Request
The [ip]
in the request URI should include the full IPv4 or IPv6 address, example: 1.1.1.1
or 2001:db8:3333:4444:5555:6666:7777:8888
.
Optional query string parameters
In order to request additional or receive less information, use following parameters in the request URL as in the example below:
Request Attributes | Value | Required | |
---|---|---|---|
include | history | no | |
include | flags | no | |
include | id | no | |
flags_timeframe_days | [number of days] | no | |
Response
The endpoint returns JSON structured response.
JSON Attributes | Type | |
---|---|---|
ip | string | |
score | number | |
country | string | |
state_prov | string | |
city | string | |
timezone_offset | string | |
isp_name | string | |
latitude | string | |
longitude | string | |
type | string | |
open_ports | array | |
tor | boolean | |
vpn | boolean | |
web_proxy | boolean | |
public_proxy | boolean | |
spam_number | integer | |
spam_urls | array | |
applied_rules | array of object | |
history | object | |
flags | array of object | |
id | string | |
JavaScript Agent v2.0
Our JavaScript Agent collects data through the browser for device fingerprinting purposes. Please follow the steps below to enable session and device data-collection with our JavaScript agent:
- Include SEON JavaScript agent in your header, between
<head>
…</head>
tags. - Insert the initialization code to the bottom of your page, just before the
</body>
tag. - Replace
[session_id]
with the unique identifier of user’s session. - We recommend to use
onSuccess
andonError
callback functions to make sure that the data has been saved successfully. Fraud API requests initiated before the successful callback won’t be able to reference the collected device data.
Options
JSON Attributes | Type | Default | |
---|---|---|---|
social_detection | boolean | false | |
audio_fingerprint | boolean | false | |
use_flash | boolean | true | |
Don’t forget to replace [session_id]
with your unique session identifier.
<html>
<head>
...
<script src="https://cdn.seon.io/v2.0/js/agent.js"></script>
...
</head>
<body>
...
<script>
seon.start({
session_id: '[session_id]',
social_detection: false,
audio_fingerprint: false,
use_flash: true,
onSuccess: function() {
console.log("Session data was sucessfully saved!");
},
onError: function() {
console.log("Something went wrong. Session data was not saved sucessfully!");
}
});
</script>
</body>
</html>
device_details
Object with JavaScript Agent v2.0
JSON Attributes | Type | |
---|---|---|
session_id | string | |
timezone | string | |
private_mode | boolean | |
useragent | string | |
fonts | integer | |
plugins | integer | |
op_sys | string | |
cookie_enabled | boolean | |
screen | string | |
avail_screen | string | |
window_screen | string | |
webrtc_count | integer | |
cookie_hash | string | |
device_hash | string | |
js_ip | string | |
js_ip_country | string | |
js_ip_isp | string | |
browser_hash | string | |
webrtc_ips | array | |
webrtc_activated | boolean | |
flash | boolean | |
java | boolean | |
plugins_hash | string | |
fonts_hash | string | |
plugin_names | array | |
device_type | string | |
fonts_names | array | |
social_sites | array | |
dns_ip | string | |
dns_ip_country | string | |
dns_ip_isp | string | |
JavaScript Agent v3.0
Our JavaScript Agent collects data through the browser for device fingerprinting purposes. In order to use it, you need to add the JavaScript file inside <head>
tags. We recommend to use our CDN hosted JavaScript for fast page load and continuous support of the script.
Step-by-step guide
- Integrate the JavaScript Agent into your website or web application, which will send the device information to SEON’s platform including the
session_id
that you generated (max. 64 characters). - During the user’s session use the same
session_id
in Fraud API calls. - The device details will be provided in the response of the Fraud API, and will be displayed on the Admin Panel on the Transaction details page.
- We recommend to use
onSuccess
andonError
callback functions to make sure that the data has been saved successfully. Fraud API requests initiated before the successful callback won’t be able to reference the collected device data.
<html>
<head>
...
<script src="https://cdn.seon.io/v3.0/js/agent.js"></script>
</head>
<body>
...
</body>
</html>
Configuration parameters
To configure the JavaScript module, you need to call seon.config()
function:
JSON Attributes | Required | |
---|---|---|
public_key | yes | |
session_id | yes | |
audio_fingerprint | no | |
canvas_fingerprint | no | |
webgl_fingerprint | no | |
onSuccess | no | |
onError | no | |
Don’t forget to replace [session_id]
with your unique session identifier, and [public_key]
with your own public key. Your public key can be found on the My Account page.
seon.config({
public_key: "[public_key]",
session_id: "[session_id]",
audio_fingerprint: true,
canvas_fingerprint: true,
webgl_fingerprint: true,
onSuccess: function(message) {
console.log('success', message);
},
onError: function(message) {
console.log('error', message);
}
});
Integration
Fingerprinting can be triggered by the seon.saveSession()
function. After collection, all the available information will automatically be sent to the configured endpoint.
seon.saveSession(function(success) {
if (success) {
console.log("Session data has been saved!");
} else {
console.log("Failed to save session data.");
}
});
Payload
SEON JavaScript SDK sends a POST request to the configured endpoint with a JSON payload. Some fields can be ‘null’, if the actual browser does not support or return data for that specific data point. In every other case, data types are preserved. Find a sample payload on the right side.
Common issues
The session_id
is provided in the Fraud API request, but the device_details
is null
in the response and there is no device information on the Transaction details page. - This means the JavaScript agent could not send the device data to SEON correctly. Please look into your integration and check again.
The session_id
is provided in the Fraud API request, but the device_details
is null
in the response but there is device information on the Transaction details page. - This means the device data arrived later than the Fraud API request at SEON. Please wait until the JavaScript finished successfully (use callbacks).
device_details
Object with JavaScript Agent v3.0
JSON Attributes | Type | |
---|---|---|
type | string | |
source | string | |
session_id | string | |
adblock | boolean | |
audio_hash | string | |
battery_charging | boolean | |
battery_level | integer | |
browser_hash | string | |
browser | string | |
browser_version | string | |
canvas_hash | string | |
cookie_enabled | string | |
cookie_hash | string | |
device_hash | string | |
device_memory | integer | |
device_type | string | |
dns_ip | string | |
dns_ip_country | string | |
dns_ip_isp | string | |
do_not_track | boolean | |
flash_enabled | boolean | |
font_count | integer | |
font_hash | string | |
font_list | array | |
hardware_concurrency | integer | |
java_enabled | boolean | |
device_ip_address | string | |
device_ip_country | string | |
device_ip_isp | string | |
accept_language | array | |
os | string | |
platform | string | |
plugin_count | integer | |
plugin_hash | string | |
plugin_list | array | |
private | boolean | |
region_language | string | |
region_timezone | string | |
screen_available_resolution | string | |
screen_color_depth | integer | |
screen_pixel_ratio | integer | |
screen_resolution | string | |
social_logins | array | |
touch_support | boolean | |
user_agent | string | |
webgl_hash | string | |
webgl_vendor | string | |
webrtc_activated | boolean | |
webrtc_count | integer | |
webrtc_ips | array | |
window_size | string | |
JavaScript Agent v4.0
You can integrate our optional device fingerprinting module directly into a web app, by using our JavaScript agent. Please, always use our CDN hosted script to ensure you always load the latest available version.
- Include the JavaScript Agent for example inside the
<head>
tags of your website or web app. You can also lazy-load it or execute upon specific actions (e.g. clicking on Login, Payment, Registration buttons, before calling the API). In this case you must ensure that the module has been loaded successfully before invoking its methods. - Set a unique
session_id
for your client using theseon.config()
function. - Call the
seon.getBase64Session()
function to get the encrypted payload for the device. - Send the returned session payload string to your backend and add to the
session
property in your Fraud API request. The Fraud API call should be still executed if thesession
is missing, due to non-executed JS snippet. Tip: Add timeout to JS and utilise Fraud API call after.
All the device fingerprinting data will be available in the response of the Fraud API, and accessible on the Admin Panel of the Transactions Details page.
Configuration parameters
To configure the JavaScript module, you need to call seon.config()
function:
JSON Attributes | Required | |
---|---|---|
host | no | |
session_id | yes | |
audio_fingerprint | no | |
canvas_fingerprint | no | |
webgl_fingerprint | no | |
onSuccess | no | |
onError | no | |
Integration
Fingerprinting can be triggered by seon.getBase64Session()
function. After collecting all the available information, the function returns an encrypted base64 encoded payload.
Payload
SEON JavaScript library collects device information and prepares an encrypted payload to use in Fraud API. The information on client side is not readable, we’ll reveal in the Fraud API response and on the Admin Panel. Some fields can be null
, if the actual browser does not support or return data for that specific data point. In every other case, data types are preserved. Find a sample payload on the right side.
Common issues
- The
session
is provided in the Fraud API request, but thedevice_details
isnull
in the response and there is no device information on the Transaction details page. - This means the encrypted payload is corrupted. Please look into your integration and check again. - The v4 version of the JavaScript Agent is not compatible with the Fraud API v1, we highly recommend to upgrade because of security and performance reasons.
- If you use CSP (Content Security Policy) headers on your site, you must allow the following domains in
connect-src
directive for full functionality based on your host configuration.
Default:*.seondnsresolve.com
seondf.com:*.seondfresolver.com
deviceinf.com:*.deviceinfresolver.com
getdeviceinf.com:*.getdeviceinfresolver.com
<html>
<head>
...
<script src="[source_url]"></script>
</head>
<body>
...
</body>
</html>
You can use the following script source URLs ([source_url]
):
https://cdn.seondf.com/js/v4/agent.js
https://cdn.deviceinf.com/js/v4/agent.js
https://cdn.getdeviceinf.com/js/v4/agent.js
seon.config({
host: "seondf.com",
session_id: "[session_id]",
audio_fingerprint: true,
canvas_fingerprint: true,
webgl_fingerprint: true,
onSuccess: function(message) {
console.log("success", message);
},
onError: function(message) {
console.log("error", message);
}
});
seon.getBase64Session(function(data) {
if (data) {
console.log("Session payload", data);
} else {
console.log("Failed to retrieve session data.");
}
});
iOS SDK v1.0
device_details
Object with iOS SDK v1.0
JSON Attributes | Type | |
---|---|---|
type | string | |
session_id | string | |
device_udid | string | |
ios_version | string | |
ip_address | string | |
app_platform_type | string | |
device_adid | string | |
wifi_mac_address | string | |
network_config | string | |
battery_level | string | |
device_orientation | string | |
file_system_size | string | |
physical_memory | string | |
cpu_type | string | |
cpu_count | integer | |
cpu_speed | string | |
accessories_number | string | |
has_proximity_sensor | boolean | |
screen_brightness | string | |
screen_resolution | string | |
ios_device_name | string | |
kernel_version | string | |
icloud_ubiquity_token | string | |
local_language | string | |
currency_code | string | |
system_uptime | string | |
Response
Android SDK v5
You can integrate our device fingerprinting module directly into Android mobile apps, by using our SDK found on GitHub. It will collect information based on the user’s software and hardware configuration.
- The SDK returns an encrypted, base64 encoded string to add in the
session
property in the Fraud API request. It isn’t permitted to access or modify the payload on the clients. - JSON structured device details will be revealed in the Fraud API response.
JSON Attributes | Type | |
---|---|---|
type | string | |
source | string | |
session_id | string | |
android_id | string | |
android_version | string | |
app_guid | string | |
audio_mute_status | boolean | |
audio_volume_current | integer | |
battery_charging | boolean | |
battery_health | string | |
battery_level | integer | |
battery_temperature | float | |
battery_voltage | integer | |
build_device | string | |
build_id | string | |
build_manufacturer | string | |
build_number | string | |
build_time | integer | |
carrier_country | string | |
carrier_name | string | |
cpu_count | integer | |
cpu_hash | string | |
cpu_speed | double | |
cpu_type | string | |
device_hash | string | |
device_cellular_id | string | |
device_name | string | |
free_storage | integer | |
has_proximity_sensor | boolean | |
is_emulator | boolean | |
is_rooted | boolean | |
kernel_arch | string | |
kernel_name | string | |
kernel_version | string | |
last_boot_time | integer | |
network_config | string | |
pasteboard_hash | string | |
physical_memory | integer | |
region_country | string | |
region_language | string | |
region_timezone | string | |
screen_brightness | integer | |
screen_height | integer | |
screen_scale | integer | |
screen_width | integer | |
sensor_hash | string | |
system_uptime | integer | |
total_storage | integer | |
wifi_mac_address | string | |
wifi_ssid | string | |
dns_ip | string | |
dns_ip_country | string | |
dns_ip_isp | string | |
device_ip_address | string | |
device_ip_country | string | |
device_ip_isp | string | |
Response
Android SDK v1.0
device_details
Object with Android SDK v1.0
JSON Attributes | Type | |
---|---|---|
type | string | |
device_id | string | |
android_id | string | |
device_name | string | |
build_id | string | |
build_device | string | |
build_manufacture | string | |
build_time | date | |
network_name | string | |
is_plugged_in | boolean | |
android_version | string | |
build_number | string | |
kernel_version | string | |
locale_country_code | string | |
wifi_mac_address | string | |
session_id | string | |
cpu_type | string | |
cpu_count | integer | |
cpu_speed | string | |
cpu_hash | string | |
system_uptime | time | |
ip_address | string | |
has_proximity_sensor | boolean | |
physical_memory | string | |
locale_language | string | |