Skip to content

Sending Orders

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.

This section of the guide will cover the following steps:

  1. Authentication >
  2. Data Mapping >
  3. Data Transformation >
  4. Order Submission >
  5. Verify Data Quality >

1. Authentication

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.

Setting up your api key

  1. $signifyd_api_key = 'YOUR_API_KEY';

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

BASE64 ENCODE YOUR API KEY

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

2. Data Mapping

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). The following diagram depicts the Case API schema:

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

Tip: If you 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.

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 for field mapping

  1. $purchase = array();
  2. $purchase['orderId'] = $this->getId();
  3. $purchase['createdAt'] = $this->getOrderDate();
  4. $purchase['paymentGateway'] = $this->getPaymentGatewayStringName();

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. Data Transformation

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 code, and CVV response code should use the predefined value.
  • Valid syntax: browser IP address, confirmation email, and userAccountEmail should have a valid syntax and format.

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

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. Order Submission

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

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 Teams page.
  2. Base64 encode the API key.
  3. Specify the appropriate request headers, authorization and content-type.
  4. Call the Create Case API.

Note: If you are on a Guaranteed Fraud Protection plan, submitting a case will automatically submit the order for guarantee; no additional steps are needed. If you are on a plan other than Guaranteed Fraud Protection, 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 {investigationId}, 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.

Example of a successful api call response

  1. // Status Code: 201.
  2. {"investigationId" : 811964631}

Note: InvestigationId has been deprecated and will return the case ID. You can use the investigation ID and case ID interchangeably in any API request.

5. Verify Data Quality

To ensure optimal fraud detection performance, Signifyd analyzes each order for data quality issues. If a data quality issue is detected, the details of the issue and steps to resolve are displayed in the Data Quality page.

Review Data Quality Issues

  1. Submit a case using the Create Case API.
  2. Go to Data Quality and search for the case you created.
  3. Review any data quality issue by clicking the Field Quality button to expand the details pane.
  4. Refer to the Steps to Resolve section to resolve any data quality issues.
  5. Repeat steps 1-4 until all of the issues have been resolved.
Data Quality verification for each team in the Developer Tools web app.

Best Practices

When sending orders for data quality analysis we recommend you mimic your production store's checkout flow, create test orders for every order type you plan to send to Signifyd, and provide as many data points as possible. This will help you identify and resolve technical issues before deploying your integration to your production store.

  • Create test orders for each payment method and payment gateway available on your store (Stripe, PayPal, check, credit card, Apple Pay, gift card, etc.).
  • Create test orders for each order channel available on your store (web, mobile app, social media, marketplace, phone, etc.)
  • If you allow customers to checkout using an online account, place test orders while logged into an account and other orders as a guest.
  • Create test orders using different shipping methods, discount codes types, and products.

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 caseId 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 doc.

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

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 totalPrice is null.
  • A guarantee already exists for a different case with the same order Id and totalPrice.
  • The createdAt for the case is 7 or more days old.
  • The totalPrice < 0.
  • The billing, delivery, or IP geo-location is a sanctioned or embargoed country, region or area as listed by the U.S. Treasury Department's Office of Foreign Assets Control (OFAC).

Wrap Up

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

Next Steps

Was this page helpful?