Risk Assessment API

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 depending on how the client was set up during launch. 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 product(s) to customer).

URI Summary

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

Schemas

Request Examples

The request is a RiskAssessmentRequest message.

Request Elements

Element

Required by Schema

Required by Business Case

Description

Type

Restriction

Order

Yes

Yes

Sequence of OrderId, PromoCode, CustomerList, ShippingList, LineItems, ExternalRiskResults, ShoppingSession, TotalCost

ComplexType

 

Order/OrderId

Yes

Yes

Order ID

String

At least 1 character, Max 20 characters

Order/PromoCode

No

Yes - If a promo is used on the order this needs to be passed to Radial.

Code used to indicate reduced cost based on a promotional offer. Can be a comma delimited list of promo codes.

String

 

Order/OriginalOrderId

No

Yes - These fields are required if the order was modified after it was placed and modification is being sent to Radial. See Definitions section for detailed explanation of Order Modification.

Original Order number/ID. This field must be valued when the order has been modified and the Order/OrderId is order ID of modified order.

String

At least 1 character, Max 20 characters

Order/WebOrderId

No

Yes - These fields are required if the order was modified after it was placed and modification is being sent to Radial. See Definitions section for detailed explanation of Order Modification.

Web Order number/ID known to customer when the order is placed, if it is different from Order/OrderId field.

String

At least 1 character, Max 20 characters

Order/ReferenceOrderId

No

Yes - These fields are required if the order was modified after it was placed and modification is being sent to Radial. See Definitions section for detailed explanation of Order Modification.

Reference Order number/ID. This field is for future use, for a reference order ID related to Order/OrderId field.

String

At least 1 character, Max 20 characters

Order/OrderCategory

No

Yes - These fields are required if the order was modified after it was placed and modification is being sent to Radial. See Definitions section for detailed explanation of Order Modification.

String to explain what kind of order it is. If the order is modified, it should have a value of MODIFIED.

String

At least 1 character

Order/OrderModifiedBy

No

Yes - These fields are required if the order was modified after it was placed and modification is being sent to Radial. See Definitions section for detailed explanation of Order Modification.

The name or ID of the person who modified the order. It could be the customer, customer service agent, or someone else.

String

At least 1 character, Max 256 characters

Order/CustomerList

Yes

Yes

Sequence of Customer. This section should only consist of Shipping customer information about the order and no billing customer information should be passed in this element. ForrOfPayment section is used for Billing information.

In case of multiple shipping addresses create multiple customers in this section each with its address.

ComplexType

 

Order/CustomerList/Customer

No, unbounded repetitions

No, unbounded repetitions

Shipping customer information should be passed in this section.

Sequence of PersonName, Email, Telephone, Address, MemberLoggedIn, CustLoyalty, CurrencyCode

ComplexType

 

Order/CustomerList/Customer/ CustomerId

No

Yes – If there is no shipping address available due to it being a digital order delivery then this field is mandatory.

When shipping address is not available for digital orders then this Id should be passed to reference the customer to the shipment that will help tie customer and shipment together.

ComplexType

 

Order/CustomerList/Customer/ PersonName

No

No

Name of the customer where order is being physically/digitally shipped. Sequence of Honorific, LastName, MiddleName, FirstName, Suffix

ComplexType

 

Order/CustomerList/Customer/ PersonName/Honorific

No

No

Shipping Customer’s title (for example, Dr., Mr., Ms.)

String

 

Order/CustomerList/Customer/ PersonName/LastName

Yes

Yes

Shipping Customer’s last name

String

Max 50 characters

Order/CustomerList/Customer/ PersonName/MiddleName

No

No

Shipping Customer’s middle name

String

Max 10 characters

Order/CustomerList/Customer/ PersonName/FirstName

Yes

Yes

Shipping Customer’s first name

String

Max 50 characters

Order/CustomerList/Customer/ PersonName/Suffix

No

No

Shipping Customer’s name suffix (for example, Jr.)

String

Max 20 characters

Order/CustomerList/Customer/ Email

No, unbounded repetitions

Yes- Mandatory for Digitally shipping orders.

Shipping Customer’s email address

String

At least 1 character, Max 256 characters

Order/CustomerList/Customer/ Telephone

No, unbounded repetitions

Yes – Mandatory for orders being delivered by SMS/Phone.

Sequence of Number, TelephoneLocation

ComplexType

 

Order/CustomerList/Customer/ Telephone/Number

Yes

Yes – Mandatory for orders being delivered by SMS/Phone.

Shipping Customer’s telephone number. Formats like (480) 555-1212, 4805551212, and 01-4805551212 are accepted, with the last example being preferred.

String

At least 1 character

Order/CustomerList/Customer/ Telephone/TelephoneLocation

No

No

Shipping Customer’s telephone location

String

Primary Home Work Mobile Fax

Order/CustomerList/Customer/ Address

No, unbounded repetitions

Yes – If the order has physical shipping address(es) then it should be passed in this section.

Shipping Customer’s address. No shipping address should be present in case of digital delivery and CustomerId element above should be used to tie customer and shipment together.

Sequence of Line1, Line2, Line3, Line4, BuildingName, PoBox, City, MainDivision, CountryName, CountryCode, PostalCode

ComplexType

 

Order/CustomerList/Customer/ Address/@AddressId

Yes

Yes – Required if physical shipping address is available on the order.

Unique shipping address ID. This ID is used to tie this address and shipment so that we know that to which address is the shipment happening.

String

Attribute element; at least 1 character

