Payments & Fraud

How It Works

Dashboard

This documentation site is retired and will soon be removed. Current information can be found at the new documentation portal here! Please update your bookmarks.

Radial Payments & Fraud Documentation

Risk Order Confirmation API

Overview

The Risk Assessment request message contains the information Radial needs to process the order and provide a fraud decision. After a client order management system receives the fraud decision and processes the order, the client should use the Risk Order Confirmation API to send Radial the final disposition of the order and other key information about the order.

URI Summary

Action	URI Template	URI Example	Non-URI Request	Response
POST	/v[M.m]/stores/[StoreId]/ risk/ fraud/orderConfirmation.[format]	/v1.0/stores/ABCXYZ/risk/ fraud/orderConfirmation.xml	XML	200 + XML response

Schemas

Request Examples

The request is a RiskOrderConfirmationRequest message.

Request example with all elements

<?xml version="1.0" encoding="UTF-8"?>
<RiskOrderConfirmationRequest xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
  <Order>
    <OrderId>123345459</OrderId>
    <StoreId>TMSUS</StoreId>
    <StatusDate>2016-05-19T09:30:47Z</StatusDate>
    <ConfirmationType>CREDIT ISSUED</ConfirmationType>
    <OrderStatus>IN_PROCESS</OrderStatus>
    <OrderStatusReason>a</OrderStatusReason>
    <LineDetails>
      <LineDetail>
        <SKU>a</SKU>
        <Quantity>0</Quantity>
        <ItemStatus>RETURNED</ItemStatus>
        <TrackingNumber>a</TrackingNumber>
        <ShippingVendorCode>OTHER</ShippingVendorCode>
        <DeliveryMethod>a</DeliveryMethod>
        <ShipScheduledDate>2001-12-17T09:30:47Z</ShipScheduledDate>
        <ShipActualDate>2001-12-17T09:30:47Z</ShipActualDate>
      </LineDetail>
      <LineDetail>
        <SKU>a</SKU>
        <Quantity>0</Quantity>
        <ItemStatus>PENDING</ItemStatus>
        <TrackingNumber>a</TrackingNumber>
        <ShippingVendorCode>FEDEX</ShippingVendorCode>
        <DeliveryMethod>a</DeliveryMethod>
        <ShipScheduledDate>2001-12-17T09:30:47Z</ShipScheduledDate>
        <ShipActualDate>2001-12-17T09:30:47Z</ShipActualDate>
      </LineDetail>
    </LineDetails>
    <CustomAttributesList>
      <CustomAttribute>
        <AttributeName>key1</AttributeName>
        <AttributeValue>value1</AttributeValue>
      </CustomAttribute>
      <CustomAttribute>
        <AttributeName>key2</AttributeName>
        <AttributeValue>value2</AttributeValue>
      </CustomAttribute>
    </CustomAttributesList>
  </Order>
</RiskOrderConfirmationRequest>

Request example with only mandatory elements

<?xml version="1.0" encoding="UTF-8"?>
<RiskOrderConfirmationRequest xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
  <Order>
    <OrderId>123345461</OrderId>
    <StoreId>MAGT1</StoreId>
    <StatusDate>2016-05-19T09:30:47Z</StatusDate>
    <ConfirmationType>CREDIT ISSUED</ConfirmationType>
    <OrderStatus>IN_PROCESS</OrderStatus>
  </Order>
</RiskOrderConfirmationRequest>

Request Elements

