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

POST/api/v2/transaction

Headers

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": "72.229.28.185",
  "sub_seller": "9991"
}

Curl command

curl -i \
-X POST https://api.fraugsterapi.com/api/v2/transaction \
-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 name	Meaning	Example
`error_msg`	An 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_approved`	A 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_id`	A unique transaction ID generated by Fraugster.	“nSjpinF3knNsrbdOBBs5xQ”
`is_liable`	Indicates whether Fraugster takes liability for this transaction. One of `true` or `false`.	false
`liability_reason`	An 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.	"high_amount"
`score`	The 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
`validation`	Information on the data validation of the API request. Read more in Data validation.
`evidence`, `signals`	Read more in Signals.
`frg_device_id`	The 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.

Error	Error message
Invalid data type	The value is of an invalid type. Check the Fraugster API reference for information on the supported data types.
Invalid country	The country is not valid. Must be an ISO 3166-1 alpha-2 code.
Invalid timestamp	The 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 date	The 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 IP	Unable to parse the IP address as IPv4 or IPv6.
Reserved IP	The IP address is reserved for special usage or applications as defined by the IETF and IANA.
Excess IP info	The IP address contains unnecessary characters.
Missing timezone	The timezone information is missing. The format '2006-01-02Z07:00' is expected.
Null string	The value is a null in string format. Please use null literal or a meaningful string.
Unknown datapoint	There is no such datapoint defined by the Fraugster API. Check the Fraugster API reference for information on the available datapoints.
Unknown value	The datapoint only accepts a closed set of values. The provided value is not one of them.

HTTP endpoint​

Headers​

Body example​

Curl command​

API response​

Response example​

Data validation​

Response example​

HTTP endpoint

Headers

Body example

Curl command

API response

Response example

Data validation

Response example