Skip to content

Integration Guide

SDKs & Libraries

V3 API Reference

Sending Orders

Overview

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

This section of the guide will cover the following steps:

  1. Submitting Order for Guarantee >
  2. Handling Errors >

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.

PRE-AUTH

POST-AUTH
1 Call the Checkout API after the order has been submitted but before the transaction is sent to your processor for payment authorization.  To maintain sub-second SLAs at checkout, the Checkout API can only be implemented with synchronous responses. Call the Sale API after the order has been submitted and after the transaction has been authorized by your payment processor.
2 After receiving Signifyd’s guarantee decision, if the recommended action is to ACCEPT the order, you can send the order to your payment processor for authorization.

If the recommended action is to REJECT the order, you should ask the buyer to try a different payment method and resubmit the checkout attempt for review.

 After receiving Signifyd’s guarantee decision, if the recommended action is to ACCEPT the order, you can capture the payment and ship the order.

If the recommended action is to REJECT the order, you should void the payment and cancel the order.
3 Follow up with the Transaction API to provide the transaction details, update or cancel out the order.
4 Provide updates to Signifyd on the fulfillment status of an order using the Fulfillments API. Sending Signifyd this data can help to strengthen our fraud model to help us catch more high-risk orders and will also help our team to fight abusive chargebacks.

Set the order fulfillment status to COMPLETE when an order is completely fulfilled, CANCELED when some or all items in the order have been canceled, etc.

If your API call is successful, you will receive a 201 status code. The checkoutId and/or orderId you specified in the request is the unique identifier for future requests. You should save this ID in your backend application so that you can identify, update or add other resources to the order later.

Note: The signifydId returned in all responses is for internal use only and cannot be used to retrieve or update the order in future requests.

EXAMPLE OF SUCCESSFUL CHECKOUT CALL

  1. // Status Code: 201.
  2. {
  3. "signifydId" : ABCD,
  4. "orderId" : 811964631,
  5. "checkoutId" : 811964631,
  6. …
  7. }

EXAMPLE OF SUCCESSFUL SALE CALL

  1. // Status Code: 201.
  2. {
  3. "signifydId" : ABCD,
  4. "orderId" : 811964631,
  5. …
  6. }

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 createdAt for the order is 7 or more days old.
  • The 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: verifying data quality.

Next Steps

Was this page helpful?

TABLE OF CONTENTS

Overview
Submitting Order for Guarantee
Handling Errors
Wrap Up
Next Step