Order/CustomerList/Customer/ Address/Line1

Yes

Yes – Required if physical shipping address is available on the order.

Shipping Address line 1

String

Max 100 characters

Order/CustomerList/Customer/ Address/Line2

No

No

Shipping Address line 2

String

Max 100 characters

Order/CustomerList/Customer/ Address/Line3

No

No

Shipping Address line 3

String

Max 100 characters

Order/CustomerList/Customer/ Address/Line4

No

No

Shipping Address line 4

String

Max 100 characters

Order/CustomerList/Customer/ Address/BuildingName

No

No

Building name. Normally should be provided in an address line.

String

 

Order/CustomerList/Customer/ Address/PoBox

No

No

PO box number. Normally should be provided in an address line.

String

 

Order/CustomerList/Customer/ Address/City

Yes

Yes

Shipping City

String

 

Order/CustomerList/Customer/ Address/MainDivision

No

No

Shipping Main division, state, or province code

String

At least 1 character

Order/CustomerList/Customer/ Address/CountryName

No

No

Shipping Country name

String

 

Order/CustomerList/Customer/ Address/CountryCode

Yes

Yes

Shipping Country code

String

 

Order/CustomerList/Customer/ Address/PostalCode

No

No

Shipping Postal code

String

At least 1 character

Order/CustomerList/Customer/ MemberLoggedIn

Yes

Yes

Flag that indicates whether the customer was logged In when the order was placed. Can only be set to true for one Customer element in CustomerList.

Boolean

True or False

Order/CustomerList/Customer/ CustLoyalty

No

Yes - If any of these fields are available they need to be passed to aid in the risk assessment.

Sequence of TotalPoints, Status, SignupDate, Remark, ProgramID, MembershipID, UserId, LoyalLevel, ExpireDate, EffectiveDate, CurrentPoints, VendorCode, ClubStatus, MemberLoggedIn, LastLogin, UserTenure, UserPassword, FailedLoginAttempts

ComplexType

 

Order/CustomerList/Customer/ CustLoyalty/TotalPoints

No

Yes - If any of these fields are available they need to be passed to aid in the risk assessment.

Lifetime points earned in the customer loyalty program

Long

 

Order/CustomerList/Customer/ CustLoyalty/Status

No

Yes - If any of these fields are available they need to be passed to aid in the risk assessment.

Status of the customer loyalty account (for example, Active)

String

At least 1 character

Order/CustomerList/Customer/ CustLoyalty/SignupDate

No

Yes - If any of these fields are available they need to be passed to aid in the risk assessment.

Enrollment date in the customer loyalty program

Date

 

Order/CustomerList/Customer/ CustLoyalty/Remark

No

Yes - If any of these fields are available they need to be passed to aid in the risk assessment.

Remarks for the customer loyalty program

String

At least 1 character

Order/CustomerList/Customer/ CustLoyalty/ProgramID

No

Yes - If any of these fields are available they need to be passed to aid in the risk assessment.

Name of the customer loyalty program

String

At least 1 character

Order/CustomerList/Customer/ CustLoyalty/MembershipID

Yes

Yes - If any of these fields are available they need to be passed to aid in the risk assessment.

Membership ID in the customer loyalty program

String

At least 1 character

Order/CustomerList/Customer/ CustLoyalty/UserId

No

Yes - If any of these fields are available they need to be passed to aid in the risk assessment.

Customer's login user name for the customer loyalty program

String

At least 1 character

Order/CustomerList/Customer/ CustLoyalty/LoyalLevel

No

Yes - If any of these fields are available they need to be passed to aid in the risk assessment.

Code that indicates elite status in customer loyalty program

String

At least 1 character

Order/CustomerList/Customer/ CustLoyalty/ExpireDate

No

Yes - If any of these fields are available they need to be passed to aid in the risk assessment.

Date when the customer loyalty program for this customer will be deactivated

Date

 

Order/CustomerList/Customer/ CustLoyalty/EffectiveDate

No

Yes - If any of these fields are available they need to be passed to aid in the risk assessment.

Date when the customer loyalty program for this customer was initiated

Date

 

Order/CustomerList/Customer/ CustLoyalty/CurrentPoints

No

Yes - If any of these fields are available they need to be passed to aid in the risk assessment.

Current points balance in the customer loyalty account

Long

 

Order/CustomerList/Customer/ CustLoyalty/VendorCode

No

Yes - If any of these fields are available they need to be passed to aid in the risk assessment.

Provider of the customer loyalty program

String

At least 1 character

Order/CustomerList/Customer/ CustLoyalty/ClubStatus

No

Yes - If any of these fields are available they need to be passed to aid in the risk assessment.

Club status in the customer loyalty program

String

At least 1 character

Order/CustomerList/Customer/ CustLoyalty/MemberLoggedIn

Yes

Yes - If any of these fields are available they need to be passed to aid in the risk assessment.

Flag that indicates whether the customer was logged in during the transaction. Can only be set to true for one Customer element in CustomerList.

Boolean

True or False

Order/CustomerList/Customer/ CustLoyalty/LastLogin

No

Yes - If any of these fields are available they need to be passed to aid in the risk assessment.

Date of the customer's last login

DateTime

 

Order/CustomerList/Customer/ CustLoyalty/UserTenure

No

Yes - If any of these fields are available they need to be passed to aid in the risk assessment.

Number of days the customer has had a customer loyalty account

Float

 

Order/CustomerList/Customer/ CustLoyalty/UserPassword

No

Yes - If any of these fields are available they need to be passed to aid in the risk assessment.

