Ecommerce Integration Guide

Signifyd uses machine learning to detect ecommerce fraud by using hundreds of data points, elastic linking, and behavior data. To learn more about Signifyd check out our how it works page.

Getting Started

Overview

Integrating Signifyd on your online stores enables orders placed on your stores to be sent to Signifyd for Guaranteed Fraud Protection. This guide will cover the minimum components to build a successful integration. You can find a complete list of all of the Signifyd APIs in the Signifyd API doc.

This integration guide covers the general steps of integrating with Signifyd.

  1. Creating teams
  2. Submitting orders for fraud review
  3. Adding device fingerprinting
  4. Configuring webhooks

Order Flow

In Step 1: Signifyd's device fingerprinting script and mobile SDK collects device and behavioral data as users shop on your online store. This occurs silently without affecting the load times of pages or the user experience. Device and behavioral data is sent to Signifyd on page load while additional events are batched and sent via HTTP every 3 seconds.

In Step 2: When an order is placed on your online store the order details provided during checkout are submitted to Signifyd for fraud review.

In Step 3: Signifyd reviews the order for fraud using machine learning, elastic linking, and data enrichment.

In Step 4: After the order is reviewed, Signifyd notifies your online store of the guarantee decision (approved or declined) through an HTTP POST or webhook.

In Step 5: When your store receives the webhook message, you can trigger automated workflows in your system based on your specific business needs e.g. capture the payment and ship the order or void the payment and cancel the order.

Wrap Up

When you're ready to start your Signifyd integration you will be assigned an Implementation Manager who will help guide you through the onboarding process. You can learn more about the onboarding process in our overview guide.

The next section will walk you through the first step of the integration process, creating a team.

-

Step 1: Creating Teams

Overview

In Signifyd, API keys are assigned to teams within your Signifyd account. Teams are groups that allow you to manage user and API access for orders submitted from your online store. 

There are two types of teams:

  • Test Team: used to build your integration and send test orders. You will not be charged for orders submitted to this team.
  • Production Team: used to send live orders to Signifyd for Guarantee Fraud Protection. Orders submitted to this team are protected by Signifyd's Guarantee Fraud Protection.

We recommend creating a Test Team when building an integration for the first time, so that you can test before going live. If you have multiple online stores like www.mygreatshoes.com and www.mygreatwatches.com you will need to create a test team for both online stores. 

note-icon

Note

After you've signed up for a plan, a Signifyd account will be created for you. If you don't have an account or need help signing up for a plan, contact us.

Create a team

Follow these steps to create a team and API key.

  1. Log in to the Signifyd Console.
  2. Go to Settings and then click the Teams tab.
  3. Enter a name for your team. We recommend you prefix your team name with "Test" and the name of your online store. Example: Test - My Shoe Store.
  4. Select the Test Team checkbox.
  5. Click the Create Team button.
  6. Copy the API key from the Teams page

Wrap Up

Congratulations, you have successfully created teams. Now that you have an API key you are ready to start building your integration.

What do you think of this section? Send us feedback.

-

Step 2: Submit an Order for Guarantee

Overview

To submit an order from your online store to Signifyd for fraud review, you will need to create a case using Signifyd’s REST API.

lightbulb-icon

Tip

Developing your integration in PHP? You can save time by using Signifyd PHP client library.

AUTHENTICATE

Set up the authentication required to make APIs requests. 

MAP

Map the data fields from your online store to the Create Case API.

TRANSFORM

Format request to meet the API specs. 

SEND ORDERS

Call the Create Case API to send an order for fraud review.

1. Authenticate

To call the Signifyd API you will need to authenticate the request using your API key. All requests must be made over HTTPS and use basic authentication.

Set Up Basic Authentication

  1. Build a string in the form of username:apiKey. There is no password, however, some REST clients expect a username:password pair separated by a colon. If so, you can use a colon as the password.
  2. BASE64 encode the API key.
  3. Provide an Authorization header with content Basic followed by the encoded API key.
  4. Provide a content-type of  application/json in the header
PHP

$signifyd_api_key = 'YOUR_API_KEY';

Python
Java
.NET
Ruby

You can use the examples below to base64 encode your API key.

PHP

$authorization = 'Basic' . base64_encode(":{$apiKey}");

Python
Java
.NET
Ruby

2. Map the Data

Next, you'll need to map various data fields from your online store to the Signifyd case API schema.

Case API Schema

The Signifyd case is broken into a series of objects that correspond to different objects from your online store (products, payments, shipments, etc).

