Fraud Integration Setup Guide

Overview

The Risk Assessment API receives environmental data about an order from the client. The API evaluates the data for fraudulent activity (either systematically or manually by the Radial fraud team) and sends the results to the client via a Webhooks HTTP(S) endpoint or an Advanced Message Queuing Protocol (AMQP) queue. A response code in the response message represents the action the client order management system (OMS) should take on the order (for example, cancel the order or approve the order and ship the products).

For processing asynchronous messages, Radial supports two flavors of integration: an AMQPS-based integration that uses the pull strategy and an HTTPS-based integration that uses the push strategy. Depending on the needs of your integration, you can choose to use either the push or the pull strategy. The push integration is an event callback (Webhooks) framework that notifies clients when event messages are produced in Radial's internal systems.

Each store implementation can use only one of these integration strategies, push or pull, but not both.

Life Cycle Flow

The following diagram summarizes the integration points for the Risk Assessment API:

  1. The customer submits the final order on the webstore.
  2. The Radial Device Fingerprint Javascript function collects environmental details about the customer's session.
  3. The Device Fingerprint data is sent from the customer's browser to the webstore server.
  4. The webstore server sends the order details and the Device Fingerprint data to the OMS.
  5. The OMS sends a RiskAssessmentRequest to the Risk Assessment API endpoint. The request message includes the Device Fingerprint data and other order details.

  6. The OMS receives a AckReply and the synchronous flow ends here.

  7. The Risk Assessment API evaluates the order for fraud and pushes a RiskAssessmentReply message to the Webhooks endpoint that the client/partner has setup earlier during launch configuration.

  8. Alternately, OMS can choose to pull the message from AMQP. In that scenario, Risk Assessment API evaluates the order for fraud and places a RiskAssessmentReply message on an AMQP queue.

  9. The OMS retrieves the message, processes/persists the message, and sends an acknowledgment to either AMQP Broker or Webhooks endpoint with HTTP status of 200.

Risk Assessment Integration Details

The following sections provide more details about integrating your OMS with the Risk Assessment API.

RISK_SUBMISSION and RISK_PROCESSING States

When sending an order for risk assessment, place the order in a RISK_SUBMISSION state. This state identifies those orders that are currently in transit for risk assessment by Radial. Orders that stay in this state too long (longer than 10 minutes) are possibly stuck and might require resubmission. Contact a Radial representative for corrective action.

An acknowledgment (ACK) response is received when Radial successfully receives the order. When Radial confirms the order receipt, place the order in a RISK_PROCESSING state. Orders that stay in this state too long (longer than 10 minutes) are possibly stuck and might require resubmission. Contact a Radial representative for corrective action.

Comparing orders with the RISK_SUBMISSION and RISK_PROCESSING states helps you determine which orders were acknowledged by Radial and which orders were not acknowledged. This information can help you triage issues that might arise.

ResponseCode Field

Transaction responses are asynchronous and must be either collected from an AMQP endpoint or they will be pushed to Webhooks endpoint. The ResponseCode field describes the action that must be taken on the order, usually in the client OMS.

 

ResponseCode Action
Accept Approve the order in the client OMS and release it for fulfillment.
Cancel Cancel the order in the client OMS and do not fulfill it. Use the ReasonCode and ReasonCodeDescription fields to describe the type of cancellation for reporting or customer communication.
Suspend Change the status in the client OMS to Suspended.The order was screened and placed into a manual review queue for risk assessment by an investigator. An Accept or Cancelresponse will ultimately apply.

ReasonCode Field

The ReasonCode field describes the status of the order as well as the type of cancellation for reporting or customer communication.

Reason Code

Reason Code Description

Comments

FA

Fraud Accepted

The order is approved by Radial’s Order Review Department.

FS

Fraud Suspend

The order was screened and placed into a manual review queue for risk assessment by an investigator. A final response will ultimately be provided with one of these reason codes: FA, XU, XD, XP, XR, YT.

XU

Fraud Cancelled

The Order Review Department detected fraud and canceled the order. If further details are needed, contact the Order Review Department at 1-866-415-1324.

XD

Client Directed

The order was canceled by direct request of a client, based on pre-defined lists of negative addresses, emails, or credit cards with which the client does not wish to conduct business. If further details are needed, contact the client corporate officers or personnel who maintain these lists. Do not contact the Order Review Department.

XP

Other Policy

The order was canceled due to Radial, Office of Foreign Assets Control (OFAC), and Federal Trade Commission (FTC) policy. If further details are needed, contact the Order Review Department at 1-866-415-1324.

XR

Customer Requested Order Review

The customer contacted the Order Review Department or was contacted by the Order Review Department and requested that the order be canceled.

YT

Test Order

The order was placed for testing purposes and then canceled, or the order contains information that matches our test order procedures. Examples include orders that use a test credit card, test email (such as Test@Test.com ) or a predefined test order list.
XA Payment Declined The customer's form of payment was declined by their bank. Please have the customer reach out to their bank for the reason. The customer can place the order again after the reason for the decline is resolved, for example, with accurate information or sufficient funds available.
XB Brand Protection The order was canceled based on criteria set by the client. If further details are needed, contact the client's corporate office or personnel.

Definitions

  • Order Modification: Order Modification occurs when a customer or customer service representative is able to modify the order after it has been submitted to Radial. In this scenario a new request must to be sent to Radial following the API guidelines.
  • Proxy Pickup: Proxy pickup is a type of in-store pickup order where the customer designates a third party to pick up their order. An indicator value saying this is a proxy pickup order should be sent to Radial.
  • Baby Registry/Gift Registry: If an item on the order is on a Baby Registry or Gift Registry, an indicator variable should be sent to Radial.
  • ISPU/STS: In-Store Pickup is a delivery option where the customer can pick up the item in a retail store. The shipping address on the order should be the store address. STS stands for Ship to Store. ISPU is expected to be picked up within hours. STS is actually shipped to the store, so it takes a longer time for the item to be available for the customer.
  • OLGC: Online Gift Cards, also called Virtual Gift Cards. A gift card code is emailed to the customer for immediate use. There should be a shipping email on the order that tells Radial where the gift card code is being sent.

Tips for Risk Assessment Integration

  • Mobile webstore optimization providers can occasionally manipulate the HTTP headers to streamline processing. Please ensure that the headers that are collected are the raw headers and are not manipulated by any third party.
  • Please ensure the Radial Device Fingerprint is put on the last page in the checkout process when the customer hits submit. This function gathers data that should be submitted with the Risk Assessment request.
  • Some integrators have run into an issue when building messages where both an online gift card and a physical item is purchased, and the tender is PayPal. In this scenario shipping email is still mandatory for the OLGC line item, the correct shipping method should be passed, and the second line item of a physical item must also reflect the correct address for that item.

More Information