If you are using a webstore other than Magento, you can use a REST API to install Radial Fraud Insight.

Note: The following instructions assume that you have experience integrating REST APIs into your system. If you do not, contact your Radial representative.

Authentication and Authorization

The client application must adhere to Radial’s Web Services Security Protocol when communicating with the Fraud Insight API.

Radial requires customers to use key-based authentication as part of their implementations. The authentication key is part of the HTTP header. Radial generates the key and provides it to the client. A new key is provided every six months.

The client application submits an order status request for Fraud Insight using HTTPS POST only.

URI Summary

Action

URI Template

URI Example

Non-URI Request

Response

POST

/v[M.m]/stores/[StoreId]/ risk/ insight/request.[format]

/v1.0/stores/ABCXYZ/risk/ insight/request.xml

XML

200 + XML response

Note: Separate URLs are provided for Fraud Insight Response during the implementation.

API Elements

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

Example GSI_CUSTOM Properties Group

Copy
<CustomProperties>
   <CustomPropertyGroup Name="GSI_CUSTOM">
      <CustomProperty Name="RDFUID">00744669-e12b-4365-960e-108402212254_1493405974023</CustomProperty>
   </CustomPropertyGroup>
</CustomProperties>

Request/Response Schemas and Samples

Schemas

Request Samples

Click to view each of the following request samples.

Response Samples

Click to view each of the following response samples.

API Security Overview

To ensure the security and integrity of our client’s uses of the Radial Fraud Insight API, all communications must be encrypted and all API calls must include a valid API Key specific to the partner, API version, and environment.

Encrypted Traffic

All communication from and to the partner must use secure encryption. The Radial Fraud Insight API supports only the Secure Sockets Layer (SSL) protocol TLSv1 and above.

  • Requests made to the API by unsecured channels (for example, HTTP) are ignored. By using unencrypted communications, the API key could be “sniffed” from the request and used by unauthorized users. Since Map service providers (like Google) charge based on usage, compromised API keys could lead to unexpected additional costs or even having their access revoked by the provider if the unauthorized traffic violates the usage policies of the provider.
  • If unencrypted communications would occur, the Partner should request an emergency API key rotation to ensure their Fraud Insight channel remains secure.
  • Improper implementation of SSL enabled capabilities using the DefaultHttpClient or other similar providers can make the implementation susceptible to “man-in-the-middle” exploits. Please ensure a sufficient security focused code review is completed to ensure this important function is implemented correctly and securely.

API Key

The Radial services team assigns your API keys during the launch planning process, development, and launch prep. During service calls, the appropriate key must be sent to Radial in the request header so that the source of the request can be authenticated and to determine if the client is authorized to use the specific function and version of the API in the request. The API key is sent in the request header so that it does not get stored in any server logs and retains its security level.

Using the API key

  • Key-Value pairs: Set the API key as a value in the request header. The key for this is “apikey”.
  • API keys are specific to the client, API version, and environment: Radial issues different keys for the Developer and Production environments. If you have access to multiple versions of the API, each version of the API requires a separate API key.
  • API Key Rotation: All API Keys must be changed at least every six months to ensure that all interactions remain secure.
  • Emergency Key Changes: If the client determines that any API key has been compromised or otherwise disclosed, the key can be changed immediately by contacting the Radial Production Support Line and requesting a P1 ticket for the change.

API key example

The following sample API key has been deactivated and will not work. You must use your assigned API key for the respective environments.

Client (Used by): ABCTEST

Allowed Store codes: ABCTEST

Key Value: 7aabe0a107ac0b3744fbd17cbf9fd23d

Key Start Date: 1 May 2012

Key Expiration Date: 10 May 2012

Adding the API Key data to the Request Header

You can add the API Key data as a Request Header programmatically when the request is prepared to be sent to the Radial Fraud Insight API. The following example shows this technique in two tools: the REST Client for Firefox and Java.

REST Client for Firefox

  1. Set the Method as POST.
  2. In the URL, paste the URL that Radial provides to you.
  3. Click Headers, then add a custom header with name apikey and value that you were provided.

  4. Provide the order status request in the Request Body as shown below.
  5. Click SEND.

    The following figure shows the status code in the Response Headers section.

If the status code is 200 or 50, the response from the Fraud Insight appears in the Response Body field.

If the status code is 40x, it indicates that an error occurred because the URL or apikey pair did not reach the Fraud Insight product. Therefore, Fraud Insight could not produce a response.

Java code

The following example shows one of many possible ways to implement adding the API Key as a Request Header.

This example does not show implementation of SSL Certificate needed for SSL usage.

Copy
import org.apache.commons.httpclient.*

String baseEndPoint = " https://api-na.gsipartners.com/v1.0/stores/ABCTEST/risk/insight/request.xml";

HttpClientParams params = new HttpClientParams();
params.setConnectionManagerTimeout(5000);
params.setSoTimeout(10000);
HttpClient httpClient = new HttpClient(params);

PostMethod method = new PostMethod(baseEndPoint);
//set the security credentials to the request header
method.addRequestHeader("apikey", "4d3ba833daec4b56f68006a6b0fbab");
method.setRequestEntity(new StringRequestEntity(xml, "text/xml", "UTF-8"));
httpClient.executeMethod(method);
String response = method.getResponseBodyAsString();