purchase ECOMMERCE SYSTEM ORDERS WEBSITE SIGNIFYD CASES shipments products recipient discountCodes card userAccount billingAddress seller* PRODUCTS CUSTOMERS SHIPMENTS DISCOUNTS PAYMENTS SELLER ACCOUNTS SESSION ID deliveryAddress
lightbulb-icon

Tip

If process payments through Authorize.net, you can use the Signifyd Authorize.net integration to sync payment data automatically.

Mapping Order Data to the Signifyd Case

  1. For each field in the create case request identify the applicable field in your online store. Some data fields like payment information (avs response code, bin, last4, etc) may require additional development effort to collect and save.
lightbulb-icon

Tip

We recommend downloading our field mapping document to keep track of which fields map to the Signifyd Create Case API request. This document can also be shared with other stakeholders or decision makers in your company.

2. Map each field you plan to send to Signifyd to the appropriate field in the Create Case request.

Example

$purchase = array();
$purchase['browserIpAddress'] = $this->getClientIp();
$purchase['orderId'] = $this->getId();
$purchase['createdAt'] = $this->getOrderDate();
$purchase['paymentGateway'] = $this->getPaymentGatewayStringName();

exclamation-gold-icon

Important

The Create Case API only requires one field to be present, however, we strongly recommend you provide all of the fields listed as required in the API document to ensure the best guarantee decision. Please consult your Implementation Manager if you are unable to provide a required field.

3. Transform Any Required Fields

The Create Case API will require some field values to be provided in a specific format for the request to be accepted successfully.

  • Dates must be in ISO 8601 format
  • Countries must be ISO 3166 format
  • Currencies must be ISO 4217 format
  • Enums: order channel, shipper, shipping method, payment method, avs response codes, and cvv response code should use the pre-defined value
  • Valid syntax: browser IP address, confirmation email, and email should have a valid syntax and format

For expected field values, field types, and formats please refer to the API doc.

lightbulb-icon

Tip

You can use the AVS and CVV response code reference sheet to determine how to map AVS and CVV response codes for specific payment gateways.

4. Send Order

After you have completed the mapping and transformation steps, you are ready to submit your first order to Signifyd.

lightbulb-icon

Tip

You should only send orders when the checkout has been completed and the order has been successfully authorized by your payment processor. This will ensure that you can successfully process the payment (capture, refund, or void) based on Signifyd's guarantee decision.

Submit an Order for Guarantee

  1. Get your API key from the settings page of the Signifyd console
  2. Base64 encode the API key
  3. Specify the appropriate request headers, authorization and content-type
  4. Call the Create Case API
note-icon

Note

If you are on a Complete Plan, submitting a case will automatically submit the order for guarantee; no additional steps are needed. If you are on an On-Demand or Enterprise plan, you will also need to submit the case for guarantee using the Submit for Guarantee API.

If your API call is successful, you will receive a 201 status code along with the investigation id, Signifyd's unique identifier for the order. You should save this id in your backend application so that you can identify, update, or add other resources to the case later.

Status Code: 201


{"investigationId" : 811964631}

note-icon

Note

Investigation id is a legacy field which will return the case id. As such, the investigation id and case id can be used interchangeably in any API request.

5. Search for the newly created case in the Signifyd Console. You can search by entering the case id into the search bar and clicking the search icon.

6. Verify the data displayed on the Signifyd order page matches the data submitted in the API request.

note-icon

Note

The Create Case API has no call limits or throttling to ensure it can accept an extremely high volume of orders even during flash sales. To that end, the API will immediately return a case Id as a synchronous response, however, the creation of the case happens later in an asynchronous manner. Due to the asynchronous nature of the API, there may be a short delay from the time a case Id is returned in the API response to when it is accessible via API or the Signifyd Console.

Handling Errors

We use conventional HTTP response codes to indicate success or failure of an API request. You can view a list of error codes on our API document.

We recommend writing code that gracefully handles all possible API exceptions. For server related errors (409 and 5xx), we recommend that you retry the request at least 5 times using exponential backoffs.

  • If the first request fails, wait .25 seconds and then try again
  • If the 2nd request fails, wait .5 seconds and then try again

For other errors that require an update to your request body, we recommend that you add logging so that you can identify the issue and fix it before re-sending the request.

Here’s a list of information that you should consider logging for general troubleshooting:

  • API Endpoint: The URI for the API request
  • API Method: PUT, POST, DELETE, etc
  • API Request Body: the body provided in the request
  • API Response: the message return by Signifyd in the API request
  • HTTP Status Code: 500, 200, etc
  • Request timestamp: the date and time the request was made.
  • Response timestamp: the date and time Signifyd returned a response.
