Start a conversation

Signifyd API

INTRODUCTION


This doc will show you how to use our REST API to authenticate, make requests, and retrieve data. All responses to and from the API will be in JSON.

Authentication

API calls must be made over HTTPS. You authenticate to the API by providing your API key in each request. Your API key can be found on the settings page.

  • Authentication: HTTP Basic Auth.

  • Username: Your API key as the basic auth username.

  • Password: You do not need to provide a password. However, some REST clients expect a username:password pair separated by a colon. If so, you can use a colon as the password.

REST Client

Our API docs include a built-in REST console you can use to interactively test the API. Each endpoint is configured with example request data that will produce a successful result from our API if you provide valid credentials. By default, the API key in the REST console is abcdefghijklmnopqrstuvwxyz which appears in it's base64 encoded form, YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXo6. You must replace this with you own base64 encoded API key in the headers section of the console to successfully submit requests.

Response Codes

We use conventional HTTP response codes to indicate success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information (e.g. a required parameter was missing, a charge failed, etc.), and codes in the 5xx range indicate an error with Signifyd's servers.

Code Description
200 Success. Request completed.
201 Success. New resource created.
204 Success. No content to return. Only the status code returns.
400 Bad Request - The request could not be parsed.
401 Unauthorized - user is not logged in, could not be authenticated.
403 Forbidden - Cannot access resource.
404 Not Found - resource doesn't exist.
409 Conflict - with state of the resource on server. Can occur with (too rapid) PUT requests.
5xx Server error.

Error Messages

There are two types of errors returned by the API server in the bodies of 4xx and 5xx responses:

  • Field-specific errors

  • General error messages

This is our standard format:

{
  "errors": {
    "fieldName":[
      "Field-specific error message, e.g., fieldName is not a valid email address."
    ]
  },
  "messages": [
    "General error message."
  ]
}

Dates

Our API uses the ISO8601 date format for complete date plus hours, minutes, seconds and timezone offset.

         yyyy-MM-dd'T'HH:mm:ssZ
For UTC: 2015-11-03T13:21:58+00:00
For PST: 2015-11-03T13:21:58-08:00

For more information about your specific programming language, please view this document.

REFERENCE

Cases

Resources related to cases in the API.

Create a Case


To send Signifyd an order for review you'll need to create a case. If you are on a complete plan this will also automatically submit the order for guarantee.

For the best decision results we recommend sending as much data as you have available. We have labeled fields as required if we believe they are necessary to provide a more accurate decision.


POST

 Create a Case (click to follow instructions) 

Retrieve a Case


Endpoint for retrieving individual cases by investigation id, the unique case identifier returned when creating a case.


GET 

Get a Case (click & follow instructions) 

Parameters

  • caseId

    The unique identifier for the case that you want to retrieve. This identifier is issued upon case creation.

    Example: 44.


    Integer

Guarantees

Submit Guarantee

A case can be manually submitted for Guarantee. This is equivalent to clicking the Guarantee button in the case console. Note that you have 7 days from the order date to submit a case for Guarantee.


POST  

