Sending Orders

Submitting Order for Guarantee

Depending on whether you’ve elected to submit orders to Signifyd for guarantee pre or post authorization, the requests you make will be slightly different.

👍

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.

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

📘

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 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 SUCCESSFUL API CALL RESPONSE

// Status Code: 201.
{
  "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.

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 250 milliseconds and then try again.
• If the 2nd request fails, wait 500 milliseconds 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 returned 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).