API v2 Documentation

Our v2.0 API documentation (API v1.0 documentation is located here - requires login).
Our team lives by two credos: 'Data is power' and 'Simplicity whenever possible'. Everything we create focuses on providing our members with better decision-making capabilities powered by a few straightforward requests. Our data is available to members via APIs so developers can build tools to make their enterprises faster, smarter and more efficient. Merchants should connect to Fraud.net systems using 2 APIs: the 'CHECK' API is used to score the transaction immediately upon completion, and the 'UPDATE' API is used to relay any subsequent changes to each transaction. In doing so, you and Fraud.net create a real-time, learning fraud prevention platform that is capable of consistently and incrementally improving your fraud detection. Fraud.net controls access to data via an API Key, the primary data authentication method for your account. Don't have a key? Start by creating an account here.

Looking for pre-built libraries for interacting with Fraud.net? Take a look at our SDKs here.

Endpoint - Transaction Check

POST
https://api.fraud.net/v2/check

Example request (JSON)

{
"transaction": {
"type":"sale",
"order_id": "447654529",
"order_total": 238.47,
"order_currency": "USD",
"order_status" : "new order",
"order_is_digital" : "false",
"cart_token" : "967451ac-e1e3-11e4-8a00-1681e6b88ec1",
"user_id" : "1234",
"ordered_on" : "2015-01-10T11:00:00-05:00",
"shipped_on" : "2015-01-10T11:00:00-05:00",
"order_count" : 12,
"order_source" : "google",
"total_spent" : 1543.23
},
"shipping": {
"first_name": "John",
"last_name": "Doe",
"address1": "321 Harbor Road",
"address2": "Suite 4",
"company": "Acme Inc",
"city": "Kalamazoo",
"region": "MI",
"country": "US",
"postal_code": "48909",
"phone":"269-555-1212",
"email":"john.doe@gmail.com"
},
"billing": {
"first_name": "Jane",
"last_name": "Doe",
"address1": "654 Main Road",
"address2": "Apt 8c",
"company": "",
"city": "Ann Arbor",
"region": "MI",
"country": "US",
"postal_code": "48103",
"phone":"269-666-2323",
"email":"jane.doe@gmail.com"
},
"device": {
"ip_address":"215.22.33.100",
"user_agent":"User-Agent: Mozilla /5.0 (Compatible MSIE 9.0;Windows NT 6.1;WOW64; Trident/5.0)"
},
"delivery":{
"method":"standard",
"courier":"usps",
"weight":1.4
},
"payment":{
"method":"credit_card",
"type":"visa",
"bin":"408540",
"last_4":"1234",
"exp_date":"0815",
"cvv_result_code":"M",
"avs_result_code":"Y"
},
"products":[
{
"upc":"031548654544",
"product_id":"787540",
"sku": "4PF2210000010",
"brand": "Nike",
"title": "Air Zoom Pegasus 32",
"price": 218.49,
"quantity": 1
}
],
"custom": [
{
"coupon_used" : "Mother's Day Sale - 10% off!",
"customer_lifecycle" : "first time buyer"
}
]
}

Example Response (JSON)

{
"success": true,
"data" : {
"risk_group" : "low",
"risk_score" : 12.6,
"id" : "f81d4fae-7dec-11d0-a765-00a0c91e6bf6",
"link" : "https://fraud.net/transaction/f81d4fae-7dec-11d0-a765-00a0c91e6bf6",
"timer" : 300
}
}

Request Headers

Header
Allowed Values
Description
Example
Accept
application/json (for .json requests)
The MIME type for the format you want to receive a response in.
application/json
Authorization
Basic
The user credentials for accessing the API.
Basic YWRtaW46cGFzc3dvcmQ=
Content-Type
application/json (for JSON requests)
The MIME type of the request body. Use to validate and parse the request to the API.
application/json
X-Auth-Client
String
Client ID of the requesting app.
X-Auth-Token
String
Access token authorizing the app to access resources on behalf of a user.

Auth instructions

Include the ​key and​ token​ in the Authorization field of each HTTP request header, using the following syntax Basic ​key:token where key:token is base64-encoded.
Ex. Authorization: Basic YWRtaW46ZTBhMDJiMDM5NzczNWI4NzNlZGQ5NWE1ZmQ1Y2I5YmI=

