Introduction

Base URL

https://api.fraudfix.com/v1/

Welcome to the FraudFix REST API. Use this API to easily and securely submit new orders and to check on existing orders. You can always check on the status of existing orders from the online dashboard at https://dashboard.fraudfix.com/portal.

To use the FraudFix API, you must have an API key. Visit our website FraudFix.com for more information.

Authentication

FraudFix uses API keys to grant access to its API. Your API key should be included in the x-api-key header of all API requests.

Orders

Submit an Order

POST https://api.fraudfix.com/v1/orders

curl -X POST https://api.fraudfix.com/v1/orders \
  -H 'Content-Type: application/json' \
  -H 'Accept: */*' \
  -H 'x-api-key: string'

Example Request Body

{
  "orderNumber": "string",
  "siteName": "string",
  "grandTotal": "49.99",
  "orderDate": "2020-04-22T20:40:35.664Z",
  "customerId": "string",
  "billing": {
    "firstName": "string",
    "middleName": "string",
    "lastName": "string",
    "company": "string",
    "address1": "string",
    "address2": "string",
    "city": "string",
    "state": "string",
    "country": "string",
    "zip": "string",
    "eveningPhone": "string",
    "dayPhone": "string",
    "cellPhone": "string",
    "email": "string"
  },
  "shipping": {
    "firstName": "string",
    "middleName": "string",
    "lastName": "string",
    "company": "string",
    "address1": "string",
    "address2": "string",
    "city": "string",
    "state": "string",
    "country": "string",
    "zip": "string",
    "eveningPhone": "string",
    "dayPhone": "string",
    "cellPhone": "string",
    "email": "string"
  },
  "orderProducts": [
    {
      "sku": "string",
      "name": "string",
      "description": "string",
      "sellingPrice": 0,
      "qty": 0,
      "stockNumber": "string",
      "brandname": "string",
      "costPrice": 0,
      "custom1": "string",
      "custom2": "string",
      "custom3": "string",
      "custom4": "string",
      "custom5": "string"
    }
  ],
  "payments": [{
    "paymentType": "creditcard",
    "gatewayTransactionId": "string",
    "gatewayStatus": "string",
    "cavvResultCode": "string",
    "bin": "string",
    "cardType": "string",
    "lastFour": "string",
    "expiration": "string",
    "avsCode": "string",
    "cidResponse": "string",
    "eciCode": "string"
  }],
  "shippingMethod": "string",
  "shippingFee": 0,
  "referringCode": "string",
  "consumerReferral": "string",
  "cookie": "string",
  "promoCode": "string",
  "deviceFingerprintId": "string",
  "customerComments": "string",
  "mirScore": 0,
  "highRiskDeliveryMethod": true,
  "shippingDeadline": "2020-03-26",
  "custom1": 0,
  "custom2": "string",
  "custom3": "string",
  "custom4": "string",
  "custom5": "string",
  "salesRep": "string",
  "salesRepComments": "string",
  "inboundCallerId": "string",
  "outboundCallerID": "string",
  "ipAddress": "string",
  "repeatCustomer": true
}

Submit an order to our fraud engines to be analyzed and graded. The more data we have, the quicker and better an order can be verified. If you don't have the information for a non-required field you can either leave it empty or skip it altogether. If a required data field is unavailable, please contact us for a solution.

Request

POST /orders

You must include your api key in the header of the POST request. The POST /orders endpoint lets you submit a single order for analysis. A successful POST returns the Order URI in the Location header.

Body Parameters

