External Fraud

OMS can be integrated with an “external” fraud system if an implementation prefers to use their own instead of the cartridges already supported by OMS. This is achieved by indicating the external fraud type in the Create Order API call and then defining the fraud score and state of the order.

This guide includes an example of how to select external fraud when creating an order, as well as releasing an order from fraud through an OMS API. If the order is rejected by the fraud system, then use the Cancel Order API to cancel the order instead of processing it further.

Create Order Fraud Data

There are several ways to build fraud data in the Create Order call, based on the fraud system being used. To use an external system, always set “EXTERNAL” as the fraudType parameter. See the full schema of the createOrder/fraudData object here.

The following parameters are required for external fraud.

fraudTypeenumThe fraud system used to determine the order’s fraud ("EXTERNAL").
fraudScorenumberThe order’s fraud score.
fraudStatestringThe order’s final fraud state ("ACCEPTED", "REVIEW").

These parameters are optional for an external fraud object:

fraudFactorsarrayThe fraud rules/decisions triggered that resulted in this order’s fraudScore.
fraudTransactionIDstringAn identifier used to associate this order with the fraud system. The maximum length is 200.

Fraud Scores

There are two scores used to advise an order’s next step:

  • REVIEW: The order has fraud potential and should move into Payment Hold (Fraud Review).
  • ACCEPT: The order does not have fraud potential and should proceed with fulfillment.

If the fraud system that the client is using does not have a fraudScore, then set the value as “0”.


An example of a fraudData object that would be populated in the Create Order call:


Releasing from Fraud

Once the external system has determined whether the order should be released from fraud or canceled, OMS APIs can be used to perform both of those actions. Releasing an order involves a POST request made to the releaseFraud action of the Order API, per the below endpoint.

Supported FormatsJSON

To release an order, the manufacturerID is required and either the orderID or externalOrderID must be passed as well. You must pass in the rectifyOrder parameter as true, or else the order will not be able to come out of Payment Hold.

orderIDintegerA unique identifier for the order. The minimum value is "1".
externalOrderIDstringClient-generated unique identifier for the order sent to Kibo. The minimum length is 1 and the maximum length is 100.
manufacturerIDintegerA unique identifier for the manufacturer. The minimum value is "1".
notifyFraudEnginebooleanWhether or not to notify the fraud engine.
rectifyOrderbooleanWhether the order should be placed into the READY status when released from fraud.

This is the entire request that will release the order from fraud.

 "rectifyOrder": true

Canceling the Order

Refer to the Cancel Order API for instructions on how to cancel an order that has been rejected for fraud. In this case, the call will be the same as any other Cancel Order request.

ProductOMS Dev: External Fraud