Create guarantee (click & follow instructions

Cancel Guarantee

A Guarantee can be canceled for orders that no longer require a guarantee fraud protection. Example: Your customer cancels the order and you issue a refund, you run out of stock for the ordered item, or you cancel the order. This is equivalent to clicking the “cancel guarantee request” button in the case console. Before canceling a guarantee request you should check the Guarantee Disposition using GET a Case. In some instances the Guarantee may have a declined decision, in which case it does not need to be cancelled.

PUT

Cancel Guarantee (click & follow instructions)

Parameters

  • caseId

    The id for the case whose guarantee is being cancelled.

    Example: 44.


    Integer

Webhooks


Webhooks are messages sent by SIGNIFYD via HTTP POST to a url you configure on your Notifications page in the SIGNIFYD settings. Webhook messages are sent when certain events occur in the life of an investigation. They allow your application to receive pushed updates about a case, rather than poll SIGNIFYD for status changes.

Supported Events

You can create webhooks in Signifyd for the following events. Each event has a corresponding topic identifier which will be sent in the X-SIGNIFYD-TOPIC header of the webhook.

Currently the Case Creation, Case Rescore, Case Review and Guarantee Completion events can trigger a webhook.

Event X-SIGNIFYD-TOPIC Description
Case Creation cases/creation Sent immediately after a case is created
Case Rescore cases/rescore Sent anytime a case is scored following case creation
Case Review cases/review Sent anytime a user assigns a case a Review Disposition (thumbs up/down on console)
Guarantee Completion guarantees/completion Sent anytime a guarantees decision is made on a case

Webhook Response

{
    analysisUrl: "https://signifyd.com/v2/cases/1/analysis",
    entriesUrl: "https://signifyd.com/v2/cases/1/entries",
    notesUrl: "https://signifyd.com/v2/cases/1/notes",
    orderUrl: "https://signifyd.com/v2/cases/1/order",
    guaranteeEligible: false,
    status: "DISMISSED",
    uuid: "709b9107-eda0-4cdd-bdac-a82f51a8a3f3",
    headline: "John Smith",
    reviewDisposition: null,
    associatedTeam: {
        teamName: "anyTeam",
        teamId: 26,
        getAutoDismiss: true,
        getTeamDismissalDays: 2 },
    orderId: "19418",
    orderDate: "2013-06-17T06:20:47-0700",
    orderAmount: 365.99,
    createdAt: "2013-11-05T14:23:26-0800",
    updatedAt: "2013-11-05T14:23:26-0800",
    investigationId: 1,
    score: 262,
    caseId: 1,
    guaranteeDisposition: "APPROVED"
}

Verification

To allow a client to verify a webhook message has in fact 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. To verify the authenticity of the webhook message, you should calculate this value yourself and verify it equals the value contained in the header.

See this example code snippet for an example of how to compute the value in Java.

Testing a Webhook

Once a webhook is configured, a test POST can be sent by selecting the Test button next to the desired webhook in the Signifyd console settings. The test webhook message is sent with an HMAC SHA256 verification header (see Webhook Verification below). The header value is the Base64 encoded output of the HMAC SHA256 encoding of the test webhook JSON body, using the team API key when available. The test webhook message uses the secret key ABCDE. A 'cases/test' topic header is also sent with the test POST.

Webhooks are messages sent by Signifyd via HTTP POST to endpoint designated using the calls detailed below. Webhook messages are sent when certain events occur in the life of an investigation. They allow the client application to receive pushed updates about a case, rather than poll Signifyd for status changes. Only one URL may be specified per event, though there is no reason the same URL couldn't be used for all events, using the topic header to determine what kind of event was sent.


Manage a Webhook


POST

Create (click & follow instructions) 

Parameters

  • hookId

    Signifyd generated id for the given webhook. These are available when webhooks are first created or when listing webhooks.

    Example: 4660.


    Number


Create a single webhook event for a team.


PUT

Update (click & follow instructions)

Replace the URL for an existing webhook identfied by its numeric id.


DELETE

Delete (click & follow instructions) 

Delete an existing webhook identified by its numeric id.

Manage Webhooks


POST

Create (click & follow instructions) 

Create multiple webhooks events for a team.


PUT

Update (click & follow instructions) 

Update existing webhook events for a team en masse, overwriting existing topics with new URLs. Existing webhooks whose events were not specified in the request will remain intact.


GET

List (click & follow instructions) 

Retrieve a list of the current webhooks for a team identified by the API key used.

Device Fingerprint


Signifyd’s device fingerprinting solution uniquely tracks and identifies devices used to transact on your site, increasing your protection from fraud.

1. Install the Javascript snippet

Place the following script just before the closing </head> tag on all public facing pages. The script loads asynchronously and does not affect page load time.

Note: We recommend that you load the script on all public user facing pages. If you are unable to load the script on pages such as payment, login, etc, make sure to have loaded the script at least once before the checkout process is complete.

<script
async
type="text/javascript"
id="sig-api"
data-order-session-id="YOUR-SESSION-ID-HERE"
src="https://cdn-scripts.signifyd.com/api/script-tag.js"></script>

2. Provide a unique session id

Replace data-order-session-id with a unique session id for the current user's browsing session.

3. Send the session id on case creation

After an order is created on your website you will need to add the value you used for data-order-session-id to the body of the API POST request to, https://api.signifiyd.com/v2/cases under the purchase object:

// Create a Case
// POST https://api.signifyd.com/v2/cases
// Body
{
    "purchase": {
        "orderSessionId": "YOUR-SESSION-ID-HERE",
        "browserIpAddress": "192.168.1.1",
        "orderId": "4fj58as",
        "createdAt": "2016-07-11T17:54:31-05:00",
        "paymentGateway": "stripe",
        "paymentMethod": "credit_card",
        "transactionId": "1a2sf3f44f21s1",
        "currency": "USD",
       …
    }
}

View the create a case docs for additional information on creating cases.

Testing the Signifyd device fingerprinting script

During testing you may want to confirm that the Signifyd device fingerprinting script is working correctly. To do so you can call the SIGNIFYD_GLOBAL.scriptTagHasLoaded() method which will return a boolean true|false value.

Note - we have namespaced all of the device fingerprinting methods under the SIGNIFYD_GLOBAL object to avoid potential naming conflicts.

Choose files or drag and drop files
Was this article helpful?
Yes
No
  1. Mo Sahlah (Signifyd)

  2. Posted

Comments