exclamation-gold-icon

Important

A submitted order can be ineligible for guarantee for various reasons. You should verify that your integration is able to handle these scenarios appropriately. You can subscribe to receive a webhook if an order is ineligible for guarantee.

Ineligible Guarantee Reasons

  • The order amount is null
  • A guarantee already exists for a different case with the same order Id and order amount (total order amount)
  • The order date (createdAt) for the case is 7 or more days old
  • The order amount < 0

Wrap Up

You are now ready for the next step: adding Signifyd’s device and behavior tracking to your store.

What do you think of this section? Send us feedback.

-

Step 3: Add Device Fingerprinting

Signifyd’s device fingerprinting tags enable the collection of behavior (page view, clicks, mouse movements, etc) and device data (operating system, browser, true IP, device Id, etc) that helps bolster the identification of fraud. If you sell products through a native mobile application (iOS and or Android), you will also need to integrate one of our Mobile SDKs.

note-icon

Note

The javascript tags load asynchronously, it does not affect page load times or the checkout experience.

GENERATE SESSION ID

Generate a random string that is unique to each user's checkout event. 

ADD THE SCRIPT

Add the javascript tag to your site and set the data-order-session-id in the script to the random string you generated in step 1.

SEND SESSION ID

Save the session id to your back-end and post it to the Create Case API along with order data collected during checkout. 

1. Generate a Session Id

The session Id is a random string that is unique to each checkout on your online store, not the user's browsing session.

Here are some suggestions for creating a unique session Id:

  • Create a session identifier from a cookie and append the date and time in milliseconds to the end of the identifier along with a hexadecimal hash.
  • Create a session identifier from scratch by using the date and time in milliseconds and a randomly generated hexadecimal hash.
  • Use an existing session identifier from your online store and add a hexadecimal hash to the value.
exclamation-gold-icon

Important

To ensure the script works properly the session Id should meet the following guidelines:

  • Be greater than 10 characters and less than 128 characters long
  • Be unique for each user's checkout
  • Only contain the following characters: upper and lowercase English letters (a-z, A-Z), digits (0-9), underscores (_), or hyphens (-)

2. Add the Script

Implementing on Your Website

Place the tags just before the closing </head> tag on all public facing pages on your store.

note-icon

Note

We highly recommend that you include this script on every page on your site - not just the checkout page. Including the script on every page allows Signifyd to detect anomalous behavior that may be indicative of fraud as users browse through your online store.

Implementing on Your Mobile App

Refer to our SDK page and mobile SDK integration guide for implementation details.

3. Send the Session Id

Add the data-order-session-id from the script and or mobile SDK to the order session Id in the body of the create case request.

Example

purchase['orderSessionId'] = uniqueSessionId;

Wrap Up

Congratulations, you have successfully added device fingerprinting to your store.

What do you think of this section? Send us feedback.

-

Step 4: Get Signifyd’s Guarantee Decision via Webhook

Overview

Signifyd can send a webhook to notify your online store every time a guarantee decision is made on a submitted order. This provides you with real-time updates enabling you to ship orders quickly and efficiently. Webhooks can also be used to notify other systems, like Order Management Systems OMS, that are not directly responsible for making the API request, but still need to know the result of the guarantee decision.

This section will walk you through the steps necessary to implement webhooks.

CREATE ENDPOINT

Create a publicly accessible webhook endpoint

SET UP WEBHOOK EVENTS

Configure what events will trigger webhook messages and where the notifications should be sent. 

PARSE WEBHOOK

Save the webhook response to your system.

AUTOMATE WORKFLOWS

Automate your back-office by triggering key events based on Signifyd's guarantee decision.

lightbulb-icon

Tip

We recommend the use of webhooks since they provide instant feedback when a decision is made on an order; however, you can use the Signifyd Get Case API to poll for the guarantee decision of the case.

Statuses and Definitions

Guarantee Status Description Webhook Event
Pending The case is waiting to be reviewed for fraud. This is the inital status of the case when submitted. None
In Review The case is being reviewed for fraud. None
Approved The case has been reviewed for fraud and is safe to ship. If the order results in a fraudulent chargeback it is eligible for reimbursement. Guarantee Completion
Declined The case has been reviewed for fraud and is not safe to ship. If the order results in a fraudulent chargeback it is not eligible for reimbursement. Guarantee Completion
Canceled The request to guarantee the order was canceled when the status was approved, pending, or in review. If the order results in a fraudulent chargeback it is not eligible for reimbursement. None
Unrequested The case has not been submitted for guarantee. If the order results in a fraudulent chargeback it is not eligible for reimbursement. None

