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 V2 API.
This section of the guide will cover the following steps:
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
- 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 Authorization header with content Basic followed by the encoded API key.
- Provide a content-type of application/json in the header.
Setting up your api key

- $signifyd_api_key = 'YOUR_API_KEY';
You can use the examples below to base64 encode your API key.
BASE64 ENCODE YOUR API KEY

- $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:
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.
2. Map each field you plan to send to Signifyd to the appropriate field in the Create Case request.
Example for field mapping

- $purchase = array();
- $purchase['orderId'] = $this->getId();
- $purchase['createdAt'] = $this->getOrderDate();
- $purchase['paymentGateway'] = $this->getPaymentGatewayStringName();
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 V2 API doc.
4. Order Submission
After you have completed the mapping and transformation steps, you are ready to submit your first order to Signifyd.
Submit an Order for Guarantee
- Get your API key from the Teams page.
- Base64 encode the API key.
- Specify the appropriate request headers, authorization and content-type.
- Call the Create Case 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

- // Status Code: 201.
- {"investigationId" : 811964631}
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
- Submit a case using the Create Case API.
- Go to Data Quality and search for the case you created.
- Review any data quality issue by clicking the Field Quality button to expand the details pane.
- Refer to the Steps to Resolve section to resolve any data quality issues.
- Repeat steps 1-4 until all of the issues have been resolved.
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.
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 V2 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.
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?