Customer's hashed password (SHA1 algorithm is preferred)

String

At least 1 character

Order/CustomerList/Customer/ CustLoyalty/FailedLoginAttempts

No

Yes - If any of these fields are available they need to be passed to aid in the risk assessment.

Number of failed login attempts for this customer loyalty account

Integer

 

Order/CustomerList/Customer/ CurrencyCode

Yes

Yes

Type of currency used for the Order Payment.

String

3-character ISO 4217 code (for example, USD, CAD, EUR). See http://en.wikipedia.org/ wiki/ISO_4217.

Order/ShippingList

No

Yes – If there is any physical or digital shipment then this section is mandatory.

This section contains one or multiple shipping methods and their costs associated with the order.

 

Sequence of Shipment

ComplexType

 

Order/ShippingList/Shipment

No, unbounded repetitions

Yes – If there is any physical or digital shipment then this section is mandatory.

This section contains information for each shipment method.

 

Sequence of CostTotals, ShippingMethod

ComplexType

 

Order/ShippingList/Shipment/ @AddressId

Yes

Yes

ID of the address in the customer section where this shipment is being shipped.

OR

CustomerId element value in the customer section to which this shipment is tied.

String

At least 1 character

Order/ShippingList/Shipment/ @ShipmentId

Yes

Yes

Unique ID for the shipment

String

At least 1 character

Order/ShippingList/Shipment/ CostTotals

No

No

This section contains cost of the shipping method to the order.

Sequence of AmountBeforeTax, AmountAfterTax

ComplexType

 

Order/ShippingList/Shipment/ CostTotals/AmountBeforeTax

No

No

Cost of the shipment before tax

Decimal

Minimum of 0, 2 decimal places

Order/ShippingList/Shipment/ CostTotals/AmountBeforeTax/ @CurrencyCode

Yes – If Shipment Amount before tax is available

Yes – If Shipment Amount before tax is available.

Type of currency used for the before-tax cost

String

3-character ISO 4217 code (for example, USD, CAD, EUR). See http://en.wikipedia.org/ wiki/ISO_4217.

Order/ShippingList/Shipment/ CostTotals/AmountAfterTax

Yes

Yes

Cost of the shipment after tax

Decimal

Minimum of 0, 2 decimal places

Order/ShippingList/Shipment/ CostTotals/AmountAfterTax/ @CurrencyCode

Yes

Yes

Type of currency used for the after-tax cost

String

Attribute element; 3-character ISO 4217 code (for example, USD, CAD, EUR). See http://en.wikipedia.org/ wiki/ISO_4217.

Order/ShippingList/Shipment/ ShippingMethod

Yes

Yes - New shipment methods need to be communicated to Radial so they can be mapped for effective risk assessment.

Shipment method name for the order

String

At least 1 character

Order/LineItems

No

Yes

Information about each line item purchased on the order.

Sequence of LineItem

ComplexType

 

Order/LineItems/LineItem

No, unbounded repetitions

Yes, unbounded repetitions

Sequence of LineTotalAmount, UnitCostAmount, Quantity, ProductName, ProductDescription, UnitWeight, ProductCategory, PromoCode, ItemId

ComplexType

 

Order/LineItems/LineItem/ @LineItemId

Yes

Yes

Unique ID for a line item

String

Attribute element; max 20 characters

Order/LineItems/LineItem/ @ShipmentId

Yes

Yes

Shipment ID from one of the shipment elements in Order/ShippingList.

This indicates that which line item is using which shipping method and is shipping to which address.

String

Attribute element; at least 1 character

Order/LineItems/LineItem/ LineTotalAmount

Yes

Yes

Total cost of the line item

Decimal

Minimum of 0, 2 decimal places

Order/LineItems/LineItem/ LineTotalAmount/ @CurrencyCode

Yes

Yes

Type of currency used for the total cost

String

Attribute element; 3-character ISO 4217 code (for example, USD, CAD, EUR). See http://en.wikipedia.org/ wiki/ISO_4217.

Order/LineItems/LineItem/ UnitCostAmount

No

Yes - Required if available

Unit cost of single quantity of line item

Decimal

Minimum of 0, 2 decimal places

Order/LineItems/LineItem/ UnitCostAmount/ @CurrencyCode

Yes

Yes

Type of currency used for the unit cost

String

Attribute element; 3-character ISO 4217 code (for example, USD, CAD, EUR). See http://en.wikipedia.org/ wiki/ISO_4217.

Order/LineItems/LineItem/ Quantity

Yes

Yes

Number of units ordered

Int

 

Order/LineItems/LineItem/ ProductName

No

Yes - Required if available

Product name

String

At least 1 character

Order/LineItems/LineItem/ ProductDescription

No

Yes - Required if available

Product description

String

At least 1 character

Order/LineItems/LineItem/ UnitWeight

No

No

Unit weight of the line item

Float

 

Order/LineItems/LineItem/ UnitWeight/@unit

No

No

Weight unit

String

Attribute element:

pound ounce kilogram gram unknown

Order/LineItems/LineItem/ ProductCategory

No

Yes - Required if available

Class of product to which the line item belongs

String

At least 1 character

Order/LineItems/LineItem/ PromoCode

No

Yes - Required if available at the LineItem level

Code that indicates whether the purchase was related to a promotional campaign

String

At least 1 character

Order/LineItems/LineItem/ ItemId

No

No

Unique identifier for a distinct product

String

Max 20 characters

Order/ExternalRiskResults

No

No

Sequence of ExternalRiskResult