Name	Type	Required	Description
`orderNumber`	string	true	This is the number we use for all correspondence including if we need to call the customer
`siteName`	string	true	The specic website of the transaction without prex or sux (e.g. abcdiscounts)
`grandTotal`	number	true
`orderDate`	string(date)	true	Order submission timestamp in ISO 8601 date format (e.g. 2020-04-22T20:40:35.664Z)
`customerId`	string	false	Merchant's internal account ID for the customer
`billing`	Address	true	Always required
`shipping`	Address	false*	*Required for physical orders
`orderProducts`	[Product]	true	An array of products included in this order
`payments`	[Creditcard/Paypal]	true	An array of payments. Currently, only a single payment is supported
`shippingMethod`	string	false*	For example Ground, Overnight, Fedex Ground, UPS Overnight. *Required for physical orders
`shippingFee`	number	false*	*Required for physical orders
`referringCode`	string	false	Merchant's internal referrer source code. This can be a designated number or a referring URL
`consumerReferral`	string	false	customer's entry response how they found out about the website. (e.g. friend, google, tv)
`cookie`	string	false
`promoCode`	string	false	Promotion Code
`deviceFingerprintId`	string	false
`customerComments`	string	false
`mirScore`	number	false	Merchant’s Internal Risk Score
`highRiskDeliveryMethod`	boolean	false	If merchant believes the shipping method choice to be a high risk (e.g. Overnight)
`shippingDeadline`	date	false	The date/time the order must ship out
`custom1`	number	false
`custom2`	string	false
`custom3`	string	false
`custom4`	string	false
`custom5`	string	false
`salesRep`	string	false	For phone orders this is the name or initials of the Sales Rep
`salesRepComments`	string	false
`inboundCallerId`	string	false	For phone orders
`outboundCallerID`	string	false	For phone orders
`ipAddress`	string	false	Customer's IP address. Required for internet and online chat orders only
`repeatCustomer`	boolean	false	Merchant's indicator if customer is a safe, non-problematic repeater

HTTP Response

A successful POST returns the Order URI in the Location header.

Status	Meaning
202	Accepted for processing
400	Bad request
401	Unauthorized
409	Conflict

Get an order

GET https://api.fraudfix.com/v1/orders/:orderId

curl -X GET https://api.fraudfix.com/v1/orders/{orderId} \
  -H 'Accept: */*' \
  -H 'x-api-key: string'

Example Response

{
    "siteName": "string",
    "orderNumber": "string",
    "customerId": "string",
    "status": "string",
    "timeInQueue": "string",
    "grandTotal": 49.99,
    "usaAddress": true,
    "efraudClass": "string",
    "avsCode": "string",
    "shippingMethod": "string",
    "resolvedDate": "2020-04-01T12:00:00.000Z",
    "isShippedEqualsBilled": false,
    "lastModified": "2020-04-01T12:00:00.000Z",
    "declineReason": "string",
    "scoreonly": 100
}

This endpoint retrieves the status of one specific order. The orderId is returned in the location header when you POST an order.

Request

GET /orders/{orderId}

URL Parameters

Name	Type	Required	Description
`orderId`	number	true	The orderId returned in the Location header of the POST order request.

Response Body

Name	Type	Description
`siteName`	string	The specic website of the transaction without prex or sux (e.g. abcdiscounts)
`orderNumber`	string	This is the number we use for all correspondence including if we need to call the customer
`customerId`	string	Merchant's internal account ID for the customer
`status`	string
`timeInQueue`	string
`grandTotal`	number
`usaAddress`	boolean
`efraudClass`	string
`avsCode`	string
`shippingMethod`	string
`resolvedDate`	date
`isShippedEqualsBilled`	boolean
`lastModified`	date
`declineReason`	string
`scoreonly`	number

HTTP Response

Status	Meaning
200	OK
401	Unauthorized
404	Not Found

Schemas

Address

address object

{
  "firstName": "string",
  "middleName": "string",
  "lastName": "string",
  "company": "string",
  "address1": "string",
  "address2": "string",
  "city": "string",
  "state": "string",
  "country": "string",
  "zip": "string",
  "eveningPhone": "string",
  "dayPhone": "string",
  "cellPhone": "string",
  "email": "string"
}

Properties

Name	Type	Required	Description
`firstName`	string	true
`middleName`	string	false
`lastName`	string	true
`company`	string	false
`address1`	string	true
`address2`	string	false
`city`	string	true
`state`	string	true	Two character state code (e.g. NY/NJ/CA)
`country`	string	true	Two character country code (e.g. US/CA/FR)
`zip`	string	true
`eveningPhone`	string	true
`dayPhone`	string	false
`cellPhone`	string	false
`email`	string	true

