Fraud API
SEON's proprietary API combines our email, phone number, IP, and AML APIs with device fingerprinting so that you can request and receive our enriched data, rules, and scoring in a single API call.
Good to know
- The API is fully modular, meaning you can choose to enable or disable each sub-APIs (Email, Phone, IP, or AML) or the device fingerprinting tool. Use the
config
object to enable or disable modules. - You can use the
custom_fields
object to send almost any custom data point to SEON. Your team can also use custom fields in rules to create a completely custom ruleset. - All SEON API requests are case-sensitive. Please follow the formatting below to avoid errors.
For more context on how to begin your API integration check the Introduction section or our Integration Guide.
Request
Request Attributes | Type | Required | |
---|---|---|---|
config | object | no | |
action_type | string | no | |
ip | string | no | |
transaction_id | string | no | |
affiliate_id | string | no | |
affiliate_name | string | no | |
order_memo | string | no | |
string | no | ||
email_domain | string | no | |
payment_id | string | no | |
password_hash | string | no | |
user_fullname | string | no | |
user_name | string | no | |
user_firstname | string | no | |
user_middlename | string | no | |
user_lastname | string | no | |
user_pob | string | no | |
user_photoid_number | string | no | |
user_id | string | no | |
user_created | integer | no | |
user_category | string | no | |
user_account_status | string | no | |
user_bank_account | string | no | |
user_bank_name | string | no | |
user_balance | float | no | |
user_verification_level | string | no | |
user_dob | date | 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 | |
session | string | no | |
device_id | string | no | |
payment_mode | string | no | |
payment_provider | string | no | |
card_fullname | string | no | |
card_bin | string | no | |
card_hash | string | no | |
card_expire | date | no | |
card_last | string | no | |
avs_result | string | no | |
cvv_result | boolean | no | |
status_3d | string | no | |
sca_method | string | no | |
phone_number | string | no | |
transaction_type | string | no | |
transaction_amount | float | no | |
transaction_currency | string | no | |
items | array of 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_category | string | no | |
merchant_id | string | no | |
merchant_created_at | integer | no | |
merchant_country | string | no | |
receiver_fullname | string | no | |
receiver_bank_account | string | no | |
details_url | string | no | |
regulation | string | no | |
bonus_campaign_id | string | no | |
brand_id | string | no | |
custom_fields | object | no | |
HTTP Endpoint
Response
The endpoint returns JSON structured response.
JSON Attributes | Type | |
---|---|---|
id | string | |
state | string | |
fraud_score | number | |
ip_details | object | |
email_details | object | |
bin_details | object | |
phone_details | object | |
aml_details | object | |
version | string | |
applied_rules | array of object | |
device_details | object | |
geolocation_details | object | |
calculation_time | integer | |
seon_id | integer | |
rule_category_details | array of object | |
Response
JavaScript Agent v5
You can integrate our optional device fingerprinting module directly into a web app, by using our JavaScript agent. Please, 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 it upon specific actions (e.g. clicking on Login, Payment, and 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 a non-executed JS snippet. Tip: Add timeout to JS and utilize 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 | |
font_list | no | |
onSuccess | no | |
onError | no | |
max_proxy_delay | 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/v5/agent.js
https://cdn.deviceinf.com/js/v5/agent.js
https://cdn.getdeviceinf.com/js/v5/agent.js
seon.config({
host: "seondf.com",
session_id: "[session_id]",
audio_fingerprint: true,
canvas_fingerprint: true,
webgl_fingerprint: true,
max_proxy_delay: 1000;
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
You can integrate our device fingerprinting module directly into iOS 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 returned in the Fraud API response.
- Latest version available:
5.0.0
Details on previous versions here.
JSON Attributes | Type | |
---|---|---|
type | string | |
source | string | |
session_id | string | |
accessories_count | integer | |
audio_mute_status | boolean | |
audio_volume_current | integer | |
battery_charging | boolean | |
battery_level | integer | |
can_send_mail | boolean | |
can_send_text | boolean | |
cpu_count | integer | |
cpu_type | string | |
device_adid | string | |
device_hash | string | |
device_name | string | |
device_orientation | string | |
device_udid | string | |
icloud_ubiquity_token | string | |
ios_device_name | string | |
ios_version | string | |
is_biometrics_enabled | boolean | |
is_emulator | boolean | |
is_ios_app_on_mac | boolean | |
is_jailbroken | boolean | |
is_on_call | boolean | |
is_passcode_enabled | boolean | |
is_screen_captured | boolean | |
kernel_arch | string | |
kernel_name | string | |
kernel_version | string | |
network_config | string | |
pasteboard_hash | string | |
physical_memory | unsigned long | |
region_country | string | |
region_language | string | |
region_timezone | string | |
screen_brightness | integer | |
screen_height | integer | |
screen_width | integer | |
system_uptime | integer | |
timezone_identifier | string | |
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
You can integrate our device fingerprinting module directly into Android mobile apps, by using our SDK found on GitHub. In the repo you will also find more details about the integration like requirements and samples. 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.
- Latest version available:
6.0.1
Details on previous versions here.
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 | |
biometric_status | boolean | |
bootloader_state | string | |
build_device | string | |
build_id | string | |
build_manufacturer | string | |
build_model | 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 | |
developer_options_state | string | |
device_hash | string | |
device_cellular_id | string | |
device_name | string | |
device_orientation | string | |
free_storage | integer | |
gsf_id | string | |
has_proximity_sensor | boolean | |
interfering_apps | array of string | |
is_click_automator_installed | boolean | |
is_emulator | boolean | |
is_keyguard_secure | boolean | |
is_nfc_available | boolean | |
is_nfc_enabled | boolean | |
is_on_call | boolean | |
is_remote_control_connected | boolean | |
is_rooted | boolean | |
is_screen_being_mirrored | 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 | |
remote_control_provider | string | |
screen_brightness | integer | |
screen_height | integer | |
screen_scale | integer | |
screen_width | integer | |
sensor_hash | string | |
system_uptime | integer | |
timezone_identifier | string | |
total_storage | integer | |
usb_cable_state | string | |
usb_debugging_state | string | |
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 | |