ComplexType

 

Order/ExternalRiskResults/ ExternalRiskResult

No, unbounded repetitions

No, unbounded repetitions

This section contains information of secondary risk assessment, if done, outside of Radial

Sequence of Score, Code, Source

ComplexType

 

Order/ExternalRiskResults/ ExternalRiskResult/Score

No

Yes - If a secondary risk assessment is performed outside of Radial, please pass that result here.

External risk score

Decimal

 

Order/ExternalRiskResults/ ExternalRiskResult/Code

No

Yes - If a secondary risk assessment is performed outside of Radial, please pass that result here.

External risk code

String

At least 1 character

Order/ExternalRiskResults/ ExternalRiskResult/Source

No

Yes - If a secondary risk assessment is performed outside of Radial, please pass that result here.

Source of the external risk code and/or score

String

At least 1 character

Order/ShoppingSession

No

No

Information related to shopping session of the customer.

Sequence of TimeOnSite, ReturnCustomer, ItemsRemoved

ComplexType

 

Order/ShoppingSession/ TimeOnSite

No

Yes - Required if available

Total time, in minutes, spent by customer for the shopping session.

Double

 

Order/ShoppingSession/ ReturnCustomer

No

Yes - Required if available

Flag that indicates whether the shopper is a return customer

Boolean

True or False

Order/ShoppingSession/ ItemsRemoved

No

Yes - Required

Flag that indicates whether items were added to the order/cart and then subsequently removed

Boolean

True or False

Order/TotalCost

No

Yes - Required

Payment/Billing information about the order.

Sequence of FormOfPayment, CostTotals, FailedCc

Boolean

True or False

Order/TotalCost/ FormOfPayment

Yes, unbounded repetitions

Yes, unbounded repetitions

For each payment method only one FormOfPayment section should be used. In case of order with multiple payment methods or split tender, xml should contain multiple FormOfPayment section.

Sequence of PaymentCard, Authorization, Email, PersonName, Address, Telephone, TransactionResponses, PaymentTransactionDate, PaymentTransactionTypeCode, PaymentTransactionID, ItemListRPH, Amount, AccountID, TenderClass

ComplexType

 

Order/TotalCost/ FormOfPayment/ PaymentCard

No

Yes – Required in case of CreditCard, PayPal and Digital Wallets.

This section contains credit card, PayPal or Digital Wallet related information. No need to set PaymentCard section in case Gift card is used as payment method.

Sequence of CardHolderName, PaymentAccountUniqueId, ExpireDate, CardType

ComplexType

 

Order/TotalCost/ FormOfPayment/ PaymentCard/ CardHolderName

Yes

Yes

Name of the credit card holder as it appears on the credit card

String

Max 100 characters

Order/TotalCost/ FormOfPayment/ PaymentCard/ PaymentAccountUniqueId/ @isToken

Yes

Yes

If you are using Radial Payments service or Radial Tokenization, then this attribute’s value will be ‘true’ else it will be ‘false’.

Flag indicates whether PaymentAccountUniqueId is a Radial token or an actual account number.

Boolean

Attribute element:True or False

Order/TotalCost/ FormOfPayment/ PaymentCard/ PaymentAccountUniqueId

Yes

Yes

Tokenized Credit card account number.

In case of PayPal, please pass the PayPal Payer ID. If Payer Id is not available in case of PayPal, then pass the value as “PAYPAL” in this field.

String

Max 22 characters

Order/TotalCost/ FormOfPayment/ PaymentCard/ExpireDate

No

Yes - Required if CC transaction and Expiration date exists.

Credit card expiration date

GYearMonth

 

Order/TotalCost/ FormOfPayment/ PaymentCard/OrderAppId

No

Yes - This is a required field if client is using Radial Payment Service.

This value is only required if Radial Payments is used.

OrderAppId is combination of storeID provided during launch and value ‘eb2c’. The format looks like below:

[storeID]-eb2c

String

At least 1 character, Max 40 characters

Order/TotalCost/ FormOfPayment/ PaymentCard/PaymentSessionId

No

Yes - This is a required field if client is using Radial Payment Service.

This value is only required if Radial Payments is used.

 

PaymentSessionId is equivalent to the value passed in payments auth response field ‘PaymentContext/OrderId’.

String

At least 1 character, Max 40 characters

Order/TotalCost/ FormOfPayment/ PaymentCard/GatewayKey

No

No

This should be the same gateway key generated by payment service when the initial auth call happened when placing order. This identifier typically ties payment transactions to an order.

String

At least 1 character, Max 40 characters

Order/TotalCost/ FormOfPayment/ PaymentCard/CardType

No

Yes - Required if a Credit Card, PayPal and Digital Wallet payment method.

2-character Payment method type used for the order (for example, Visa, American Express, Diners Club, MasterCard, any private label). Values for this element can be used from Tender Type code at https://docs.radial.com/ptf/Content/Topics/payments/tender-types.htm

String

At least 1 character

Order/TotalCost/ FormOfPayment/ Authorization

No

No

Bank Authorization information for credit card transaction.

Sequence of Decline, Code

ComplexType

 

Order/TotalCost/ FormOfPayment/ Authorization/Decline

Yes

Yes

Flag that indicates whether this was a declined credit card authorization

Boolean

True or False

Order/TotalCost/ FormOfPayment/ Authorization/Code

No

No

Bank Authorization code for the credit card transaction

String

At least 1 character

Order/TotalCost/ FormOfPayment/Email

No, unbounded repetitions