Product

product object

{
  "sku": "string",
  "name": "string",
  "description": "string",
  "sellingPrice": 0,
  "qty": 0,
  "stockNumber": "string",
  "brandname": "string",
  "costPrice": 0,
  "custom1": "string",
  "custom2": "string",
  "custom3": "string",
  "custom4": "string",
  "custom5": "string"
}

Properties

Name	Type	Required	Description
`sku`	string	true	Manufacturer's Stock Number
`name`	string	true
`description`	string	false
`sellingPrice`	number	true
`qty`	number	true	Quantity of the product ordered
`stockNumber`	string	true	Merchant's Stock Number
`brandName`	string	true
`costPrice`	number	false
`custom1`	string	false
`custom2`	string	false
`custom3`	string	false
`custom4`	string	false
`custom5`	string	false

Credit Card Payment

crediCardPayment object

{
  "paymentType": "creditcard",
  "gatewayTransactionId": "string",
  "gatewayStatus": "string",
  "cavvResultCode": "string",
  "bin": "string",
  "lastFour": "string",
  "cardType": "string",
  "expiration": "string",
  "avsCode": "string",
  "cidResponse": "string",
  "eciCode": "string",
  "fraudFree":"boolean"
}

Properties

Name	Type	Required	Description
`paymentType`	string	true	`creditcard`
`gatewayTransactionId`	string	false
`gatewayStatus`	string	false	One of: `approved`, `declined`, `timeout`
`cavvResultCode`	string	false
`bin`	string	true	Bank Identication Number. The first 6 numbers of the credit card number.
`lastFour`	string	true	Last four digits of the credit card number.
`cardType`	string	false	Example: `visa`, `mastercard`, `discover`, `amex`
`expiration`	string	false	e.g. `05/12` or `0512`
`avsCode`	string	true	Return code from Address Verification System.
`cidResponse`	string	true	cvv2 response code. Visa's standard codes or Y/N.
`eciCode`	string	false	Two digit Electronic Commerce Indicator Code. Used for 3D secure transactions. (e.g. 06, 02, 05)
`fraudFree`	boolean	false

Paypal Payment

paypalPayment object

{
    "paymentType": "paypal",
    "payerEmail": "string",
    "payerStatus": "string",
    "paymentStatus": "string",
    "protectionEligible": "string"
}

Properties

Name	Type	Required	Description
`paymentType`	string	true	`paypal`
`payerEmail`	string	true
`payerStatus`	string	true	Use `Y` or `N` if payer_status=VERIFIED/UNVERIFIED
`paymentStatus`	string	false
`protectionEligible`	string	false	`eligible` or `ineligible`. Leave this field empty for digital goods.

Testing

In order to facilitate testing and development we have enabled certain combinations of order totals and order numbers to override normal verification processes and return a predetermined response. When a transaction is submitted with an order number beginning with "TEST-" and one of the following values in the grandTotal field, the response will be as indicated here:

denomination	response	description
$0.11	scoreonly	For “ScoreOnly” transactions. FraudFix would display a score only, without an approval/decline decision
$0.12	n/a	deprecated
$0.13	allowed	Approved, insured and backed by our Fraud Chargeback guarantee
$0.14	rejected	Transactions that are denied insurance. FraudFix could not confirm them as FRAUD and suggests further review
$0.15	fraud	Probable - FraudFix believes the transaction to be FRAUD
$0.16	fraud	Missed - FraudFix was notified after approving an order that it was FRAUD
$0.17	cancelled	The customer or merchant requested cancellation of the transaction
$0.18	safe	For FraudFix SAFE Submissions (not guaranteed). We believe the transaction is safe to process
$0.19	review	For FraudFix SAFE Submissions. We believe the transaction is not safe to process without further review

Questions and feedback

We always appreciate hearing from our users. You can send us an email with questions or feedback at any time.