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.
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.
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.
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
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.
Create a team
Follow these steps to create a team and API key.
- Log in to the Signifyd Console.
- Go to Settings and then click the Teams tab.
- 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.
- Select the Test Team checkbox.
- Click the Create Team button.
- Copy the API key from the Teams page
Congratulations, you have successfully created teams. Now that you have an API key you are ready to start building your integration.
Step 2: Submit an Order for Guarantee
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.
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
- 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.
- BASE64 encode the API key.
- Provide an
Authorizationheader with content
Basicfollowed by the encoded API key.
- Provide a
application/jsonin the header
You can use the examples below to base64 encode your API key.
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).
Mapping Order Data to the Signifyd Case
- 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.
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.
$purchase = array();
$purchase['browserIpAddress'] = $this->getClientIp();
$purchase['orderId'] = $this->getId();
$purchase['createdAt'] = $this->getOrderDate();
$purchase['paymentGateway'] = $this->getPaymentGatewayStringName();
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.
4. Send Order
After you have completed the mapping and transformation steps, you are ready to submit your first order to Signifyd.
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.
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.
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.
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.
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.
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
You are now ready for the next step: adding Signifyd’s device and behavior tracking to your store.
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.
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.
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
data-order-session-id from the script and or mobile SDK to the order session Id in the body of the create case request.
Congratulations, you have successfully added device fingerprinting to your store.
Step 4: Get Signifyd’s Guarantee Decision via Webhook
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.
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.
- Go to the Notifications page in the settings menu
- Under the Webhooks section, select the event type of Guarantee Completion and the Team the webhook should be configured for
- Click Add
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.
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.
We recommend saving the following fields from the webhook body to your ecommerce platform.
You can verify if the webhook was sent by Signifyd by checking the signature in the header of the webhook message.
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.
$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;
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
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.
Congratulations, you have completed your Signifyd integration! Your Signifyd Implementation Manager will now guide you through deploying your integration to your production store.