Yes - Required if available. Also known as Billing Email Address. Should be available on the majority of transactions.

Billing Email address associated with the form of payment

String

At least 1 character, Max 256 characters

Order/TotalCost/ FormOfPayment/ PersonName

No

No

Billing Name associated with the form of payment. Sequence of Honorific, LastName, MiddleName, FirstName, Suffix

ComplexType

 

Order/TotalCost/ FormOfPayment/ PersonName/Honorific

No

No

Billing Person's title (for example, Dr., Mr., Ms.)

String

 

Order/TotalCost/ FormOfPayment/ PersonName/LastName

Yes

Yes

Billing Person's last name

String

Max 50 characters

Order/TotalCost/ FormOfPayment/ PersonName/MiddleName

No

No

Billing Person's middle name

String

Max 10 characters

Order/TotalCost/ FormOfPayment/ PersonName/FirstName

Yes

Yes

Billing Person's first name

String

Max 50 characters

Order/TotalCost/ FormOfPayment/ PersonName/Suffix

No

No

Billing Person's name suffix (for example, Jr.)

String

Max 20 characters

Order/TotalCost/ FormOfPayment/Address

No, unbounded repetitions

No, unbounded repetitions

Billing address associated with the form of payment. Sequence of Line1, Line2, Line3, Line4, BuildingName, PoBox, City, MainDivision, CountryName, CountryCode, PostalCode

ComplexType

 

Order/TotalCost/ FormOfPayment/Address/ @AddressId

Yes

Yes

Unique address identifier assigned to Billing address

String

Attribute element; at least 1 character

Order/TotalCost/ FormOfPayment/Address/ Line1

Yes

Yes

Billing Address line 1

String

Max 100 characters

Order/TotalCost/ FormOfPayment/Address/ Line2

No

No

Billing Address line 2

String

Max 100 characters

Order/TotalCost/ FormOfPayment/ Address/Line3

No

No

Billing Address line 3

String

Max 100 characters

Order/TotalCost/ FormOfPayment/ Address/Line4

No

No

Billing Address line 4

String

Max 100 characters

Order/TotalCost/ FormOfPayment/ Address/BuildingName

No

No

Building name.

String

 

Order/TotalCost/ FormOfPayment/ Address/PoBox

No

No

PO box number.

String

 

Order/TotalCost/ FormOfPayment/ Address/City

Yes

Yes

Billing City

String

 

Order/TotalCost/ FormOfPayment/ Address/MainDivision

No

No

Billing Main division, state, or province code

String

At least 1 character

Order/TotalCost/ FormOfPayment/ Address/CountryName

No

No

Country name

String

 

Order/TotalCost/ FormOfPayment/ Address/CountryCode

Yes

Yes

Country code

String

 

Order/TotalCost/ FormOfPayment/ Address/PostalCode

No

Yes - Required if available

PostalCode

String

At least 1 character

Order/TotalCost/ FormOfPayment/ Telephone

No, unbounded repetitions

No, unbounded repetitions

Billing Telephone number

Sequence of Number, TelephoneLocation

ComplexType

 

Order/TotalCost/ FormOfPayment/ Telephone/Number

Yes

Yes

Billing Telephone number. Formats like (480) 555-1212, 4805551212, and 01-4805551212 are all accepted, with the last example being preferred.

String

At least 1 character

Order/TotalCost/ FormOfPayment/ Telephone/TelephoneLocation

No

No

Telephone location

String

Primary Home Work Mobile Fax

Order/TotalCost/ FormOfPayment/ TransactionResponses

No

No

This section should contain additional information received from Payment Authorization response. Like Address Validation response codes for credit card transactions, PayPal Address and Id verification responses and additional Amex validations.

Sequence of TransactionResponse

ComplexType

 

Order/TotalCost/ FormOfPayment/ TransactionResponses/ TransactionResponse

No, unbounded repetitions

Yes, if credit card transaction both AVS and CSC are required. If available, 3DS response is also required.

Transaction response code received in Payment Authorization response:

1)        Credit card: Value for AVSResponseCode, CVV2ResponseCode

2)        PayPal: Value for PayerStatus and AddressStatus

3)       Amex additional codes: Values for PhoneResponseCode, NameResponseCode, EmailResponseCode

String

 

Order/TotalCost/ FormOfPayment/ TransactionResponses/ TransactionResponse/ @ResponseType

Yes

Yes

ResponseType codes varies by tender. Example values:

·         CC: avs, csc

·         3DS Enabled: 3ds

·         PayPal: PayPalPayer, PayPalAddress

·         Amex: AmexPhone, AmexEmail, AmexZip

String

 

Order/TotalCost/ FormOfPayment/ PaymentTransactionDate

Yes

Yes

Timestamp of the Payment transaction

DateTime

 

Order/TotalCost/ FormOfPayment/ PaymentTransactionTypeCode

Yes

Yes

2-character Payment method type used for the order (for example, Visa, American Express, Diners Club, MasterCard, any private label). Values for this element can be used from Tender Type code at https://docs.radial.com/ptf/Content/Topics/payments/tender-types.htm

If the gift card is used as a payment method please pass value as ‘TS’.

String

At least 1 character

Order/TotalCost/ FormOfPayment/ PaymentTransactionID

No

No

Transaction ID for the payment

String

At least 1 character

Order/TotalCost/ FormOfPayment/ ItemListRPH

No

No

LineItemIds from Order/LineItems that this form of payment paid for. This is the full set of LineItemIds, separated by spaces.

String

At least 1 character

Order/TotalCost/ FormOfPayment/Amount