Element	Required	Description	Type	Restriction
Order	Yes	Sequence of OrderId, StoreId, StatusDate, ConfirmationType, OrderStatus, OrderStatusReason, LineDetails, CustomAttributesList	ComplexType
Order/OrderId	Yes	Store ID	String	Max 40 characters
Order/StoreId	No	Contains the store identifier which is also passed in request URI	String	Max 100 characters
Order/StatusDate	Yes	Date and time the status change occurred	dateTime	Should be in UTC
Order/ConfirmationType	Yes	One of the following actions should apply in order for the OrderConfirmation call to be made. CREDIT ISSUED -- when A credit is issued due to price adjustment, customer appeasement, or other reason. RETURN PROCESSED --- when the merchandise was returned SHIPMENT -- When items in this order are shipped whether the shipment includes all ordered items or only some of the ordered items CANCEL -- When the full or partial order was cancelled OTHER -- When there is a different reason other than the values listed above.	Enum	Should be part of the enum values CREDIT ISSUED RETURN PROCESSED SHIPMENT CANCEL OTHER
Order/OrderStatus	No	One of the below status should apply based on items statuses: IN_PROCESS -- Some items of the order are still in process. SHIPPED -- The whole order has been shipped. CANCELLED -- The whole order has been cancelled. COMPLETED -- The whole order is completed, either through being shipped or cancelled or returned items.	Enum	Should be part of the enum values IN_PROCESS SHIPPED CANCELLED COMPLETED
Order/OrderStatusReason	No	The order status reason description provides information to explain the order status.	String	Max 200 characters
Order/LineDetails	No, unbounded repetitions	Contains the line items on the order corresponding to this confirmation type or the total order items in the order with current statuses snapshot. Sequence of SKU, Quantity, ItemStatus, TrackingNumber, ShippingVendorCode, DeliveryMethod, ShipScheduledDate, ShipActualDate	ComplexType
Order/LineDetails/ SKU	Yes	A unique identifier for a distinct product. Sample Data: 13548975	String	Minimum 1 character
Order/LineDetails/ Quantity	Yes	The number of units in this item corresponding to this confirmation or package. This number doesn't need to match the total quantity for this item in the order. Should be associated with only the current status. One Item with more than 1 quantity in original order can be split into multiple lineDetails if quantity is split into different shipments. Sample Data: 3	Integer
Order/LineDetails/ ItemStatus	Yes	The current status of this item with enumerated values SHIPPED -- if this item is shipped RETURNED -- if this item is returned CANCELLED -- if this item is cancelled PENDING -- if this item is waiting for shipment either due to other review process or backordered	String	Should be part of the enum values SHIPPED RETURNED CANCELLED PENDING
Order/LineDetails/ TrackingNumber	Required if available	Tracking number associated with this package, if the item is shipped.	String	Max 64 characters
Order/LineDetails/ ShippingVendorCode	No	Alphanumeric code identifies the carrier (shipping vendor). UPS -- The carrier for this shipment is United Parcel Service. FEDEX -- The carrier for this shipment is Federal Express. USPS -- The carrier for this shipment is United States Postal Service. DHL -- The carrier for this shipment is DHL. OTHER -- The carrier for this shipment is different from the options listed above.	Enum	Should be part of the enum values UPS FEDEX USPS DHL OTHER
Order/LineDetails/ DeliveryMethod	Yes	Represents the selected delivery method (also known as shipping method). Client OMS should do a mapping at their end and provide values similar to below values STANDARD EXPRESS 1DAY 2DAY 3DAY SATURDAY INSTOREPICKUP SHIPTOSTORE EMAIL	String	Max 20 characters
Order/LineDetails/ ShipScheduledDate	No	The scheduled shipping date and time of this item in yyyy-MM-ddThh24:mm:ss format (UTC)	dateTime	Should be in UTC
Order/LineDetails/ ShipActualDate	No	The actual shipping date and time of this item in yyyy-MM-ddThh24:mm:ss format (UTC)	dateTime	Should be in UTC
Order/CustomAttributesList	No	A custom attribute in key and value pairs. These key and value pairs needs to be used if any of the information cannot be passed through above elements. For example, refunded Amount can be passed here using key RefundedAmount and value 100.00 Keys can be generated by the client as per need.	ComplexType
Order/CustomAttributesList/ CustomAttribute	No, unbounded repetitions	Complex Type with sequence of AttributeName, AttributeValue
Order/CustomAttributesList/ CustomAttribute/AttributeName	Yes	Name of the attribute, a Key in the key-value pair Can be generated by client OMS based on need	String	Max 100 characters
Order/CustomAttributesList/ CustomAttribute/AttributeValue	Yes	Value of the attribute, a Key in the key-value pair	String	Max 512 characters

Response Example