1. Create Endpoint

You'll need to create a publicly accessible endpoint for Signifyd's webhook notifications to POST to.

Creating a webhook endpoint on your server is no different from creating any page on your website. You can use a framework like Sinatra or ngrok and add a new route with the desired URL.

2. Set Up Webhook Events

Once you have a publicly accessible webhook endpoint, you can add the webhook URL in the Signifyd console so that Signifyd can notify your system every time a guarantee decision is made on a submitted order.

  1. Go to the Notifications page in the settings menu
  2. Under the Webhooks section, select the event type of Guarantee Completion and the Team the webhook should be configured for
  3. Click Add
lightbulb-icon

Tip

You can send a test notification to the endpoint by clicking the Test button. If there is an issue with posting to the endpoint, a message will be shown with the error.

Jan-11-2019 03-09-42
note-icon

Note

A webhook will not be sent if the guarantee decision is pending, canceled, or in-review.

3. Parse Webhook

Webhook data is sent as JSON in the POST request body. The JSON can be parsed into an Event object.

PHP

$request = file_get_contents("php://input");
$eventJson = json_decode($request, true);
// Handle received event
http_response_code(200);

Python
Java
.NET
Ruby

We recommend saving the following fields from the webhook body to your ecommerce platform.

  • caseId
  • guaranteeDisposition
lightbulb-icon

Tip

You can verify if the webhook was sent by Signifyd by checking the signature in the header of the webhook message.

Verify Webhook

To verify a webhook message has come from SIGNIFYD, an X-SIGNIFYD-SEC-HMAC-SHA256 header is included in each webhook POST message. The contents of this header is the Base64 encoded output of the HMAC SHA256 encoding of the JSON body of the message, using the team's API key as the encryption key.

You should calculate this value and verify it matches the value contained in the header.

PHP

$request = file_get_contents("php://input");
// Signifyd webhook headers include - but PHP replaces them with _ on $_SERVER and adds 'HTTP_ before it
$phpServerHeaderHash = 'HTTP_' . str_replace('-', '_', 'X-SIGNIFYD-SEC-HMAC-SHA256');
$hash = $_SERVER[$phpServerHeaderHash];
$check = base64_encode(hash_hmac('sha256', $request, $apiKey, true));
$isValidRequest = $hash == $check ? true : false;

Java

4. Automate Workflows

To automate order fulfillment you’ll want to take action in your online store or order management system based on Signifyd’s guarantee decision. The specific actions that you may need take in your system to complete order fulfillment may vary, however, you should consider the following actions when defining your workflows.

Scenario 1: Ship Approved Orders

When Signifyd makes a guarantee decision of approved ship the order and capture the payment immediately.

  • Guarantee Decision: Approved
  • Order Status: Fulfilled
  • Payment Status: Captured
  • Buyer Communication: Your order is shipping

Scenario 2: Manually review orders that are declined.
The order is placed on hold so your team can review the order in the Signifyd console.

  • Guarantee Decision: Declined
  • Order Status: Hold
  • Payment Status: Authorized/Sale
  • Buyer Communication: None

You can then manually take the following actions:

  • Cancel - If your review team agrees with Signifyd and believes the order is fraudulent, cancel the order.
  • Resubmit - If your review team believes the order is not fraud, you can resubmit it for a second review.
  • Ship without a guarantee - If you choose, you can ship the order without guarantee fraud protection.

Scenario 3: Cancel orders that are declined.
Cancel the order and void / refund the payment immediately

  • Guarantee Decision: Declined
  • Order Status: Cancel
  • Payment Status: Void/Refund
  • Buyer Communication: Your order is canceled

Error Handling

To acknowledge receipt of a webhook, your endpoint should be publicly accessible and return a 2xx HTTP status code. All response codes outside of this range, including 3xx codes, will indicate to Signifyd that you did not receive the webhook including URL redirection or "Not Modified" responses.

If your endpoint is down or not able to successfully receive a webhook Signifyd will resend the webhook up to 15 times over a four day period. The first webhook will be retried after 20 seconds with exponential delays for each subsequent retry.

Retry Time
1 20s
2 40s
3 80s
4 160s
5 320s
6 640s

Wrap Up

Congratulations, you have completed your Signifyd integration! Your Signifyd Implementation Manager will now guide you through deploying your integration to your production store.

What do you think of this section? Send us feedback.