Radial Integration | 2016

Payments, Tax & Fraud > Fraud Management Processing > Risk Order Confirmation API

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

No

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 CANCELLED
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

 

 

Copyright © 2017 Radial. All rights reserved.