logo
API Reference
Help Desk
Banking / Fintech
Commerce
Identity
Terms of Service
Powered by Stoplight

API Documentation

Contents:

Introduction

The Fraud.net API allows you to obtain critical insight into the validity of a Cart (pre-authorization, e-commerce) or a Transaction. To mitigate fraud, we require data on a Cart and/or a Transaction. Data is shared via our Check and Update API requests.

  1. Check request includes the details of a Cart or a Transaction. As part of the evaluation, we append 1,000s of additional data points which is utlized by our machine learning platform to calculate a fraud risk score.

  2. Update request relay any changes to a Cart or a Transaction.

Fraud.net API requests are optimized for specific use cases such as banking, e-commerce, marketplaces, and travel. Typically, Fraud.net can accomodate requests to include customer specific API variables. To learn more, please contact your Customer Success Manager or email us at success@fraud.net.

Back to Top

Key Concepts

Carts and Transactions

  1. Cart is a data object that represents an e-commerce shopping cart.

  2. Transaction is a data object that represents an authorized purchase or action. For example, within e-commerce, at checkout, once a customers payment information is authorized, a Cart converts into a Transaction. The status of Carts and Transactions change over time (e.g. new, approved, paid, etc.)

Risk Score and Risk Group

Once a customer has created a Cart or a Cart has been converted to a Transaction, the data is sent to Fraud.net through the API, and the API will return a Risk Score and Risk Group. The Risk Score is a value from 0 to 100, where 0 indicates low risk and 100 indicates high risk. A Risk Score is assigned one of the following Risk Group labels: Low, Medium, or High. You can set the label thresholds for the Risk Groups in the Fraud.net Case Managemenet Portal. Additionally, the Risk Groups can be utilized in the Case Management Portal rules engine.

Updating Cart and Transaction Status

Over time, the status of the Carts and Transactions will change. Some examples of status changes include:

  • A Cart is converted to a Transaction
  • A Transaction is approved
  • A Transaction is determined to be fraud
  • Payment is declined

Fraud.net calculates risk factors based on Cart and Transaction data. As new data is available, it’s important that the data be sent to Fraud.net to optimize the algorithms for detecting fraud.

Each time Transaction status changes on your system, the Transaction should be updated using the Update API request.

For more information, see Uploading Cart and Order Status.

Back to Top

Your Data Is Safe

Your customer data that is highly sensitive. We are compliant with the General Data Protection Regulation (GDPR), and apply the standard to all customer data. Click here to learn more on our data security and privacy policies.

Back to Top

Authentication

Fraud.net manages access to the API and data via an API key. The API key is the primary data authentication method for your account. Users can manager and generate API keys by logging into the Fraud.net Case Management Portal. After logging into the Case Management Portal, on the menu bar, click Developer and then Connect your API.

The API uses Basic Access Authentication for security. Include a header where the key is Authorization and the value is constructed as follows:

  1. The username and password are combined with a single colon (:). This means that the username itself cannot contain a colon.
  2. The resulting string is end into an octet sequence. The character set to use for this encoding is by default unspecified, as long as it is compatible with US-ASCII, but the server may suggest use of UTF-8 by sending the charset parameter.
  3. The resulting string is encoded using a variant of Base64.
  4. The word “Basic” and a space (e.g. "Basic ") is then prepended to the encoded string.

For example, if the browser uses Aladdin as the username and OpenSesame as the password, then the field’s value is the base64-encoding of Aladdin:OpenSesame, or QWxhZGRpbjpPcGVuU2VzYW1l. Then the Authorization header will be:

Authorization: Basic QWxhZGRpbjpPcGVuU2VzYW1l

Back to Top

Errors

Possible error responses for Fraud.net API requests and what they mean:

  • 200 = Whether the Request was successful.
  • 401 = Unauthorized. Invalid credentials or authorization header.
  • 403 = Forbidden. You do not have authorization to make this request.
  • 406 = Not Acceptable. Invalid data being passed by the request.
  • 500 = Internal Server Error. Something went wrong on the server.
  • 503 = Service Unavailable

Back to Top

Uploading Cart and Transaction Status

As your customers add items to a Cart and then go through the checkout process, the status of the Cart and then the Transaction will change. For Carts, theses are tracked:

  • Whether the Cart has been verified
  • Whether the Cart is converted to a Transaction or Approved

For Transactions, these are tracked:

  • Whether the Transaction is fraudulent
  • The type of fraud
  • Whether the Transaction was canceled
  • Why it was canceled
  • The payment status
  • The return reason
  • The chargeback status

It’s important that you use the Status Update API requests to relay any changes to the status of a Cart or Transaction. By providing Fraud.net with up-to-date data, we can incrementally improve the fraud detection algorithms. When calling the status update API requests, use the Cart or Transaction ID that you used when calling the check API request when the Cart or Transaction was first created.

The Cart and Transaction update requests are very similar. However, the Cart update includes additional payment information.

Cart Status

The diagram below shows you the flow for Cart status updates. Note that you do not have to update the status for changes to the Cart involving addition or removal of items.

Cart Status Flow
Cart Status Flow

Transaction Status Flow

The diagrams below shows you the flow for transaction status updates. Note that there are separate statuses for the Transaction and the Transaction payment.

Order Status Flow
Order Status Flow
Transaction Payment Status Flow
Transaction Payment Status Flow

If a chargeback occurs, then there is a simple flow where when the customer requests a chargeback, The status is changed to Opened. If the chargeback is approved, then the status changes to Won. If not, it changes to Lost.

Chargeback Status Flow
Chargeback Status Flow

Back to Top

Webhook

A webhook is available if you wish to be notified that a status update has been entered into the Fraud.net database. An HTTP request is made to the URL of the webhook with status information, and your server can take that information and do whatever you like with it.

Register the URL you want for your webhook in the Fraud.net portal.

Back to Top

Data Backfill

Before you can make API requests, you will need to “backfill” our database by providing 6 to 12 months of cart and order data. There are two formats we accept:

  • CSV (Comma Separated Values)
  • JSONP (JSON with Padding)

Contact your Fraud.net representative for the exact format template.

Once you have created the file, your representative will provide you with a URL and credentials for an Amazon S3 Bucket. You will upload the file to that bucket.

Back to Top