<?xml version="1.0" encoding="UTF-8"?>
<RiskOrderConfirmationReply xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
  <OrderId>1234567890</OrderId>
  <StoreId>ABCTEST</StoreId>
  <CreateTimestamp>2001-12-17T09:30:47Z</CreateTimestamp>
  <OrderConfirmationAcknowledgement>true</OrderConfirmationAcknowledgement>
</RiskOrderConfirmationReply>

Response Elements

Element	Required	Description	Type	Restriction
OrderId	Yes	Order ID	String	Max 40 characters
StoreId	Yes	Store ID for the order	String	Max 100 characters
CreateTimestamp	No	Timestamp when the response is generated	dateTime
OrderConfirmationAcknowledgement	No	It lets the requester know whether the RiskOrderConfirmationRequest was successfully processed or not. If this is false, the client OMS is supposed to resend the RiskOrderConfirmationRequest	Boolean	True or False

Integration Details

A RiskOrderConfirmationRequest API call should be made if any of the scenarios listed below occurs in the client order management system. Calls to the API should be made every time each scenario occurs. For example, if an order has three items and each was shipped separately for a total of three shipments, the result should be three API calls to RiskOrderConfirmationRequest for the order.

The client order management system can choose to send either all the items involved in order with every RiskOrderConfirmationRequest under LineDetails, or send only the items involved with that particular RiskOrderConfirmationRequest confirmation type under LineDetails element.

Below are some of the possible scenarios when RiskOrderConfirmationRequest is required, with examples of values for the different elements under the request.

Order shipped completely

In this scenario, all the items in an order are shipped. For this order, submit a RiskOrderConfirmationRequest with the following values:

RiskOrderConfirmationRequest/Order/ConfirmationType	SHIPMENT
RiskOrderConfirmationRequest/Order/OrderStatus	COMPLETED
RiskOrderConfirmationRequest/Order/LineDetails/LineDetail[]/ItemStatus	SHIPPED

Order shipped partially, some items still processing

In this scenario, some items in an order are shipped and some other items are either waiting for shipment, backordered, cancelled, or returned. For this order, submit a RiskOrderConfirmationRequest with the following values:

RiskOrderConfirmationRequest/Order/ConfirmationType	SHIPMENT
RiskOrderConfirmationRequest/Order/OrderStatus	IN_PROCESS
RiskOrderConfirmationRequest/Order/LineDetails/LineDetail[]/ItemStatus	SHIPPED and PENDING, CANCELLED, or RETURNED

Note: Items with backordered status should be sent as PENDING.

Order shipped partially, completes the order

In this scenario, some items in an order are shipped and some other items are either cancelled or returned which makes the whole order complete at this time. For this order, submit a RiskOrderConfirmationRequest with the following values:

RiskOrderConfirmationRequest/Order/ConfirmationType	SHIPMENT
RiskOrderConfirmationRequest/Order/OrderStatus	COMPLETED
RiskOrderConfirmationRequest/Order/LineDetails/LineDetail[]/ItemStatus	SHIPPED and CANCELLED or RETURNED

Order cancelled completely

In this scenario, all the items in an order are cancelled. For this order, submit a RiskOrderConfirmationRequest with the following values:

RiskOrderConfirmationRequest/Order/ConfirmationType	CANCEL
RiskOrderConfirmationRequest/Order/OrderStatus	CANCELLED
RiskOrderConfirmationRequest/Order/LineDetails/LineDetail[]/ItemStatus	CANCELLED

Order cancelled partially, some items still processing

In this scenario, some items in an order are cancelled and some other items are either waiting for shipment, backordered, or returned. For this order, submit a RiskOrderConfirmationRequest with the following values:

RiskOrderConfirmationRequest/Order/ConfirmationType	CANCEL
RiskOrderConfirmationRequest/Order/OrderStatus	IN_PROCESS
RiskOrderConfirmationRequest/Order/LineDetails/LineDetail[]/ItemStatus	CANCELLED and PENDING, CANCELLED, or RETURNED

Note: Items with backordered status should be sent as PENDING

Order cancelled partially, completes the order

In this scenario, some items in an order are cancelled and some other items are either shipped or returned which makes the whole order complete at this time. For this order, submit a RiskOrderConfirmationRequest with the following values:

