Skip to main content

API request

The Fraugster API accepts a payment transaction as a JSON object where each key/value pair represents a datapoint. In this article, you find an example of an API request and response, as well as information on data validation.

HTTP endpoint



  • Authorization – required. Contains the credentials to authenticate with the server.
  • X-Forwarded-For – optional. A header for identifying the originating IP address of a client connecting through an HTTP proxy or a load balancer.
  • User-Agent – optional. Contains a characteristic string that allows the network protocol peers to identify the application type, operating system, software vendor, or software version of the requesting software user agent.

Body example

"platform_id": "CollectPartner",
"trans_id": "d72xfdil915889fu",
"order_id": "000000999140045453863",
"items": [
"item_id": 42,
"unique_item_id": "42-FA12987-089723",
"item_desc": "Jacket",
"additional_description": "Red | Size M",
"item_amt": 44.99,
"discount": 8.45,
"tax_rate": 19,
"quantity": 1
"trans_amt": 44.99,
"trans_currency": "EUR",
"trans_ts": "2018-06-12T11:34:21.000Z",
"pmt_method": "card",
"cc_num_hash": "745rcsljDUZBC45d7esl25584/j38fbD98bnf834nd7=",
"cc_bin": "123456789",
"cc_last_4_dig": "1234",
"bin_brand": "MasterCard",
"cc_exp_dt": "0622",
"bill_ad_city": "New York",
"bill_ad_ctry": "US",
"bill_ad_line1": "42 Main Street",
"bill_ad_zip": "12345",
"cust_email": "[email protected]",
"cust_last_name": "Hopper",
"cust_first_name": "Grace",
"cust_name_title": "Ms",
"cust_id": "2234",
"ship_ad_last_name": "Hopper",
"ship_ad_first_name": "Grace",
"ship_name_title": "Ms",
"ship_ad_city": "New York",
"ship_ad_ctry": "US",
"ship_ad_line1": "1234 Toonville Court 1",
"ship_ad_zip": "98765",
"ip": "",
"sub_seller": "9991"

Curl command

curl -i \
-H "Authorization: SessionToken KWqrUW4wUu7cJ5e5A7i2iNd" \
-d '{"trans_id": "42d72xfdil915889fu","trans_ts":"2018-06-12T11:34:21.000Z","trans_amt":"44.97","cust_first_name":"Grace","cust_last_name":"Hopper","cust_email":"[email protected]"}'

API response

The Fraugster API uses conventional HTTP response codes to indicate the success or failure of a request. Read more about error handling in Errors.

Each incoming transaction receives an associated identifier – Fraugster transaction ID frg_trans_id. If you need to contact us about a specific transaction, providing the Fraugster transaction ID helps us assist you the fastest way possible.

Response example

"fraugster_approved": 0,
"frg_trans_id": "abc01f6ccc8a5832a7871fdb14be1211",
"is_liable": false,
"liability_reason": "declined",
"score": 0.92,
"validation": {
"ok": true
"evidence": {
"signals": [
"category": "seller",
"id": "ff9578ab",
"related_to": ["slr_crncy", "slr_ctry"],
"type": "technical"
"category": "user",
"id": "85dd94qc",
"related_to": ["cust_email", "cust_first_name", "cust_last_name"],
"type": "bad"
"frg_device_id": "2fc4b5912826ad1"

Please note: this is an example of a basic API response. In most cases, it will probably be longer, especially if you're using opt-in features. Fraud Management SaaS users also receive rule hits as part of the API response.

The following table illustrates the fields that each API response contains.

Field nameMeaningExample
error_msgAn error message pertaining to the status of the API request. An optional field returned only if an actual error occurred. Not to be confused with datapoint validation errors returned separately in the validation field.“Server error”
fraugster_approvedA decision on whether the transaction should be declined (0), approved (1), marked for manual review (2), or take a custom action (3) defined by you.0
frg_trans_idA unique transaction ID generated by Fraugster.“nSjpinF3knNsrbdOBBs5xQ”
is_liableIndicates whether Fraugster takes liability for this transaction. One of true or false.false
liability_reasonAn explanation for cases where Fraugster doesn't take liability for the transaction. One of
  • declined: Fraugster declined the transaction.
  • high_amount: The transaction amount in Euro is above the agreed upon liability threshold.
  • not_ffp: The merchant's account is not covered by the FraudFree product.
  • unknown_amount: The transaction amount was not provided in the request.
  • approve_list: One or more datapoints in the transaction were put on an approve list by the merchant.
scoreThe risk score given to the transaction by Fraugster. Between 0.00 and 1.00. The lower the score, the lower the fraud probability.0.66
validationInformation on the data validation of the API request. Read more in Data validation.
evidence, signalsRead more in Signals.
frg_device_idThe device ID value determined by the device_id_mapped attribute. Read more about the device ID at Fraugster in Device ID.2fc4b5912826ad1

Data validation

As part of the HTTP response, Fraugster returns data validation errors to indicate if you’ve sent invalid datapoints in your request.

Response example

"frg_trans_id": "9436199ad26311eabbda54ee75b3b98a",
"score": 0.42,
"fraugster_approved": 1,
"is_liable": true,
"validation": {
"ok": false,
"errors": [
"datapoint": "ip",
"msg": "Unable to parse the IP address as IPv4 or IPv6."
"datapoint": "trans_ts",
"msg": "The timestamp is not valid. Must be an RFC3339-encoded timestamp."
"datapoint": "acct_ad_ctry",
"msg": "The country is not valid. Must be an ISO 3166-1 alpha-2 code."

The field ok in the response example is introduced for API convenience. The value true indicates that no data validation errors occurred; the value false indicates that some validation errors require your attention. The affected datapoints and error messages are included to facilitate debugging.

The error messages accompanying the datapoint in the response body are not error codes and are subject to change without prior notice. The list of error values is not exhaustive and is subject to expansion in the future.

ErrorError message
Invalid data typeThe value is of an invalid type. Check the Fraugster API reference for information on the supported data types.
Invalid countryThe country is not valid. Must be an ISO 3166-1 alpha-2 code.
Invalid timestampThe timestamp is not valid. Must be an RFC3339-encoded UTC timestamp. The timezone accepts either the character "Z" to indicate UTC or a time offset in the format "+02:00" or "-07:30".
Invalid dateThe date is not valid. Must be the date part of an RFC3339-encoded UTC timestamp, for example '2006-01-02Z'. The timezone accepts either the character "Z" to indicate UTC or a time offset in the format "+02:00" or "-07:30".
Invalid IPUnable to parse the IP address as IPv4 or IPv6.
Reserved IPThe IP address is reserved for special usage or applications as defined by the IETF and IANA.
Excess IP infoThe IP address contains unnecessary characters.
Missing timezoneThe timezone information is missing. The format '2006-01-02Z07:00' is expected.
Null stringThe value is a null in string format. Please use null literal or a meaningful string.
Unknown datapointThere is no such datapoint defined by the Fraugster API. Check the Fraugster API reference for information on the available datapoints.
Unknown valueThe datapoint only accepts a closed set of values. The provided value is not one of them.