Request Parameters

Category
Field_Name
Data Type
Example
Required
Comments
Option List
transaction
type
string
sale
yes
The transaction type. The login and registration types are used for non-purchase/non-payment transactions.
sale, login, registration, payment, authenticate, update
order_id
string
123456
yes
Your internal transaction ID. You can use this to locate specific transactions in our reports and email alerts.
order_total
numeric
541.21
The order or payment total.
order_currency
string
USD
The currency used for the payment, using ISO 4217 format. Default="USD".
order_status
string
pending
Your current internal order / transaction status.
new order, approved, authorized, review, purchase_order, invoiced, shipped, cancelled, returned, refunded, chargeback, fraud
order_is_digital
boolean
false
Use if sale is of virtual or downloadable goods, or for services rendered. Default=0.
0,1
cart_token
string
967451ac-e1e3-11e4-8a00-1681e6b88ec1
Unique identifier for a particular cart that is attached to a particular order.
user_id
string
1234
Your internal user ID associated with the order.
ordered_on
string
2015-01-10T11:00:00-05:00
The date and time when the order or transaction was received.
shipped_on
string
2015-01-10T11:00:00-05:00
The date and time when the order or transaction was fulfilled.
order_source
string
Google PPC
The source or marketing channel from which the transaction originated.
order_count
string
12
The total number of orders placed by the user.
total_spent
string
1543.23
The total value of orders placed by the user.
shipping
first_name
string
John
yes
First name of recipient.
last_name
string
Doe
yes
Last name of recipient.
address1
string
321 Harbor Road
yes
The street address of the recipient / shipping address.
address2
string
Apt 6
An optional additional field for the street address of the recipient / shipping address.
company
string
example
If shipping to a company, the name of the company associated with the recipient / shipping address.
city
string
Kalamazoo
yes
City of recipient / shipping address.
region
string
MI
yes
The two-letter abbreviation of the state or province of the recipient / shipping address. ISO 3156.
postal_code
string
49009
yes
Postal code (zip code) of recipient / shipping address.
country
string
US
Country of recipient / shipping address, formatted using to ISO 3156 (2 characters).
phone
string
269-555-1212
Phone number of 'recipient / 'ship to' party.
email
string
john.doe@gmail.com
Email of 'recipient / 'ship to' party.
billing
first_name
string
John
First name of billing / sending party.
last_name
string
Doe
Last name of billing / sending party.
address1
string
321 Harbor Road
The street address of the billing / sending address.
address2
string
Apt 6
An optional additional field for the street address of the billing / sending address.
company
string
example
If billing a company, the name of the company associated with the billing / sending address.
city
string
Kalamazoo
City of billing / sending party's address.
region
string
MI
The two-letter abbreviation of the state or province of the billing / sending party's address. ISO 3156.
postal_code
string
48103
Postal code (zip code) of billing / sending party.
country
string
US
Country of billing / sending party, formatted using ISO 3156-1 alpha-2 (2 characters).
phone
string
269-666-2323
Phone number of billing / sending party.
email
string
jane.doe@gmail.com
Email of billing / sending party.
device
ip_address
string
215.22.33.474
IP address of the device from which the order was placed.
user_agent
string
User-Agent: Mozilla /5.0 (Compatible MSIE 9.0;Windows NT 6.1;WOW64; Trident/5.0)
The user agent of the device's browser from which the order was placed.
delivery
delivery_method
string
standard
For physical goods retailers, the delivery method for the goods or services sold.
standard, ground, freight, 2_day, 3_day, overnight, messenger
delivery_courier
string
usps
For physical goods retailers, the ship courier you are using to deliver your package.
fedex, ups, usps, dhl, walk-in
delivery_weight
numeric
1.4
For physical goods retailers, the weight of the order, in lbs.
payment
payment_method
string
credit_card
yes
Payment method used for the transaction.
ach, apple_pay, android_pay, bill_me_later, bitcoin, cash, check, credit_card, credit, eCheck, eft, gift_card, google_wallet, masterpass, money_order, paypal, rewards_points, voucher, third_party_processor
payment_type
string
visa
If payment by credit card, the credit card network used.
visa, mc, amex, discover, diners_club
bin
string
408540
If payment by credit card, first 6 digits of the card number (BIN).
last_4
string
1234
If payment by credit card, last 4 digits of the card number.
exp_date
string
815
If payment by credit card, the expiration date of the card.
cvv_result_code
string
M
Payment gateway CVV response code for the transaction.
avs_result_code
string
Y
Payment gateway AVS response code for the transaction.
routing_number
string
123456789
For ACH and EFT transactions only, the beneficiary bank's ABA routing number.
account_number
string
1234567890
For ACH and EFT transactions only, the beneficiary's account number in MD5 hash format.
ach_return_code
string
R23
For ACH transactions only, the bank/payment gateway ACH return code.
eft_reason_code
string
S01
For EFT transactions only, the bank/payment gateway response code.
products
upc
string
65784574894
Unique product code..
product_id
string
65784574894
Unique product code..
sku
string
65784574894
Unique product code..
brand
string
Nike
The brand of the product sold.
title
string
Air Zoom Pegasus 32
The title of the product sold.
price
numeric
218.49
The price at which the product was sold.
quantity
numeric
1
The quantity of this product that was ordered.
custom
custom variables
array
"coupon":"10% Off"
Include any custom variables you think might correlate to fraud. No limit.


