External Fraud


This documentation is for translated APIs and intended only for some implementations who have upgraded from a previous version of Order Management. Verify whether your implementation uses translated APIs before making this call, as you will experience errors if your tenant is not configured to use these. If your implementation is not configured to do so, then refer to the standard API documentation instead.

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, refer to the below parameter schema that denotes the fraud type as “EXTERNAL.” This schema is the exact same as in the previous version of OMS, as the Unified Commerce platform supports backwards compatibility for the Create Order API request that this data is provided in.

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.

Note that the request body and parameter schemas for this call are the exact same as in the previous version of OMS, as the Unified Commerce platform supports backwards compatibility for this API. The only change to this request is the format of the base endpoint, as shown in the below table. Remember to provide the x-vol-tenant key for authentication in the headers.

Production URLhttps://{tenantId}-translation.mozu.com/api/v2/order/action/releaseFraud
Sandbox URLhttps://{tenantId}-translation.sandbox.mozu.com/api/v2/order/action/releaseFraud
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.