RiskOrderConfirmationRequest/Order/ConfirmationType	CANCEL
RiskOrderConfirmationRequest/Order/OrderStatus	COMPLETED
RiskOrderConfirmationRequest/Order/LineDetails/LineDetail[]/ItemStatus	CANCELLED and SHIPPED or RETURNED

Return received partially and credit not issued, order is completed previously

In this scenario, items are received to warehouse and credit is still not issued to customer. All the items in order are already shipped or cancelled which makes order complete before return is received. For this order, submit a RiskOrderConfirmationRequest with the following values:

RiskOrderConfirmationRequest/Order/ConfirmationType	RETURN PROCESSED
RiskOrderConfirmationRequest/Order/OrderStatus	COMPLETED
RiskOrderConfirmationRequest/Order/LineDetails/LineDetail[]/ItemStatus	RETURNED and SHIPPED or CANCELLED

Return received partially and credit not issued, order is in process previously

In this scenario, items are received to warehouse and credit is still not issued to customer. Some of the items in an order are either backordered/waiting for shipment when return is received. For this order, submit a RiskOrderConfirmationRequest with the following values:

RiskOrderConfirmationRequest/Order/ConfirmationType	RETURN PROCESSED
RiskOrderConfirmationRequest/Order/OrderStatus	IN_PROCESS
RiskOrderConfirmationRequest/Order/LineDetails/LineDetail[]/ItemStatus	RETURNED and PENDING, SHIPPED, or CANCELLED

Note: Items with backordered status should be sent as PENDING.

Return received completely and credit not issued

In this scenario, all the items in an order are returned and credit is still not issued to customer. For this order, submit a RiskOrderConfirmationRequest with the following values:

RiskOrderConfirmationRequest/Order/ConfirmationType	RETURN PROCESSED
RiskOrderConfirmationRequest/Order/OrderStatus	COMPLETED
RiskOrderConfirmationRequest/Order/LineDetails/LineDetail[]/ItemStatus	RETURNED

Return received partially and credit issued, order is completed previously

In this scenario, credit is issued to customer for the returned items. All the items in order are already shipped or cancelled which makes order complete before return is received. For this order, submit a RiskOrderConfirmationRequest with the following values:

RiskOrderConfirmationRequest/Order/ConfirmationType	CREDIT ISSUED
RiskOrderConfirmationRequest/Order/OrderStatus	COMPLETED
RiskOrderConfirmationRequest/Order/LineDetails/LineDetail[]/ItemStatus	RETURNED and SHIPPED or CANCELLED

Note: The amount credited to customer should be listed under custom attributes with key as "RefundAmount"

Return received partially and credit issued, order is in process previously

In this scenario, credit is issued to customer for the returned items. Some of the items in an order are either backordered or waiting for shipment when return is received. For this order, submit a RiskOrderConfirmationRequest with the following values:

RiskOrderConfirmationRequest/Order/ConfirmationType	CREDIT ISSUED
RiskOrderConfirmationRequest/Order/OrderStatus	IN_PROCESS
RiskOrderConfirmationRequest/Order/LineDetails/LineDetail[]/ItemStatus	RETURNED and PENDING, SHIPPED, or CANCELLED

Note: Items with backordered status should be sent as PENDING

Return received completely and credit issued

In this scenario, credit is issued to customer for the returned items. All the items in an order are returned. For this order, submit a RiskOrderConfirmationRequest with the following values:

RiskOrderConfirmationRequest/Order/ConfirmationType	CREDIT ISSUED
RiskOrderConfirmationRequest/Order/OrderStatus	COMPLETED
RiskOrderConfirmationRequest/Order/LineDetails/LineDetail[]/ItemStatus	RETURNED

Credit Issued

In this scenario, credit is issued to customer either due to price adjustment or customer appeasement or some other reason. For this order, submit a RiskOrderConfirmationRequest with the following values:

RiskOrderConfirmationRequest/Order/ConfirmationType	CREDIT ISSUED
RiskOrderConfirmationRequest/Order/OrderStatus	Based on current order status
RiskOrderConfirmationRequest/Order/LineDetails/LineDetail[]/ItemStatus	SHIPPED, PENDING, CANCELLED, or RETURNED based on current item statuses

Return to top

What are you waiting for?