Response Headers

Header
Allowed Values
Description
Example
Date
An RFC 2822 date.
The date the response was sent.
Tue, 15 Nov 2011 12:45:26 GMT
Last-Modified
An RFC 2822 date.
The date the resource was last modified. Please refer to the individual resource pages for support for this header.
Tue, 15 Nov 2011 12:45:26 GMT
Content-Type
application/json (for JSON requests)
The MIME type of the response, dependent on the extension of the endpoint that was requested.
application/json
WWW-Authenticate
Basic
Indicates the authentication scheme that should be used to access the API. Sent with a 401 Unauthorized response if HTTP Basic Authentication credentials weren’t supplied.
Basic
X-Retry-After
An integer
Rate limited response, indicating the number of seconds before the quota refreshes. See the Basic Auth rate limits documentation for more information.
15
X-BC-ApiLimit-Remaining
An integer
The number of API requests remaining for the current period (rolling one hour). See the Basic Auth rate limits documentation for more information.
987
X-BC-Fn-Version
A version number
The version of Fraud.net service is running on. This header is available from versions 1.7+.
1.7

Response Codes

Every request includes an HTTP status code with the result. The status code should examined before the response. In most error cases, the response body will contain an errors JSON/XML document with more details.

Successful status codes (2xx)
200
OK
The request was successful.


Client error status codes (4xx)
400
Bad Request
The request was invalid or could not be understood by the server. Resubmitting the request will likely result in the same error.
401
Invalid Auth Token
The request was rejected due to an invalid authentication token. Please check your api key or call us to confirm use of active auth key.
404
Not Found
The resource was not found with the given identifier. The response body will explain which resource was not found.

Server error status codes (5xx)
500
Internal Server Error
TThe server encountered an error while processing your request and failed.

Response Parameters

Category
Field_Name
Data Type
Example
Comments
Options
Success
string
true
true,false
data
risk_group
string
low
This risk grouping returns one of three risk levels, often used to simplify order processing decisions in which low = approve, medium = review, high = reject.
low, medium, high
risk_score
numeric
12.6
This risk score returns a number between 1.0 and 100.0, often used to provide a more nuanced decision, in which 1=Lowest Risk and 100=Highest Risk.
id
string
f81d4fae-7dec-11d0-a765-00a0c91e6bf6
The id is Fraud.net's unique identifier for the requested transaction. Can be stored on client's system for later reference.
link
string
https://fraud.net/fraudsearch.cfm?id=f81d4fae-7dec-11d0-a765-00a0c91e6bf6
This link is the URL in your Fraud.net account which displays the full transaction detail. Can be stored on client's order administration page for further review, if necessary.
timer
numeric
286
The timer returns the response time per transaction in milliseconds.


Don't see a situation that this request / response accommodates? Let us know by sending us any field and value in your request which you believe to be relevant in your fraud prevention program and we'll incorporate it into your algorithms and analytics. Otherwise, feel free to contact to let us know how we can better help you through any customization you'd like to see. Contact us at api@fraud.net with API feedback.