Yes

Yes

Amount for this form of payment

Decimal

Minimum of 0, 2 decimal places

Order/TotalCost/ FormOfPayment/Amount/ @CurrencyCode

Yes

Yes

Type of currency used for this form of payment

String

Attribute element; 3-character ISO 4217 code (for example, USD, CAD, EUR). See http://en.wikipedia.org/ wiki/ISO_4217.

Order/TotalCost/ FormOfPayment/AccountID

No

Yes - Required if available

Tokenized Credit card account number.

In case of PayPal, please pass the PayPal Payer ID. If Payer Id is not available in case of PayPal, then pass the value as “PAYPAL” in this field.

For purchases done via Gift cards, please pass gift card number itself.

String

Max 22 characters

Order/TotalCost/ FormOfPayment/AccountID/ @isToken

Yes

Yes

If you are using Radial Payments service or Radial Tokenization, then this attribute’s value will be ‘true’ else it will be ‘false’.

Flag indicates whether AccountID is a Radial token or an actual account number.

Boolean

Attribute element: True or False

Order/TotalCost/ FormOfPayment/TenderClass

Yes

Yes

Tender category/class

For PayPal value for this field will be ‘Other’.

For purchases done via GiftCard value for this field will be ‘StoredValue’

String

CreditCard StoredValue Other

Order/TotalCost/CostTotals

Yes

Yes

Total cost for the order.

Sequence of AmountBeforeTax, AmountAfterTax

ComplexType

 

Order/TotalCost/CostTotals/ AmountBeforeTax

No

No

Total cost of the order before tax

Decimal

Minimum of 0, 2 decimal places

Order/TotalCost/CostTotals/ AmountBeforeTax/ @CurrencyCode

Yes

Yes

Type of currency used for the total before-tax cost

String

Attribute element; 3-character ISO 4217 code (for example, USD, CAD, EUR). See http://en.wikipedia.org/ wiki/ISO_4217.

Order/TotalCost/CostTotals/ AmountAfterTax

Yes

Yes

Total cost of the order after tax

Decimal

Minimum of 0, 2 decimal places

Order/TotalCost/CostTotals/ AmountAfterTax/ @CurrencyCode

Yes

Yes

Type of currency used for the total after-tax cost

String

Attribute element; 3-character ISO 4217 code (for example, USD, CAD, EUR). See http://en.wikipedia.org/ wiki/ISO_4217.

Order/TotalCost/FailedCc/ @Number

No

No

Number of failed authorizations for the order. If customer experiences failed authorizations across multiple tenders, all of these should be added together to get the failed authorization count.

Int

Attribute element

ServerInfo

Yes

Yes

Sequence of Time, TZOffset, TZOffsetRaw, DSTActive

ComplexType

 

ServerInfo/Time

Yes

Yes

Timestamp for order creation, in UTC. This should include milliseconds, if possible.

Date Time format: 2019-01-31T19:17:58.701Z

DateTime

Greater than 1900-01-01T00:00:00 Less than 2100-01-01T00:00:00

ServerInfo/TZOffset

Yes

Yes

Time zone offset for the order creation timestamp as compared to UTC. Informational only. This helps understanding that in which time zone was the order placed.

Decimal

Ranges from -12 to 13 in half or quarter hour increments

ServerInfo/TZOffsetRaw

No

No

 

Decimal

Ranges from -12 to 13 in half or quarter hour increments

ServerInfo/DSTActive

Yes

Yes

Flag that indicates whether daylight savings time was active on the server at the time of the event

Boolean

True or False

DeviceInfo

No

No

Device information from which the order is placed.

Sequence of JSCData, SessionID, DeviceIP, DeviceHostname, HttpHeaders, UserCookie

ComplexType

 

DeviceInfo/JSCData

No

No

 

String

 

DeviceInfo/SessionID

No

Yes – if available.

User's browser session ID that is used to identify session hijacking occurrences

String

Max 255 characters

DeviceInfo/DeviceIP

No

Yes - Required if available. Should be available on most transactions, pulled from X-Forwarded-For header.

IP4 or IPv6 address of the customer’s device making the request to the server, (for example, 10.0.0.1). This is the customer's external IP address.

String

Max 39 characters

DeviceInfo/DeviceHostname

No

No

Domain name of the browser’s page where order is being placed.

String

Max 100 characters

DeviceInfo/HttpHeaders

No

Yes – If available.

HTTP header entry collected from the HTTP session on the web application server

 

Sequence of HttpHeader

ComplexType

 

DeviceInfo/HttpHeaders/ HttpHeader

No, unbounded repetitions

No, unbounded repetitions

HTTP header entry collected from the HTTP session on the web application server

String

 

DeviceInfo/HttpHeaders/ HttpHeader/@name

Yes

Yes

Name of the http header

String

Attribute element

DeviceInfo/UserCookie

No

Yes - Required if available

Specific portion of the HttpHeader cookie that is used by the web system integrating with the fraud system

String

 

CustomProperties

No

Yes- See table below for a list of custom properties that must be included if available.

Sequence of CustomPropertyGroup

ComplexType

See table below for a list of custom properties that must be included if available.

CustomProperties/ CustomPropertyGroup

Yes, unbounded repetitions

Yes, unbounded repetitions

Sequence of CustomProperty

ComplexType

 

CustomProperties/ CustomPropertyGroup/ @name

Yes

Yes

Property group name

String

Attribute element; at least 1 character

CustomProperties/ CustomPropertyGroup/ CustomProperty

Yes

Yes

Choice of StringValue, IntegerValue, FloatValue, DateTimeValue

ComplexType

 

CustomProperties/ CustomPropertyGroup/ CustomProperty/@name

Yes

Yes

Property name

String

Attribute element; at least 1 character

CustomProperties/ CustomPropertyGroup/ CustomProperty/StringValue

Choice, one of the elements at this level is required

Choice, one of the elements at this level is required.

Property string value

String

 

CustomProperties/ CustomPropertyGroup/ CustomProperty/IntegerValue

Choice, one of the elements at this level is required

Choice, one of the elements at this level is required.

Property integer value

Long

 

CustomProperties/ CustomPropertyGroup/ CustomProperty/FloatValue

Choice, one of the elements at this level is required

Choice, one of the elements at this level is required.

Property float value

Double

 

CustomProperties/ CustomPropertyGroup/ CustomProperty/ DateTimeValue

Choice, one of the elements at this level is required

Choice, one of the elements at this level is required.

Property DateTime value

DateTime

 

Custom Properties

The following custom properties must be passed in the request if available.

Custom Property Name

Custom Property Group Name

Data Type

Description

Sample Values

RDFUID

GSI_CUSTOM

String

The RDFUID captured during the order placement, which is generated by Radial Device fingerprinting JavaScript, should be sent in this customer property.

Details on how to capture RDFUID are available here: Radial Device Fingerprint

00744669-e12b-4365-960e-108402212254_1493405974023

BABY_REGISTRY_IND

GSI_CUSTOM

String

If an item on the order is on a Baby Registry an indicator of “Y” or “N” variable should be sent to Radial.

Y, N

GIFT_REGISTRY_IND

GSI_CUSTOM

String

If an item on the order is on a Gift Registry an indicator of “Y” or “N” variable should be sent to Radial.

Y, N

PAYPAL_PAYER_COUNTRY

GSI_CUSTOM

String

If the tender type is PayPal, the Payer Country field received from PayPal transaction.

US, CA

ORIG_SOURCE

GSI_CUSTOM

String

The source of the order. It can have values like web if webstore, phone if customer agent took the order, kiosk if customer placed order in store, etc.

Web, Kiosk, Phone, etc.,

PROXY_ORDER

GSI_CUSTOM

String

Proxy pickup is a type of in store pickup order where the customer designates a 3rd party to pick their order up. An indicator of “Y” or “N” value saying this is a proxy pickup order should be sent to Radial.

Y, N

PP_SLR_PRT

GSI_CUSTOM

String

The value of PayPal Seller Protection received from PayPal transaction response, if available should be passed here.

Eligible, Ineligible

Example GSI_CUSTOM Properties Group

<CustomProperties>
      <CustomPropertyGroup Name="GSI_CUSTOM">
         <CustomProperty Name="RDFUID">
            <StringValue>00744669-e12b-4365-960e-108402212254_1493405974023</StringValue>
         </CustomProperty>
         <CustomProperty Name="BABY_REGISTRY_IND">
            <StringValue>N</StringValue>
         </CustomProperty>
         <CustomProperty Name="PAYPAL_PAYER_COUNTRY">
            <StringValue>US</StringValue>
         </CustomProperty>
         <CustomProperty Name="GIFT_REGISTRY_IND">
            <StringValue>N</StringValue>
         </CustomProperty>
         <CustomProperty Name=" ORIG_SOURCE ">
            <StringValue>Web</StringValue>
         </CustomProperty>
         <CustomProperty Name=" PROXY_ORDER ">
            <StringValue>N</StringValue>
         </CustomProperty>
         <CustomProperty Name="PP_SLR_PRT">
            <StringValue>Eligible</StringValue>
         </CustomProperty>
      </CustomPropertyGroup>
</CustomProperties>

Types of Response Messages

This API supports multiple types of response messages.

  • The Fault_DUPLICATE message provides information regarding the order as well as an error code and description to help troubleshoot the issue.
  • The AckReply message is an HTTP Response that simply acknowledges that the request was received. See HTTP Response, below, for details.
  • The RiskAssessmentReply asynchronous message provides risk details for a single order and is supported by RabbitMQ. See Reply Event (Single), below.
  • The RiskAssessmentReplyList asynchronous message is an optional alternative to RiskAssessmentReply. It provides risk details for multiple orders in the same message. RiskAssessmentReplyList is not supported by RabbitMQ, but can be used by clients that implement webhook. See Risk Assessment List Event, below.

Fault_DUPLICATE Response Event

The Fault_DUPLICATE XML response contains a StoreId and OrderId to help identify the order that caused the error, as well as the Code and Description fields which help troubleshoot what caused the error in the Radial system.

Fault_DUPLICATE Response Example

<Fault_DUPLICATE xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
   <OrderId>80000000022053</OrderId>
   <Code>RejectedRequest</Code>
   <Description>Fraud request was rejected</Description>
   <StoreId>ZAJEUS</StoreId>
</Fault_DUPLICATE>

Fault_DUPLICATE Response Elements

Element Required Description Type Restriction
OrderId Yes The unique identifier of the order that caused the error String At least 1 character, Max 20 characters
Code Yes The unique Error Code related to the cause of the Fault Response String  
Description Yes A more user friendly error message that describes the error that occurred String
StoreId Yes Contains the store identifier passed by the client in request URI String Max 100 characters

AckReply Http Response

<?xml version="1.0" encoding="UTF-8"?>
<AckReply xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
   <Received/>
</AckReply>

Reply Event (Single)

The RiskAssessmentReply asynchronous message provides risk details for a single order and is supported by RabbitMQ.

Queue Format

q.Risk.Orders.Status.<RABBIT_MQ_USERNAME>

Response Example (Single)

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<RiskAssessmentReply xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
   <OrderId>1452618248</OrderId>
   <MockOrderEvent>false</MockOrderEvent>
   <ResponseCode>Accept</ResponseCode>
   <StoreId>TMSUS</StoreId>
   <ReasonCode>FA</ReasonCode>
   <ReasonCodeDescription>Fraud Accepted</ReasonCodeDescription>
</RiskAssessmentReply>

Response Elements (Single)

Element

Required

Description

Type

Restriction

OrderId

Yes

Order ID

String

At least 1 character, Max 20 characters

MockOrderEvent

No

Flag that indicates whether the risk assessment is for a mock/test order. If this is true, nothing should be shipped.

Boolean

True or False

ResponseCode

Yes

Overall response code for the risk assessment

String

Accept Cancel Suspend

StoreId

Yes

Contains the store identifier passed by the client in request URI

String

Max 100 characters

ReasonCode

No

The reason code mapped from the responses based on Fraud response

String

ReasonCodeDescription

No

Description associated with the reason code

String

Risk Assessment List Event

The Risk Assessment List XML response contains a list of RiskAssessmentReply and/or Fault_DUPLICATE messages clubbed under one parent element. This response format is available only for clients using Asynchronous API Operations through Webhooks. Both the list responses are shown below. This message cannot be obtained from a queue in RabbitMQ, so the queue format is not applicable for this response format.

The individual RiskAssessmentReply message continues to be supported on the RabbitMQ server. See the information above for details.

Response Example (List)

The below response shows a list of both RiskAssessmentReply and Fault_DUPLICATE. Instead of returning single RiskAssessmentReply or Fault_DUPLICATE message, a list/batch of messsages are getting returned here.
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<RiskAssessmentReplyList xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
    <RiskAssessmentReply>
       <OrderId>1452618248</OrderId>
       <MockOrderEvent>false</MockOrderEvent>
       <ResponseCode>Accept</ResponseCode>
       <StoreId>TMSUS</StoreId>
       <ReasonCode>FA</ReasonCode>
       <ReasonCodeDescription>Fraud Accepted</ReasonCodeDescription>
    </RiskAssessmentReply>
    <RiskAssessmentReply>
       <OrderId>1000012</OrderId>
       <MockOrderEvent>false</MockOrderEvent>
       <ResponseCode>Accept</ResponseCode>
       <StoreId>TMSCA</StoreId>
       <ReasonCode>XU</ReasonCode>
       <ReasonCodeDescription>Fraud Cancelled</ReasonCodeDescription>
    </RiskAssessmentReply>
    <Fault_DUPLICATE_List>
	  <Fault_DUPLICATE>
		  <OrderId>80000000022053</OrderId>
		  <Code>RejectedRequest</Code>
		  <Description>Fraud request was rejected</Description>
		  <StoreId>ZAJEUS</StoreId>
	  </Fault_DUPLICATE>
	  <Fault_DUPLICATE>
		  <OrderId>90000000022009</OrderId>
		  <Code>RejectedRequest</Code>
		  <Description>Fraud request was rejected</Description>
		  <StoreId>ZAJEUS</StoreId>
	  </Fault_DUPLICATE>
  </Fault_DUPLICATE_List>	
</RiskAssessmentReplyList>

Response Elements (List)

Element

Required

Description

Type

Restriction

RiskAssessmentReplyList

No. A wrapper/parent object for all the RiskAssessmentReply elements

Sequence of RiskAssessmentReply elements

ComplexType

RiskAssessmentReply

A wrapper/parent object for all the sub-elements such as OrderId, MockOrderEvent, ResponseCode, StoreId, ReasonCode etc.

Sequence of OrderId, MockOrderEvent, ResponseCode, StoreId, ReasonCode

ComplexType

OrderId

Yes

Order ID

String

At least 1 character, Max 20 characters

MockOrderEvent

No

Flag that indicates whether the risk assessment is for a mock/test order. If this is true, nothing should be shipped.

Boolean

True or False

ResponseCode

Yes

Overall response code for the risk assessment

String

Accept Cancel Suspend

StoreId

Yes

Contains the store identifier passed by the client in request URI

String

Max 100 characters

ReasonCode

No

The reason code mapped from the responses based on Fraud response

String

ReasonCodeDescription

No

Description associated with the reason code

String

Fault_DUPLICATE_List

No. A wrapper/parent object for all the Fault_DUPLICATE elements and it's sub-elements such as Fault_DUPLICATE, OrderId, Code, Description, StoreId etc.

Sequence of Fault_DUPLICATE, OrderId, Code, Description, StoreId, etc.

ComplexType

Fault_DUPLICATE

A wrapper/parent object for all the Fault_DUPLICATE elements and it's sub-elements such as OrderId, Code, Description, StoreId etc.

Sequence of OrderId, Code, Description, StoreId, etc.

ComplexType

Code

Yes

Overall response code for the risk assessment

String

Description

Yes

Description associated with the reason code

String

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. Please see Fraud Integration for more details. The ResponseCode field describes the action that must be taken on the order, usually in the client OMS.

 

ResponseCodeAction
AcceptApprove the order in the client OMS and release it for fulfillment.
CancelCancel 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.
SuspendChange 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.

XAPayment DeclinedThe 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.
XBBrand ProtectionThe 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

  • 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.