Signifyd API (3.0)

Download OpenAPI specification:Download

Implementations Team: support@signifyd.com

Introduction

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

If you are a Signifyd customer and would like to access Enterprise API documentation, please log in here and navigate to the Resource Center within Developer Tools.

Versioning

Documentation for the now deprecated Signifyd V2 APIs can be found here.

We only update the version of our API when a non backwards-compatible change is made. Signifyd considers the following changes to be backwards-compatible:

  • Adding new optional request parameter(s) to an existing API endpoint.
  • Adding a new value to an enum field.
  • Adding new fields to existing API responses.
  • Changing the order of fields in an existing API response.
  • Adding a brand new API resource.
  • Adding a new webhook event. Your integration should handle unfamiliar webhook events gracefully.
  • Changing the length of UUIDs (though we don't change lengths that often!).
  • Changing the format of error messages, and other human readable strings.

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, invalid syntax, 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.
202 Success - The request has been accepted, but not yet processed.
204 Success - No content to return.
400 Bad Request - The request could not be parsed, generally due to bad syntax.
401 Unauthorized - The request could not be authenticated due to missing or invalid credentials.
403 Forbidden - You do not have permission to access to the resource.
404 Not Found - The resource doesn't exist.
409 Conflict - The with state of the resource on server. Can occur with (too rapid) PUT requests.
429 The request was not accepted because the application has exceeded the rate limit.
500 Internal Server Error - An internal error occurred in Signifyd.
503 Service Unavailable - The server is currently unavailable. Check the status page for reported outages.
504 Gateway Timeout - The request could not complete in time.

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

Required vs Needed

If a parameter is marked as required, it means the API call will fail with a 400 status code if the parameter is not included in the request. If a parameter is marked as needed, it means you must provide the value if you can. The request will not fail if you do not provide a needed parameter because there are varied user flows, and the data may not always be available for every flow. Before going live, however, our implementations team will validate that needed parameters are always provided in relevant buyer flows.

Authentication

Server-Side-Auth

All server-side API requests must be made over HTTPS using a base64 encoded API key. You can generate an API key by creating a team in 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.
Security Scheme Type: HTTP
HTTP Authorization Scheme: basic

Device Fingerprinting

Signifyd’s device fingerprinting solution uniquely tracks and identifies devices and behaviors used by customers and criminals that are attempting transactions on your site. If your integration includes a mobile application (iOS or Android), testing will need to be coordinated with Signifyd during implementation.

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.

We recommend that you load the script on all public user-facing pages. If you are unable to load the script on all pages you must load the script on the page Signifyd is evaluating (meaning a login, checkout, or return page as relevant).

<script
defer
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 checkout. We recommend appending with a Signifyd Team ID number if you have multiple teams.

A new session id should be set after each successful checkout event or after 24 hours and must be formatted as follows:

  • Less than 128 characters long
  • Upper and lowercase English letters (a-z, A-Z)
  • Digits (0-9)
  • Underscore (_)
  • Hyphen (-)

3. Send the session id on event completion

After an event (e.g.: a login, an order, a return) is completed 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 the corresponding API under the device object:

// Create an Order
// https://api.signifyd.com/v3/orders/events/sales
// Body
{
  "device": {
    "clientIPAddress": "192.168.1.1",
    "sessionID": "YOUR-SESSION-ID-HERE",}
}

View the checkout or sale docs for additional information on creating orders.

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 may open the dev tools on your browser and check that sigScriptLoader.isInitialized is set to true.

Listening for error events

When an issue occurs within the Signifyd device fingerprinting script an error message is displayed in the browsers developer console tab. You may also want the ability to be aware of this within your application or perform an action when an error happens.

The Signifyd device fingerprinting script dispatches an event whenever an error occurs that can be received by the invoking application. The event type is sigScriptError and this can be listened for via an event listener to handle the outcome of an error being raised.

Below is an example of listening for the error event:

<script>
  document.addEventListener('sigScriptError', function (error) {
    // Logic that happens whenever error occurs within Signifyd device fingerprinting script
    // Details of error can be found in error.detail
    console.log('Error details: ', error.detail)
  })
</script>

Checkout

Use the Checkout APIs if you're executing a PreAuth flow where you call into Signifyd before authorizing a payment with your Payment Gateway. For each Order, you will make at least 2 API calls, a Checkout call prior to payment authorization and a Transaction after authorization. If you prefer to execute a PostAuth flow, see the Sale API.

Checkout

To create an Order in the Signifyd system in a PreAuth flow, you need to record a Checkout Event. A checkout event represents the completion of a purchase flow by a buyer. This call should be instrumented before you call your Payment Gateway. Following the call to your gateway, you must complete the Checkout with a call to Transaction.

If a past checkout event has been received and it had the same orderId as this one, then the entire Order will be updated to reflect the new details. If you would like to do a partial update, there are other events to accomplish that.

Orders can be updated a maximum of 100 times for a new decision. Any updates following the 100th update will result in a decision.checkpointAction value of REJECT.

Policies for this event can be instrumented in Decision Center at the Checkout checkpoint.

Authorizations:
Server-Side-Auth
header Parameters
SIGNIFYD-TEAM-ID
integer <int64>
Example: 789123

The team id requested for authentication. This should normally be omitted, as it's only relevant when auth credentials allow requests for multiple teams.

Request Body schema: application/json
checkoutId
required
string (CheckoutId)

Unique identifier for a checkout.

object (Device)

Data about the device that was used by the user to complete the actions.

object (MerchantPlatform)

Details about the merchant's commerce platform.

object (SignifydClient)

For internal use only. Provides Signifyd details about the Signifyd plugin that a merchant is using.

Array of PreAuthCardTransaction (object) or PreAuthBankTransaction (object) or PreAuthPayPalTransaction (object) or PreAuthGenericTransaction (object) (PreAuthTransactions)

A list of payment authorizations that will be attempted to pay for the order.

additionalEvalRequests
Array of strings (AdditionalEvalRequests)
Items Value: "SCA_EVALUATION"

The types of additional evaluations requested. If no additional evaluation object is provided or is empty, additional evaluation will not take place. For further information please contact your Signifyd Implementation Manager.

  • SCA_EVALUATION - Use when you want SCA exemption and exclusion evaluation.
decisionMechanism
string (DecisionMechanism)
Default: "SIGNIFYD_RECOMMENDATION"
Enum: "POLICY_ONLY_ACCEPT" "SIGNIFYD_RECOMMENDATION"

This field specifies how the decision returned in the decision field will be made.

  • POLICY_ONLY_ACCEPT - use when you only want to apply your Decision Center policies to determine the decision with no recommendation provided by Signifyd. If no policy fires, the returned decision.checkpointAction will be ACCEPT. This value can only be used when the request's coverageRequests value is set to NONE.
  • SIGNIFYD_RECOMMENDATION - Use when you would like Signifyd's Model recommendation to be the default decision.checkpointAction. Your Decision Center policies will still run and potentially override the Signifyd recommendation.
orderId
required
string (OrderId)

Unique identifier for an Order. This id must match the orderId used for the original Checkout or Sale request.

required
object (Purchase)

Details about the products that were purchased and how the purchase was made.

object (UserAccount)

Data about the user's account with you, the merchant or service provider.

Array of objects (Membership)

The membership object should be used to indicate the use of a buyer’s rewards, discounts, or admission programs during the purchase. Common uses include but are not limited to, memberships like Costco, Amazon Prime, Walmart+, and Airline Frequent Flyer programs. This object is conceptually distinct from userAccount whose attributes relate to the online account that was used by the buyer to complete the purchase; it's what the buyer "logs in to". You would never login to a "membership".

coverageRequests
Array of strings (CoverageRequests)
Items Enum: "FRAUD" "INR" "SNAD" "ALL" "NONE"

needed The types of coverages requested. If no coverage object is provided or is empty, coverage will be set to the team's default policy. For further information please contact your Signifyd Implementation manager.

  • FRAUD - use when you need a financial guarantee for Payment Fraud.
  • INR - use when you need a financial guarantee for Item Not Received.
  • SNAD - use when you need a financial guarantee for fraud alleging items are Significantly Not As Described.
  • ALL - use when you need a financial guarantee on all chargebacks.
  • NONE - use when you do not need a financial guarantee. Suggested actions in decision.checkpointAction are recommendations.
merchantCategoryCode
string <ISO-18245> (MerchantCategoryCode)

A Merchant Category Code (MCC) is a four-digit number listed in ISO 18245 for retail financial services. An MCC is used to classify every business that accepts card payments by the goods or services it provides. The MCC is provided by payment processors on authorizations.

Array of objects (Seller)

Use only if you operate a marketplace (e.g. eBay) and allow other merchants to list and sell products on the online store. A seller is an online account for the merchant or business that listed and sold the product(s) on the order.

tags
Array of strings

A list of attributes or short descriptors associated with the order.

customerOrderRecommendation
string (customerOrderRecommendation)
Enum: "DECLINE_POLICY" "DECLINE_FRAUD" "APPROVE" "REVIEW" "DECLINE" "MR_APPROVE" "MR_DECLINE_FRAUD" "MR_TIMEOUT"

If you have a legacy risk system independent of Signifyd, use this field to pass us the decision from that system. For declines, use either DECLINE_POLICY or DECLINE_FRAUD whenever possible. DECLINE should only be used if the underlying reason is unknown

Responses

Request samples

Content type
application/json
{
  • "checkoutId": "29bd5784-d3e0-4baa-bd2f-dbb82d90406d",
  • "device": {
    },
  • "merchantPlatform": {
    },
  • "signifydClient": {
    },
  • "transactions": [
    ],
  • "additionalEvalRequests": [
    ],
  • "decisionMechanism": "SIGNIFYD_RECOMMENDATION",
  • "orderId": "XGR-1840823423",
  • "purchase": {
    },
  • "userAccount": {
    },
  • "memberships": [
    ],
  • "coverageRequests": [
    ],
  • "merchantCategoryCode": "1111",
  • "sellers": [
    ],
  • "tags": [
    ],
  • "customerOrderRecommendation": "DECLINE_POLICY"
}

Response samples

Content type
application/json
{
  • "signifydId": 44,
  • "checkoutId": "29bd5784-d3e0-4baa-bd2f-dbb82d90406d",
  • "orderId": "XGR-1840823423",
  • "decision": {
    },
  • "coverage": {
    },
  • "scaEvaluation": {
    }
}

Transaction

The Transaction operation should be performed if you are using a PreAuthorization flow. In that flow, the initial Checkout call to Signifyd occurs before you call your Payment Gateway for Payment Authorization.

After you call your Gateway, perform this Transaction call and pass the complete transaction information. The transactions array passed in this call will completely replace the pre-existing transactions array on the Order. Therefore, you are required to send the data elements sent in the Checkout call, as well as the information gathered after the authorization. This completes the journey of the transaction until another event occurs (such as a void or refund). You will need the associated checkoutId in order to make this Transaction call.

Authorizations:
Server-Side-Auth
header Parameters
SIGNIFYD-TEAM-ID
integer <int64>
Example: 789123

The team id requested for authentication. This should normally be omitted, as it's only relevant when auth credentials allow requests for multiple teams.

Request Body schema: application/json
checkoutId
required
string

Unique identifier for a checkout. This id is used to link these transactions with the original Record Checkout event. It must be supplied to ensure proper linking.

orderId
required
string

Unique identifier for an Order. This is required to link this transaction to the original Order created by the Checkout event.

required
Array of PostAuthCardTransaction (object) or PostAuthBankTransaction (object) or PostAuthPayPalTransaction (object) or PostAuthGenericTransaction (object) (PostAuthTransactions)

A list of payment authorizations that were attempted to pay for the order.

Responses

Request samples

Content type
application/json
{
  • "checkoutId": "29bd5784-d3e0-4baa-bd2f-dbb82d90406d",
  • "orderId": "XGR-1840823423",
  • "transactions": [
    ]
}

Response samples

Content type
application/json
{
  • "signifydId": 44,
  • "checkoutId": "29bd5784-d3e0-4baa-bd2f-dbb82d90406d",
  • "orderId": "XGR-1840823423",
  • "decision": {
    },
  • "coverage": {
    }
}

Sale

Use the Sale API if you're executing a "PostAuth" Flow where you call into Signifyd after the payment has been authorized with your Payment Gateway. If you are executing a "PreAuth" Flow, then use the Checkout APIs.

Sale

To create an Order in the Signifyd system in a PostAuth flow, you record a Sale Event. A Sale event represents the completion of a purchase flow by a buyer as well as a Payment Authorization. If an Order has already been made by a Checkout or Sale event, calling this API again with the same orderID will update all order information and return a new decision.

Policies for this event can be instrumented in Decision Center at the Sale checkpoint.

Authorizations:
Server-Side-Auth
header Parameters
SIGNIFYD-TEAM-ID
integer <int64>
Example: 789123

The team id requested for authentication. This should normally be omitted, as it's only relevant when auth credentials allow requests for multiple teams.

Request Body schema: application/json
orderId
required
string (OrderId)

Unique identifier for an Order. This id must match the orderId used for the original Checkout or Sale request.

required
object (Purchase)

Details about the products that were purchased and how the purchase was made.

object (UserAccount)

Data about the user's account with you, the merchant or service provider.

Array of objects (Membership)

The membership object should be used to indicate the use of a buyer’s rewards, discounts, or admission programs during the purchase. Common uses include but are not limited to, memberships like Costco, Amazon Prime, Walmart+, and Airline Frequent Flyer programs. This object is conceptually distinct from userAccount whose attributes relate to the online account that was used by the buyer to complete the purchase; it's what the buyer "logs in to". You would never login to a "membership".

coverageRequests
Array of strings (CoverageRequests)
Items Enum: "FRAUD" "INR" "SNAD" "ALL" "NONE"

needed The types of coverages requested. If no coverage object is provided or is empty, coverage will be set to the team's default policy. For further information please contact your Signifyd Implementation manager.

  • FRAUD - use when you need a financial guarantee for Payment Fraud.
  • INR - use when you need a financial guarantee for Item Not Received.
  • SNAD - use when you need a financial guarantee for fraud alleging items are Significantly Not As Described.
  • ALL - use when you need a financial guarantee on all chargebacks.
  • NONE - use when you do not need a financial guarantee. Suggested actions in decision.checkpointAction are recommendations.
merchantCategoryCode
string <ISO-18245> (MerchantCategoryCode)

A Merchant Category Code (MCC) is a four-digit number listed in ISO 18245 for retail financial services. An MCC is used to classify every business that accepts card payments by the goods or services it provides. The MCC is provided by payment processors on authorizations.

decisionDelivery
string (DecisionDelivery)
Default: "ASYNC_ONLY"
Enum: "SYNC" "ASYNC_ONLY"

Specify SYNC if you require the Response to contain a decision field. If you have registered for a webhook associated with this checkpoint, then the webhook will also be sent when SYNC is specified. If ASYNC_ONLY is specified, then the decision field in the response will be null, and you will require a Webhook integration to receive Signifyd's final decision.

object (Device)

Data about the device that was used by the user to complete the actions.

object (MerchantPlatform)

Details about the merchant's commerce platform.

object (SignifydClient)

For internal use only. Provides Signifyd details about the Signifyd plugin that a merchant is using.

Array of PostAuthCardTransaction (object) or PostAuthBankTransaction (object) or PostAuthPayPalTransaction (object) or PostAuthGenericTransaction (object) (PostAuthTransactions)

A list of payment authorizations that were attempted to pay for the order.

decisionMechanism
string (DecisionMechanism)
Default: "SIGNIFYD_RECOMMENDATION"
Enum: "POLICY_ONLY_ACCEPT" "SIGNIFYD_RECOMMENDATION"

This field specifies how the decision returned in the decision field will be made.

  • POLICY_ONLY_ACCEPT - use when you only want to apply your Decision Center policies to determine the decision with no recommendation provided by Signifyd. If no policy fires, the returned decision.checkpointAction will be ACCEPT. This value can only be used when the request's coverageRequests value is set to NONE.
  • SIGNIFYD_RECOMMENDATION - Use when you would like Signifyd's Model recommendation to be the default decision.checkpointAction. Your Decision Center policies will still run and potentially override the Signifyd recommendation.
Array of objects (Seller)

Use only if you operate a marketplace (e.g. eBay) and allow other merchants to list and sell products on the online store. A seller is an online account for the merchant or business that listed and sold the product(s) on the order.

tags
Array of strings

A list of attributes or short descriptors associated with the order.

customerOrderRecommendation
string (customerOrderRecommendation)
Enum: "DECLINE_POLICY" "DECLINE_FRAUD" "APPROVE" "REVIEW" "DECLINE" "MR_APPROVE" "MR_DECLINE_FRAUD" "MR_TIMEOUT"

If you have a legacy risk system independent of Signifyd, use this field to pass us the decision from that system. For declines, use either DECLINE_POLICY or DECLINE_FRAUD whenever possible. DECLINE should only be used if the underlying reason is unknown

Responses

Request samples

Content type
application/json
{
  • "orderId": "XGR-1840823423",
  • "purchase": {
    },
  • "userAccount": {
    },
  • "memberships": [
    ],
  • "coverageRequests": [
    ],
  • "merchantCategoryCode": "1111",
  • "decisionDelivery": "ASYNC_ONLY",
  • "device": {
    },
  • "merchantPlatform": {
    },
  • "signifydClient": {
    },
  • "transactions": [
    ],
  • "decisionMechanism": "SIGNIFYD_RECOMMENDATION",
  • "sellers": [
    ],
  • "tags": [
    ],
  • "customerOrderRecommendation": "DECLINE_POLICY"
}

Response samples

Content type
application/json
{
  • "signifydId": 44,
  • "orderId": "XGR-1840823423",
  • "decision": {
    },
  • "coverage": {
    }
}

PostSale

APIs under the PostSale namespace record events that occur after the initial Sale. These events are linked by an orderId, modifying the Order entity that was created in the Sale or Checkout event.

Reprice

This endpoint is designed to enable a merchant to record a change to the price of an order that the buyer did not initiate. For example, the order may need to be revised because the product that the buyer purchased is out-of-stock, and the merchant would like to substitute a new product.

This endpoint allows repricing without a revision to the original decision returned by Signifyd. For example, if the order has both FRAUD and INR coverage for $150, when you call this endpoint to reprice the order to $100, you will retain coverage for FRAUD and INR, but now for $100 instead. Your invoice will also be updated to reflect the new coverage amount.

This endpoint is not designed for buyers modifying their carts -- those events should be recorded as new Checkout events.

Orders can be updated a maximum of 100 times within 14 days of the order being placed. Any updates following the 100th update will result in an HTTP 400 response.

This is a special-access endpoint that must be enabled by your Implementation Manager. The 14-day window can also be extended on a case-by-case basis.

Authorizations:
Server-Side-Auth
header Parameters
SIGNIFYD-TEAM-ID
integer <int64>
Example: 789123

The team id requested for authentication. This should normally be omitted, as it's only relevant when auth credentials allow requests for multiple teams.

Request Body schema: application/json
orderId
required
string (OrderId)

Unique identifier for an Order. This id must match the orderId used for the original Checkout or Sale request.

required
object (Purchase)

Responses

Request samples

Content type
application/json
{
  • "orderId": "XGR-1840823423",
  • "purchase": {
    }
}

Response samples

Content type
application/json
{
  • "signifydId": 44,
  • "orderId": "XGR-1840823423",
  • "coverage": {
    }
}

Reroute

Call this endpoint anytime Delivery Address on an Order needs to be changed. The change will be linked to the original Order with the orderId parameter in the body.

Orders can be updated a maximum of 100 times for a new decision. Any updates following the 100th update will result in an HTTP 400 response.

Authorizations:
Server-Side-Auth
header Parameters
SIGNIFYD-TEAM-ID
integer <int64>
Example: 789123

The team id requested for authentication. This should normally be omitted, as it's only relevant when auth credentials allow requests for multiple teams.

Request Body schema: application/json
orderId
required
string

Unique identifier for the order. This is required to link this Reroute to the original Order created by a Checkout or Sale Event.

object (Device)

Data about the device that was used by the user to complete the actions.

required
Array of objects (Shipment)

Details about the delivery destinations and the products for each one.

Responses

Request samples

Content type
application/json
{
  • "orderId": "XGR-1840823423",
  • "device": {
    },
  • "shipments": [
    ]
}

Response samples

Content type
application/json
{
  • "signifydId": 44,
  • "decision": {
    },
  • "coverage": {
    }
}

Get Decision

Retrieve the latest fraud decision for an order in the Signifyd system.

Authorizations:
Server-Side-Auth
path Parameters
orderId
required
string

the unique identifier for an order

header Parameters
SIGNIFYD-TEAM-ID
integer <int64>
Example: 789123

The team id requested for authentication. This should normally be omitted, as it's only relevant when auth credentials allow requests for multiple teams.

Responses

Response samples

Content type
application/json
{
  • "signifydId": 44,
  • "orderId": "XGR-1840823423",
  • "decision": {
    },
  • "coverage": {
    }
}

Get Decisions

Retrieve the list of decisions associated with an order in the Signifyd system.

Authorizations:
Server-Side-Auth
path Parameters
orderId
required
string

the unique identifier for an order

header Parameters
SIGNIFYD-TEAM-ID
integer <int64>
Example: 789123

The team id requested for authentication. This should normally be omitted, as it's only relevant when auth credentials allow requests for multiple teams.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Fulfillments

Use this endpoint to record a list of fulfillments associated with an Order. All fulfillments passed here will be appended to existing fulfillments. If a fulfillment already exists on the order with any of the provided shipmentIds the entire request will be rejected.

Authorizations:
Server-Side-Auth
header Parameters
SIGNIFYD-TEAM-ID
integer <int64>
Example: 789123

The team id requested for authentication. This should normally be omitted, as it's only relevant when auth credentials allow requests for multiple teams.

Request Body schema: application/json
orderId
required
string

The id that uniquely identifies the order the shipment is for. This should be the same orderId provided when created by Checkout or Sale event.

fulfillmentStatus
string (FulfillmentStatus)
Enum: "PARTIAL" "COMPLETE" "REPLACEMENT" "CANCELED"

Statuses to indicate fulfillment state.

  • PARTIAL - Some of the items in the order have not been shipped.
  • COMPLETE - All of the items in the order have been shipped.
  • REPLACEMENT - A replacement for one of the items in the order has been shipped.
  • CANCELED - For some or all of the items in the order, shipment was canceled.
required
Array of objects (Fulfillment)

A list of fulfillments associated with an order.

Responses

Request samples

Content type
application/json
{
  • "orderId": "string",
  • "fulfillmentStatus": "PARTIAL",
  • "fulfillments": [
    ]
}

Response samples

Content type
application/json
{
  • "orderId": "string",
  • "shipmentIds": [
    ],
  • "coverage": {
    }
}

Return

APIs under the Return namespace record events that represent attempts or executions of returns, exchanges, and/or refunds of an order. These events are linked by an orderId, modifying the Order entity that was created in the Sale or Checkout event. For returns that Signifyd evaluates, there will always be two calls--one for evaluation via the Attempt Return endpoint, and one via the the Execute Return endpoint to let us know what your company decided to do after that. For returns we do not evaluate, there will be no update, as Signifyd is not in the loop, only a single call to the Record Return endpoint.

Attempt Return

Use this endpoint to solicit an evaluation from Signifyd when the customer is requesting a refund, exchange, and/or a return. The response contains the checkpointAction, which will drive any merchant workflow you have configured Note: using this API does NOT cancel any Guarantee associated with the corresponding order investigation. To send Signifyd information about return/refund/exchanges that will not be evaluated, use the Record Return API.

Authorizations:
Server-Side-Auth
header Parameters
SIGNIFYD-TEAM-ID
integer <int64>
Example: 789123

The team id requested for authentication. This should normally be omitted, as it's only relevant when auth credentials allow requests for multiple teams.

Request Body schema: application/json
orderId
required
string

Unique identifier for the order. This is required to link this Attempt Return to the original Order created by a Checkout or Sale event.

returnId
required
string (ReturnId)

Unique identifier for the Attempt Return.

object (Device)

Data about the device that was used by the user to complete the actions.

Array of objects (ReturnProduct)

A list of products that are going to be returned by the buyer.

object (ReplacementItems)
object (AttemptReturnRefund)

Details about the reimbursement that will be issued to the buyer if the attempt return is approved.

object (ReturnInitiator)

Unique identifier for who initiated the return. This will be used if an internal employee initiated the return.

Responses

Request samples

Content type
application/json
{
  • "orderId": "XGR-1840823423",
  • "returnId": "e4056107-6720-431f-a9f4-fe0ff9b6c92a",
  • "device": {
    },
  • "returnedItems": [
    ],
  • "replacementItems": {
    },
  • "refund": {
    },
  • "initiator": {
    }
}

Response samples

Content type
application/json
{
  • "orderId": "XGR-1840823423",
  • "returnId": "e4056107-6720-431f-a9f4-fe0ff9b6c92a",
  • "decision": {
    },
  • "coverage": {
    }
}

Execute Return

Use this endpoint to inform Signifyd of subsequent actions on a return/refund/exchange request that was previously submitted for evaluation via the Attempt Return API. Integration of this endpoint is required if your organization has subscribed to Returns Abuse Prevention coverage from Signifyd.

Authorizations:
Server-Side-Auth
header Parameters
SIGNIFYD-TEAM-ID
integer <int64>
Example: 789123

The team id requested for authentication. This should normally be omitted, as it's only relevant when auth credentials allow requests for multiple teams.

Request Body schema: application/json
orderId
required
string (OrderId)

Unique identifier for an Order. This id must match the orderId used for the original Checkout or Sale request.

returnId
required
string (ReturnId)

Unique identifier for the Attempt Return.

returnStatus
string (ReturnStatus)
Enum: "OPEN" "CANCELED" "REFUNDED" "REPLACED"

The status of the Return. For every update you get to a Return after creation, you can call executeReturn to update the status of the return. If no returnStatus is provided, the default will be OPEN.

  • OPEN - The return has been approved, but not processed.
  • CANCELED - The return has been closed by either the customer or the merchant.
  • REFUNDED - The return request has been processed and refunded.
  • REPLACED - If a return resulted in a new item being sent, the replacement item has been allocated for delivery to the customer.
trackingNumbers
Array of strings

The tracking number(s) for the returned item(s).

refundTransactionId
string

Transaction id for the refund issued for a refund claim.

storeCreditId
string

Id for the store credit issued for a refund claim.

replacementOrderId
string

Unique identifier for the replacement order issued either as a response to a refund claim or as an exchange for a return.

Responses

Request samples

Content type
application/json
{
  • "orderId": "XGR-1840823423",
  • "returnId": "e4056107-6720-431f-a9f4-fe0ff9b6c92a",
  • "returnStatus": "OPEN",
  • "trackingNumbers": [
    ],
  • "refundTransactionId": "f40b4f33-f3ac-42ac-a8d0-0a416a11f1b9",
  • "storeCreditId": "cb6b59f4-e370-4456-8f19-36d0ee20779b",
  • "replacementOrderId": "XGR-fad658a1d4"
}

Response samples

Content type
application/json
{
  • "orderId": "XGR-1840823423",
  • "returnId": "e4056107-6720-431f-a9f4-fe0ff9b6c92a",
  • "coverage": {
    }
}

Record Return

Call this endpoint to record a return, exchanges, cancel a guarantee (within 30 days of order placement) and/or refund that does not need a decision from Signifyd.

Authorizations:
Server-Side-Auth
header Parameters
SIGNIFYD-TEAM-ID
integer <int64>
Example: 789123

The team id requested for authentication. This should normally be omitted, as it's only relevant when auth credentials allow requests for multiple teams.

Request Body schema: application/json
orderId
required
string

Unique identifier for the order. This is required to link this Record Return to the original Order created by a Checkout or Sale event.

returnId
required
string (ReturnId)

Unique identifier for the Attempt Return.

object (Device)

Data about the device that was used by the user to complete the actions.

Array of objects (ReturnProduct)

A list of products that are going to be returned by the buyer.

object (ReplacementItems)
object (AttemptReturnRefund)

Details about the reimbursement that will be issued to the buyer if the attempt return is approved.

object (ReturnInitiator)

Unique identifier for who initiated the return. This will be used if an internal employee initiated the return.

trackingNumbers
Array of strings

The tracking number(s) for the returned item(s).

refundTransactionId
string

Transaction id for the refund issued for a refund claim.

storeCreditId
string

Id for the store credit issued for a refund claim.

replacementOrderId
string

Unique identifier for the replacement order issued either as a response to a refund claim or as an exchange for a return.

Responses

Request samples

Content type
application/json
{
  • "orderId": "XGR-1840823423",
  • "returnId": "e4056107-6720-431f-a9f4-fe0ff9b6c92a",
  • "device": {
    },
  • "returnedItems": [
    ],
  • "replacementItems": {
    },
  • "refund": {
    },
  • "initiator": {
    },
  • "trackingNumbers": [
    ],
  • "refundTransactionId": "f40b4f33-f3ac-42ac-a8d0-0a416a11f1b9",
  • "storeCreditId": "cb6b59f4-e370-4456-8f19-36d0ee20779b",
  • "replacementOrderId": "XGR-fad658a1d4"
}

Response samples

Content type
application/json
{
  • "orderId": "XGR-1840823423",
  • "returnId": "e4056107-6720-431f-a9f4-fe0ff9b6c92a",
  • "coverage": {
    }
}

Return Feedback

Use this endpoint to provide Signifyd with information regarding the quality of a return/refund/exchange (i.e. if it was later discovered to be an "abusive" return or a confirmed "good" return). If your company is currently performing any analysis on the quality of its returns, sending that information via this endpoint will become available to custom policies in created in Signifyd's Decision Center and appear in our Insights dashboards.

Authorizations:
Server-Side-Auth
header Parameters
SIGNIFYD-TEAM-ID
integer <int64>
Example: 789123

The team id requested for authentication. This should normally be omitted, as it's only relevant when auth credentials allow requests for multiple teams.

Request Body schema: application/json
orderId
required
string (OrderId)

Unique identifier for an Order. This id must match the orderId used for the original Checkout or Sale request.

returnId
required
string (ReturnId)

Unique identifier for the Attempt Return.

Array of objects (ReturnProduct)

A list of products that are going to be returned by the buyer.

returnOutcome
required
string (ReturnOutcome)
Enum: "GOOD" "ABUSIVE" "FRAUD"

The outcome of the return once received by your return team.

  • GOOD - the return was accepted and processed.
  • ABUSIVE - the return violates the return policy.
  • FRAUD - the return is fraudulent.
returnOutcomeReason
string (ReturnOutcomeReason)

The reason for the return outcome. Any reason will be accepted, but we strongly recommend mapping to one of the following keys if possible:

  • Used Item
  • Wrong Item
  • Empty Box
  • Missing Items
  • Trash Returned
  • Damaged Item

Responses

Request samples

Content type
application/json
{
  • "orderId": "XGR-1840823423",
  • "returnId": "e4056107-6720-431f-a9f4-fe0ff9b6c92a",
  • "returnedItems": [
    ],
  • "returnOutcome": "ABUSIVE",
  • "returnOutcomeReason": "Used Item"
}

Response samples

Content type
application/json
{
  • "orderId": "XGR-1840823423",
  • "returnId": "e4056107-6720-431f-a9f4-fe0ff9b6c92a",
  • "coverage": {
    }
}

Chargeback

APIs under the Chargebacks namespace record events that represent Chargeback creation and updates

Create Chargeback

To create a chargeback against an Order in the Signifyd system, you need to record a Chargeback Event.

Within this call, Signifyd will create a single claim, along with the chargeback. Any fulfillments sent will be created for the order.

If the chargeback already exists in the Signifyd system, a duplicate chargeback exception will be raised and the chargeback will not be created or updated.

Multiple different chargebacks can be created against an order, dependent on the Signifyd team settings.

The response will contain a summary of the current state of the main Chargeback Case artifacts, namely Chargeback, Claim and Representment Summaries. A representment summary will only be returned if an unassigned representment was created.

According to the Signifyd team settings, an unassigned representment will be created if the team is covered for chargeback recovery or the team has given consent to full access.

Authorizations:
Server-Side-Auth
header Parameters
SIGNIFYD-TEAM-ID
integer <int64>
Example: 789123

The team id requested for authentication. This should normally be omitted, as it's only relevant when auth credentials allow requests for multiple teams.

Request Body schema: application/json
orderId
required
string (OrderId)

Unique identifier for an Order. This id must match the orderId used for the original Checkout or Sale request.

chargebackId
required
string (ChargebackId)

Unique Chargeback id as given by payment processor or merchant. Maximum length of 256 characters.

partnerChargebackId
string (PartnerChargebackId)

Optional field containing a unique Id generated within a partner's system to represent a chargeback case.

required
object (ChargebackCreateRequest)
Array of objects (FulfillmentDetail)

Responses

Request samples

Content type
application/json
{
  • "orderId": "XGR-1840823423",
  • "chargebackId": "MyChargeback-1234",
  • "partnerChargebackId": "PB5CDVPNB6X",
  • "chargeback": {
    },
  • "fulfillments": [
    ]
}

Response samples

Content type
application/json
{
  • "orderId": "XGR-1840823423",
  • "signifydId": 999999,
  • "chargebackCaseSummary": {
    }
}

Representment Outcome

To set the outcome of a Chargeback's Representment in the Signifyd system, you need to record a Representment Outcome Event.

Authorizations:
Server-Side-Auth
header Parameters
SIGNIFYD-TEAM-ID
integer <int64>
Example: 789123

The team id requested for authentication. This should normally be omitted, as it's only relevant when auth credentials allow requests for multiple teams.

Request Body schema: application/json
orderId
required
string (OrderId)

Unique identifier for an Order. This id must match the orderId used for the original Checkout or Sale request.

chargebackId
required
string (ChargebackId)

Unique Chargeback id as given by payment processor or merchant. Maximum length of 256 characters.

partnerChargebackId
string (PartnerChargebackId)

Optional field containing a unique Id generated within a partner's system to represent a chargeback case.

representmentOutcome
required
string (UpdateRepresentmentOutcome)
Enum: "LOST" "WON"

The Representment Outcome indicates the final result of the representment case.

  • LOST - To be used when the chargeback was resolved in favor of the cardholder.
  • WON - To be used when the chargeback was resolved in favor of the merchant.

Responses

Request samples

Content type
application/json
{
  • "orderId": "XGR-1840823423",
  • "chargebackId": "MyChargeback-1234",
  • "partnerChargebackId": "PB5CDVPNB6X",
  • "representmentOutcome": "LOST"
}

Response samples

Content type
application/json
{
  • "orderId": "XGR-1840823423",
  • "signifydId": 999999,
  • "chargebackCaseSummary": {
    }
}

Chargeback Stage

To change the stage of a Chargeback in the Signifyd system, you need to record a Chargeback Stage Event.

As well as changing the Chargeback stage, this Api allows you to optionally also update the Chargeback Amount, Reason and Representment Outcome.

This event must change the stage of a Chargeback. If the request contains the existing stage, then the request will be rejected.

Authorizations:
Server-Side-Auth
header Parameters
SIGNIFYD-TEAM-ID
integer <int64>
Example: 789123

The team id requested for authentication. This should normally be omitted, as it's only relevant when auth credentials allow requests for multiple teams.

Request Body schema: application/json
orderId
required
string (OrderId)

Unique identifier for an Order. This id must match the orderId used for the original Checkout or Sale request.

chargebackId
required
string (ChargebackId)

Unique Chargeback id as given by payment processor or merchant. Maximum length of 256 characters.

partnerChargebackId
string (PartnerChargebackId)

Optional field containing a unique Id generated within a partner's system to represent a chargeback case.

chargebackStage
required
string (ChargebackStage)
Enum: "RETRIEVAL" "CHARGEBACK" "PREARBITRATION" "ARBITRATION" "RECALLED"

The Chargeback Stage refers to the stage within the chargeback dispute lifecycle that the chargeback is in with respect to the payment processor/gateway.

  • RETRIEVAL - To be used when the issuer or the cardholder requests additional information regarding a charge on their card before they request for a credit and it is converted into a chargeback. There is no financial adjustment made at this stage.
  • CHARGEBACK - To be used when the issuing bank initiates the first chargeback on behalf of the cardholder by sending a chargeback notification stating the dispute reason.
  • PREARBITRATION - A pre-arb (pre-arbitration) is a second chargeback. To be used when the merchant challenges the chargeback and the bank initially rules in the merchant's favor, the cardholder can raise a second chargeback.
  • ARBITRATION - The final step that a merchant may encounter in the chargeback process is called arbitration. Arbitration involves the relevant card association stepping in to help resolve the dispute between the acquiring and issuing banks, and by extension the merchant and the cardholder.
  • RECALLED - To be used when the issuer or the cardholder recalls the chargeback. There are no adjustments to chargeback details made at this stage.
object (Amount)

The amount of the transaction and the currency it is within.

object (Reason)

A Payment Processor's view of the reason for the chargeback.

changeRepresentmentOutcome
string (UpdateRepresentmentOutcome)
Enum: "NONE" "LOST" "WON"

The Representment Outcome indicates the final result of the representment case.

  • NONE - To be used when the chargeback was disputed but the outcome is not available, cannot be obtained or was not received.
  • LOST - To be used when the chargeback was resolved in favor of the cardholder.
  • WON - To be used when the chargeback was resolved in favor of the merchant.
issuerReportedDate
string <date-time>

The date on which the issuer reported updating the chargeback stage. Formatted as yyyy-MM-dd'T'HH:mm:ssZ per ISO 8601

dueDate
string <date-time>

The date by which a response to the new chargeback stage is required. Formatted as yyyy-MM-dd'T'HH:mm:ssZ per ISO 8601

object (AssumedOwnership)

Assumed ownership is an optional field passed to Signifyd to provide details about the assumed owning party of the representation rights upon creation of the chargeback case. This field will be ignored unless the caller is a Signifyd partner.

Responses

Request samples

Content type
application/json
{
  • "orderId": "XGR-1840823423",
  • "chargebackId": "MyChargeback-1234",
  • "partnerChargebackId": "PB5CDVPNB6X",
  • "chargebackStage": "RETRIEVAL",
  • "changeAmount": {
    },
  • "changeReason": {
    },
  • "changeRepresentmentOutcome": "NONE",
  • "issuerReportedDate": "2019-08-24T14:15:22Z",
  • "dueDate": "2019-08-24T14:15:22Z",
  • "assumedOwnership": {
    }
}

Response samples

Content type
application/json
{
  • "orderId": "XGR-1840823423",
  • "signifydId": 999999,
  • "chargebackCaseSummary": {
    }
}

Create Early Alert

To create an early alert against an order in the Signifyd system, you need to record an Early Alert Event.

Authorizations:
Server-Side-Auth
header Parameters
SIGNIFYD-TEAM-ID
integer <int64>
Example: 789123

The team id requested for authentication. This should normally be omitted, as it's only relevant when auth credentials allow requests for multiple teams.

Request Body schema: application/json
alertProviderReferenceId
required
string (AlertProviderReferenceId)

Unique reference associated with the early alert by the provider and maintained throughout the life cycle of the transaction.

required
object (Amount)

The amount of the transaction and the currency it is within.

cardBin
required
integer (CardBin)

Card Bank Identification Number

merchantName
required
string (MerchantName)

Name of the merchant associated with this early alert

orderId
required
string (OrderId)

Unique identifier for an Order. This id must match the orderId used for the original Checkout or Sale request.

alertName
string (AlertName)

Provider’s name for the early alert.

alertProviderReportedDate
string <date-time>

The date on which the early alert was reported by the provider. Formatted as yyyy-MM-dd'T'HH:mm:ssZ per ISO 8601

alertInitiatedBy
string (AlertInitiatedBy)
Enum: "ISSUER" "CARDHOLDER" "NOT_AVAILABLE"

Whether the transaction was initially identified by the card holder or the card issuer.

  • ISSUER - This indicates that an alert was initiated by the issuer.
  • CARDHOLDER - This indicates that an alert was initiated by the cardholder.
  • NOT_AVAILABLE - When the initiator is unknown or unavailable.
cardholderEmail
string (CardholderEmail)

Email address for the cardholder

cardholderName
string (CardholderName)

Name associated with the cardholder

merchantId
string (MerchantId)

The merchant account identifier used in the transaction the alert is for.

mcc
string <ISO-18245> (MerchantCategoryCode)

A Merchant Category Code (MCC) is a four-digit number listed in ISO 18245 for retail financial services. An MCC is used to classify every business that accepts card payments by the goods or services it provides. The MCC is provided by payment processors on authorizations.

cardScheme
string (CardScheme)

Card scheme linked to payment card

issuer
string (Issuer)

The name of the card issuer

transactionId
string (TransactionId)

Unique value assigned by the card scheme (VISA/Mastercard, etc.) to each transaction on the Authorization and maintained throughout the life cycle of the transaction.

arn
string (Arn)

Acquirer Reference Number assigned to the transaction

alertReasonCode
integer (AlertReasonCode)

The card scheme-specific chargeback reason code which indicates the cardholder’s reason for disputing the transaction.

alertReasonDescription
string (AlertReasonDescription)

Description of the alert reason

alertOutcome
string (AlertOutcome)

The outcome for the alert.

Responses

Request samples

Content type
application/json
{
  • "alertProviderReferenceId": "BPXQX21TJ18WORG8",
  • "amount": {
    },
  • "cardBin": 400344,
  • "merchantName": "Samsung",
  • "orderId": "XGR-1840823423",
  • "alertName": "NOTIFICATION_OF_FRAUD",
  • "alertProviderReportedDate": "2019-08-24T14:15:22Z",
  • "alertInitiatedBy": "CARDHOLDER",
  • "cardholderEmail": "name@example.com",
  • "cardholderName": "John Smith",
  • "merchantId": "SomeCompany_ECom",
  • "mcc": "1111",
  • "cardScheme": "visa",
  • "issuer": "Capital One",
  • "transactionId": "A9Y2X01TI18POAG7",
  • "arn": "arn1665059145275",
  • "alertReasonCode": 5,
  • "alertReasonDescription": "Fraudulent Use of Account Number",
  • "alertOutcome": "RESOLVED"
}

Response samples

Content type
application/json
{
  • "orderId": "XGR-1840823423",
  • "signifydId": 999999
}

WebhookEvents

Webhooks are a way for a merchant to receive Signifyd decisions asynchronously. Signifyd will push the notification to the merchant, allowing them to continue processing based on the decision contained within.

Webhook verification

To allow a client to verify a webhook message has in fact come from Signifyd, an 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. Here's an example of how to compute the Json body as an HMAC encoded value in Java.

Mac sha256HMAC = javax.crypto.Mac.getInstance("HmacSHA256");
SecretKeySpec secretKey = new SecretKeySpec(teamAPIKEY.getBytes(), "HmacSHA256");
sha256HMAC.init(secretKey);
String encodedHMAC256 = Base64.encodeBase64String(sha256HMAC.doFinal(jsonBody.getBytes("UTF-8")));

Order Checkpoint Action Update Webhook

header Parameters
SIGNIFYD-TOPIC
required
string (topic)
Value: "ORDER_CHECKPOINT_ACTION_UPDATE"
SIGNIFYD-CHECKPOINT
required
string (Checkpoint)
Enum: "MERCHANT_REVIEW" "SIGNIFYD_REVIEW" "CHECKOUT" "TRANSACTION" "SALE" "REROUTE"


* MERCHANT_REVIEW - Sent any time a user assigns a case a Review Disposition (thumbs up/down on console)
* SIGNIFYD_REVIEW - Sent any time a decision is made by Signifyd agent on a case
* CHECKOUT - Sent any time a decision is made in response to a checkout event
* SALE - Sent any time a decision is made in response to a sale event
* TRANSACTION - Sent any time a decision is made in response to a transaction event
* REROUTE - Sent any time a decision is made in response to a reroute event

SIGNIFYD-SEC-HMAC-SHA256
required
string

To allow a client to verify a webhook message has in fact come from SIGNIFYD, an 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.

Request Body schema: application/json
signifydId
required
integer <int64> (signifydId)

Signifyd's unique ID for this event.

orderId
required
string

Unique identifier for the order. You should retain the value so you can retrieve summary information about the order later.

object or null (DecisionResponse)

Signifyd's Decision for this event. Populated only when decisionDelivery is set to "SYNC". Otherwise will be null and you will require a webhook integration to receive Signifyd's final decision.

object or null (Coverage)

Details about the coverage Signifyd will cover on each type of claim.

Responses

Request samples

Content type
application/json
{
  • "signifydId": 44,
  • "orderId": "XGR-1840823423",
  • "decision": {
    },
  • "coverage": {
    }
}

WebhookManagement

Use the Webhooks APIs to create and manage the subscriptions to the webhooks defined above.

Create Webhook

Create a new webhook. This will add to the list of any existing webhooks.
The webhook endpoint must use SSL with either TLSv1.2 or TLSv1.3 protocols.
Cipher Suites currently supported are:

  • TLS_AES_128_GCM_SHA256
  • TLS_AES_256_GCM_SHA384
  • TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
  • TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
  • TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
  • TLS_ECDH_ECDSA_WITH_AES_256_GCM_SHA384
  • TLS_ECDH_RSA_WITH_AES_256_GCM_SHA384
  • TLS_DHE_RSA_WITH_AES_256_GCM_SHA384
  • TLS_DHE_DSS_WITH_AES_256_GCM_SHA384
  • TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
  • TLS_ECDH_ECDSA_WITH_AES_128_GCM_SHA25
  • TLS_ECDH_RSA_WITH_AES_128_GCM_SHA256
  • TLS_DHE_RSA_WITH_AES_128_GCM_SHA256
  • TLS_DHE_DSS_WITH_AES_128_GCM_SHA256

NOTE: You can create more than one webhook per topic.
Authorizations:
Server-Side-Auth
path Parameters
teamId
required
integer <int64>
Example: 567890

Signifyd's unique identifier for the team

Request Body schema: application/json
url
required
string <uri> (url)

The URL to which the webhook data should be sent when the event is triggered.

Responses

Request samples

Content type
application/json

Response samples

Content type
application/json
{}

Get Webhooks

Get the list of webhooks for a team. If the user belongs to the team with the given teamId or has sufficient privileges to access the team webhooks, a list of webhooks for that team will be returned.

Authorizations:
Server-Side-Auth
path Parameters
teamId
required
integer <int64>
Example: 567890

Signifyd's unique identifier for the team

Responses

Response samples

Content type
application/json
[]

Update Webhook

Replaces an existing webhook identified by the hookId.

Authorizations:
Server-Side-Auth
path Parameters
teamId
required
integer <int64>
Example: 567890

Signifyd's unique identifier for the team

hookId
required
string
Example: 00071eb8-468c-4176-b7cc-dc2876ee6b4f

Signifyd's unique identifier for the webhook.

Request Body schema: application/json
url
required
string <uri> (url)

The URL to which the webhook data should be sent when the event is triggered.

Responses

Request samples

Content type
application/json

Response samples

Content type
application/json
{}

Delete Webhook

Deletes an existing webhook identified by the hookId.

Authorizations:
Server-Side-Auth
path Parameters
teamId
required
integer <int64>
Example: 567890

Signifyd's unique identifier for the team

hookId
required
string
Example: 00071eb8-468c-4176-b7cc-dc2876ee6b4f

Signifyd's unique identifier for the webhook.

Responses

Response samples

Content type
application/json
{
  • "messages": [
    ],
  • "traceId": "891f2e31d267dde",
  • "errors": {
    }
}

Signups

APIs under the Signups namespace record events that represent attempts to create a new user account in your system.

Signup

Record a Signup attempt in the Signifyd system. This event should be instrumented each time a user attempts to Signup to your system. The call to Signifyd should come after the sign up event and the account was already created on your system. All Signup attempts should be recorded. Signifyd will return a response indicating if the user should be allowed to proceed with the Signup.

Authorizations:
Server-Side-Auth
header Parameters
SIGNIFYD-TEAM-ID
integer <int64>
Example: 789123

The team id requested for authentication. This should normally be omitted, as it's only relevant when auth credentials allow requests for multiple teams.

SIGNIFYD-TEST-DECISION-RESPONSE
string
Enum: "ACCEPT" "CHALLENGE" "REJECT"

The decision response requested for testing API integrations. This should normally be omitted, as it's only relevant when testing API integration with Signifyd.

Request Body schema: application/json
required
object (PostSignupAccount)

An object containing information about the user signing up for the account

required
object (Device)

Data about the device that was used by the user to complete the actions.

identityProvider
string (IdentityProvider)

The name of the entity that is administering this authentication factor and identity. Any name will be accepted, but we strongly recommend mapping to one of the following keys if possible:

  • DIRECT - if this method of authentication is directly administered by you, not a third-party.
  • FACEBOOK - If the user signed in with "Sign-In with Facebook"
  • GOOGLE - If the user signed in with "Sign-In with Google"
  • MICROSOFT - If the user signed in with "Sign-In with Microsoft"
  • LINKEDIN - If the user signed in with "Sign-In with LinkedIn"
  • APPLE - If the user signed in with "Sign-In with Apple"
  • TWITTER - If the user signed in with "Sign-In with Twitter"
  • AMAZON - If the user signed in with "Sign-In with Amazon"

Responses

Request samples

Content type
application/json
{
  • "userAccount": {
    },
  • "device": {
    },
  • "identityProvider": "Facebook"
}

Response samples

Content type
application/json
{
  • "signifydId": 44,
  • "accountNumber": "q49sgfkj49",
  • "decision": {
    }
}

Confirm Account

When you receive an account creation attempt that you deem risky, you will likely want to verify whether the user is who they say they are. If you issue additional account verification or have a manual follow up via your customer service team, you can send us the outcome.

Authorizations:
Server-Side-Auth
header Parameters
SIGNIFYD-TEAM-ID
integer <int64>
Example: 789123

The team id requested for authentication. This should normally be omitted, as it's only relevant when auth credentials allow requests for multiple teams.

Request Body schema: application/json
accountNumber
required
string

Your unique, immutable identifier for the account being verified.

required
Array of EmailVerificationAuthFactor (object) or PhoneNumberVerificationAuthFactor (object) (AccountVerificationAuthFactor)
required
object (Device)

Data about the device that was used by the user to complete the actions.

verificationStart
string <date-time>

Formatted as yyyy-MM-dd'T'HH:mm:ssZ per ISO 8601.
The date and time when the verification was started.

verificationFinish
string <date-time>

Formatted as yyyy-MM-dd'T'HH:mm:ssZ per ISO 8601.
The date and time when the verification was finished.
Must be > verificationStart

Responses

Request samples

Content type
application/json
{
  • "accountNumber": "q49sgfkj49",
  • "factors": [
    ],
  • "device": {
    },
  • "verificationStart": "2020-12-23T13:57:40-0700",
  • "verificationFinish": "2020-12-23T13:59:55-0700"
}

Response samples

Content type
application/json
{
  • "signifydId": 44,
  • "accountNumber": "q49sgfkj49"
}

AccountModifications

APIs under the AccountModifications namespace record events that represent attempts to modify a user account in your system.

Account Modification

Call this end point when a customer makes a change to the saved data in their account.

Authorizations:
Server-Side-Auth
header Parameters
SIGNIFYD-TEAM-ID
integer <int64>
Example: 789123

The team id requested for authentication. This should normally be omitted, as it's only relevant when auth credentials allow requests for multiple teams.

Request Body schema: application/json
modificationId
required
string

A unique identifier for the modification event.

required
object (UserAccount)

Data about the user's account with you, the merchant or service provider.

required
object (Device)

Data about the device that was used by the user to complete the actions.

identityProvider
string (IdentityProvider)

The name of the entity that is administering this authentication factor and identity. Any name will be accepted, but we strongly recommend mapping to one of the following keys if possible:

  • DIRECT - if this method of authentication is directly administered by you, not a third-party.
  • FACEBOOK - If the user signed in with "Sign-In with Facebook"
  • GOOGLE - If the user signed in with "Sign-In with Google"
  • MICROSOFT - If the user signed in with "Sign-In with Microsoft"
  • LINKEDIN - If the user signed in with "Sign-In with LinkedIn"
  • APPLE - If the user signed in with "Sign-In with Apple"
  • TWITTER - If the user signed in with "Sign-In with Twitter"
  • AMAZON - If the user signed in with "Sign-In with Amazon"
originatingUserAgent
string

The originating userAgent for this event.

Responses

Request samples

Content type
application/json
{
  • "modificationId": "e31b770c",
  • "userAccount": {
    },
  • "device": {
    },
  • "identityProvider": "Facebook",
  • "originatingUserAgent": "Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:35.0) Gecko/20100101 Firefox/35.0"
}

Response samples

Content type
application/json
{
  • "signifydId": 44,
  • "accountNumber": "q49sgfkj49",
  • "decision": {
    }
}

Logins

APIs under the Logins namespace record events that represent Authentication Attempts into your system.

RecordLogin

Record a login attempt in the Signifyd system. This event should be instrumented each time a user attempts to log in to your system. The call to Signifyd should come after the attempt is made. Both successful and unsuccessful login attempts should be recorded. Signifyd will return a response indicating if the user should be allowed to proceed with the login.

Authorizations:
Server-Side-Auth
header Parameters
SIGNIFYD-TEAM-ID
integer <int64>
Example: 789123

The team id requested for authentication. This should normally be omitted, as it's only relevant when auth credentials allow requests for multiple teams.

SIGNIFYD-TEST-DECISION-RESPONSE
string
Enum: "ACCEPT" "CHALLENGE" "REJECT"

The decision response requested for testing API integrations. This should normally be omitted, as it's only relevant when testing API integration with Signifyd.

Request Body schema: application/json
loginId
required
string

A unique ID for this login that you can use to retrieve this login event later.

required
Array of objects (AuthFactor)

The factors that were used to authenticate this user.

required
object (Device)

Data about the device that was used by the user to complete the actions.

required
object (UserAccount)

Data about the user's account with you, the merchant or service provider.

orderId
string

The orderId associated with this login attempt, if one exists

result
required
string (LoginResult)
Enum: "SUCCESS" "INVALID_FACTOR" "ACCOUNT_UNKNOWN" "ACCOUNT_SUSPENDED" "ACCOUNT_DISABLED" "MAX_ATTEMPTS_EXCEEDED" "OTP_EXPIRED"

The result of the authentication attempt before Signifyd's evaluation.

  • SUCCESS - User provided a valid auth factor for this account.
  • INVALID_FACTOR - You denied the user access to the account because one of the authentication factors was invalid.
  • ACCOUNT_UNKNOWN - You did not allow the user to proceed with the login because the account does not exist.
  • ACCOUNT_SUSPENDED - You did not allow the user to proceed with the login because the account is disabled due to suspicious behavior.
  • ACCOUNT_DISABLED - You did not allow the user to proceed with the login because the account is disabled due to inactivity.
  • MAX_ATTEMPTS_EXCEEDED - You did not allow the user to proceed with the login because your maximum login attempts threshold has been exceeded.
  • OTP_EXPIRED - You did not allow this user to proceed with the login because the one time password link expired.
originatingUserAgent
string

The user agent for this login attempt, if one exists.

Responses

Request samples

Content type
application/json
{
  • "loginId": "e33febb4-4bb7-4264-8001-504a8d7fc2d7",
  • "factors": [
    ],
  • "device": {
    },
  • "userAccount": {
    },
  • "orderId": "XGR-1840823423",
  • "result": "SUCCESS",
  • "originatingUserAgent": "Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:35.0) Gecko/20100101 Firefox/35.0"
}

Response samples

Content type
application/json
{
  • "signifydId": 44,
  • "loginId": "e33febb4-4bb7-4264-8001-504a8d7fc2d7",
  • "decision": {
    }
}

UpdateChallenge

When you receive a login attempt that may or may not be the account owner, you will want to provide a step-up challenge to verify if the user is the owner of the account. Once you have completed this challenge, the outcome of the challenge should be recorded.

Authorizations:
Server-Side-Auth
header Parameters
SIGNIFYD-TEAM-ID
integer <int64>
Example: 789123

The team id requested for authentication. This should normally be omitted, as it's only relevant when auth credentials allow requests for multiple teams.

Request Body schema: application/json
loginId
required
string

The unique ID for the login attempt you are attempting to verify.

required
Array of objects (AuthFactor)

The factors that were used to authenticate this user.

result
required
string (LoginResult)
Enum: "SUCCESS" "INVALID_FACTOR" "ACCOUNT_UNKNOWN" "ACCOUNT_SUSPENDED" "ACCOUNT_DISABLED" "MAX_ATTEMPTS_EXCEEDED" "OTP_EXPIRED"

The result of the authentication attempt before Signifyd's evaluation.

  • SUCCESS - User provided a valid auth factor for this account.
  • INVALID_FACTOR - You denied the user access to the account because one of the authentication factors was invalid.
  • ACCOUNT_UNKNOWN - You did not allow the user to proceed with the login because the account does not exist.
  • ACCOUNT_SUSPENDED - You did not allow the user to proceed with the login because the account is disabled due to suspicious behavior.
  • ACCOUNT_DISABLED - You did not allow the user to proceed with the login because the account is disabled due to inactivity.
  • MAX_ATTEMPTS_EXCEEDED - You did not allow the user to proceed with the login because your maximum login attempts threshold has been exceeded.
  • OTP_EXPIRED - You did not allow this user to proceed with the login because the one time password link expired.

Responses

Request samples

Content type
application/json
{
  • "loginId": "e33febb4-4bb7-4264-8001-504a8d7fc2d7",
  • "factors": [
    ],
  • "result": "SUCCESS"
}

Response samples

Content type
application/json
{
  • "signifydId": 44,
  • "loginId": "e33febb4-4bb7-4264-8001-504a8d7fc2d7"
}

Partners

A Partner is an entity that is allowed to create Organizations, Teams, and Users in the Signifyd system. If a Partner creates one of these entities, the Partner has full control over it. Users can be added as members with roles to an Organization, Team, or the Partner itself. Team members can access information regarding that Team and have their own level of privilege for a given Team. Organizations are a way of grouping Teams. Organization members can access information for all Teams that belong to that Organization and have a configurable default level of privilege that can be overridden at the level of a specific Team. Partner members can access information for all Teams belonging to all Organizations belonging to the Partner and have a configurable default level of privilege that can be overridden at a lower level.

Get Partner Members

Gets a paginated list of details for all members at the Partner level.

Authorizations:
Server-Side-Auth
path Parameters
partnerId
required
integer <int64>
Example: 123

Signifyd's unique identifier for the partner. This can also accept the placeholder "0" which will automatically populate with your partnerId using your partner credentials via an API.

query Parameters
limit
integer [ 1 .. 100 ]
Default: 50

Specifies the max number of members to return in the response. This should be a positive integer.

offset
integer >= 0
Default: 0
Example: offset=50

Specifies the number of members to skip at the start of the response. This should be a positive integer. Combined with limit, this allows for paging through the members found in the search. Don’t include this parameter on the first call. Use the nextOffset value returned in a previous response to request the next page of members.

Responses

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "hasMore": true,
  • "nextOffset": 50
}

Add Partner Member

Adds a user as a Partner level member. Such members will have access to all Teams belonging to all Organizations belonging to the Partner. Members at Partner level can only be removed at Partner level. The access granted as a Partner Member will supersede any pre-existing access the user had. This includes team and organization access.

Authorizations:
Server-Side-Auth
path Parameters
partnerId
required
integer <int64>
Example: 123

Signifyd's unique identifier for the partner. This can also accept the placeholder "0" which will automatically populate with your partnerId using your partner credentials via an API.

Request Body schema: application/json

Member details

userId
required
integer <int64>

Signifyd's unique identifier for the user.

role
required
string (Role)
Enum: "REVIEWER" "MEMBER" "ADMIN"

The role the member will have on all underlying Teams.

  • REVIEWER - Can view Orders. Can not perform User managment.
  • MEMBER - Can view Orders and cancel guarantee Orders. Can not perform User managment.
  • ADMIN - Has full rights and privileges, can view Orders and perform User managment.

Responses

Request samples

Content type
application/json
{
  • "userId": 123456,
  • "role": "REVIEWER"
}

Response samples

Content type
application/json
{
  • "userId": 123456,
  • "role": "REVIEWER"
}

Update Partner Member

Updates a member at a Partner level. Any fields not specified will not be changed.

Authorizations:
Server-Side-Auth
path Parameters
partnerId
required
integer <int64>
Example: 123

Signifyd's unique identifier for the partner. This can also accept the placeholder "0" which will automatically populate with your partnerId using your partner credentials via an API.

userId
required
integer <int64>
Example: 123456

Signifyd's unique identifier for the user.

Request Body schema: application/json

member details

role
string (Role)
Enum: "REVIEWER" "MEMBER" "ADMIN"

The role the member will have on all underlying Teams.

  • REVIEWER - Can view Orders. Can not perform User managment.
  • MEMBER - Can view Orders and cancel guarantee Orders. Can not perform User managment.
  • ADMIN - Has full rights and privileges, can view Orders and perform User managment.

Responses

Request samples

Content type
application/json
{
  • "role": "REVIEWER"
}

Response samples

Content type
application/json
{
  • "userId": 123456,
  • "role": "REVIEWER"
}

Get Partner Member

Gets the details for a Partner member.

Authorizations:
Server-Side-Auth
path Parameters
partnerId
required
integer <int64>
Example: 123

Signifyd's unique identifier for the partner. This can also accept the placeholder "0" which will automatically populate with your partnerId using your partner credentials via an API.

userId
required
integer <int64>
Example: 123456

Signifyd's unique identifier for the user.

Responses

Response samples

Content type
application/json
{
  • "userId": 123456,
  • "role": "REVIEWER"
}

Remove Partner Member

Removes Partner membership from a user. This will remove the ability for that user to access information regarding all Organizations and Teams that the user is not directly a member of.

Authorizations:
Server-Side-Auth
path Parameters
partnerId
required
integer <int64>
Example: 123

Signifyd's unique identifier for the partner. This can also accept the placeholder "0" which will automatically populate with your partnerId using your partner credentials via an API.

userId
required
integer <int64>
Example: 123456

Signifyd's unique identifier for the user.

Responses

Response samples

Content type
application/json
{
  • "messages": [
    ],
  • "traceId": "891f2e31d267dde",
  • "errors": {
    }
}

Organizations

This entity is a grouping of Teams for Billing purposes.

Create Organization

Creates an Organization. This is an entity used to group related Teams together for billing purposes. For example, if you have merchants that are mapped to Teams, but are billed at a higher entity level you would group them under a single Organization. Teams must belong to an Organization and one must create an Organization in order to create Teams.

Authorizations:
Server-Side-Auth
path Parameters
partnerId
required
integer <int64>
Example: 123

Signifyd's unique identifier for the partner. This can also accept the placeholder "0" which will automatically populate with your partnerId using your partner credentials via an API.

Request Body schema: application/json

Organization details

name
required
string

The name for the Organization.

object (Billing)

The billing details for the Organization

Responses

Request samples

Content type
application/json
{
  • "name": "Initrode",
  • "billing": {
    }
}

Response samples

Content type
application/json
{
  • "orgId": 123456,
  • "name": "Initrode",
  • "billing": {
    }
}

Get Organization

Gets the details for an Organization

Authorizations:
Server-Side-Auth
path Parameters
partnerId
required
integer <int64>
Example: 123

Signifyd's unique identifier for the partner. This can also accept the placeholder "0" which will automatically populate with your partnerId using your partner credentials via an API.

orgId
required
integer <int64>
Example: 123456

Signifyd's unique identifier for the Organization

Responses

Response samples

Content type
application/json
{
  • "name": "Initrode",
  • "billing": {
    }
}

Update Organization

Updates an Organization. Any fields not supplied will not be changed.

Authorizations:
Server-Side-Auth
path Parameters
partnerId
required
integer <int64>
Example: 123

Signifyd's unique identifier for the partner. This can also accept the placeholder "0" which will automatically populate with your partnerId using your partner credentials via an API.

orgId
required
integer <int64>
Example: 123456

Signifyd's unique identifier for the Organization

Request Body schema: application/json

Organization details

name
string

The name for the Organization.

object (Billing)

The billing details for the Organization

Responses

Request samples

Content type
application/json
{
  • "name": "Initrode",
  • "billing": {
    }
}

Response samples

Content type
application/json
{
  • "orgId": 123456,
  • "name": "Initrode",
  • "billing": {
    }
}

Get Organization Members

Gets a paginated list of details for all members at the Organization level.

Authorizations:
Server-Side-Auth
path Parameters
partnerId
required
integer <int64>
Example: 123

Signifyd's unique identifier for the partner. This can also accept the placeholder "0" which will automatically populate with your partnerId using your partner credentials via an API.

orgId
required
integer <int64>
Example: 123456

Signifyd's unique identifier for the Organization.

query Parameters
limit
integer [ 1 .. 100 ]
Default: 50

Specifies the max number of members to return in the response. This should be a positive integer.

offset
integer >= 0
Default: 0
Example: offset=50

Specifies the number of members to skip at the start of the response. This should be a positive integer. Combined with limit, this allows for paging through the members found in the search. Don’t include this parameter on the first call. Use the nextOffset value returned in a previous response to request the next page of members.

Responses

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "hasMore": true,
  • "nextOffset": 50
}

Add Organization Member

Adds a user as an Organization level member. Such members will have access to all Teams belonging to that Organization. Members at Organization level can only be removed at Organization level. The access granted as a Organization Member will supersede any pre-existing team access the user had.

Authorizations:
Server-Side-Auth
path Parameters
partnerId
required
integer <int64>
Example: 123

Signifyd's unique identifier for the partner. This can also accept the placeholder "0" which will automatically populate with your partnerId using your partner credentials via an API.

orgId
required
integer <int64>
Example: 123456

Signifyd's unique identifier for the Organization.

Request Body schema: application/json

Member details

userId
required
integer <int64>

Signifyd's unique identifier for the user.

role
required
string (Role)
Enum: "REVIEWER" "MEMBER" "ADMIN"

The role the member will have on all underlying Teams.

  • REVIEWER - Can view Orders. Can not perform User managment.
  • MEMBER - Can view Orders and cancel guarantee Orders. Can not perform User managment.
  • ADMIN - Has full rights and privileges, can view Orders and perform User managment.

Responses

Request samples

Content type
application/json
{
  • "userId": 123456,
  • "role": "REVIEWER"
}

Response samples

Content type
application/json
{
  • "orgId": 123456,
  • "userId": 123456,
  • "role": "REVIEWER"
}

Update Organization Member

Updates a member at an Organization level. Any fields not specified will not be changed.

Authorizations:
Server-Side-Auth
path Parameters
partnerId
required
integer <int64>
Example: 123

Signifyd's unique identifier for the partner. This can also accept the placeholder "0" which will automatically populate with your partnerId using your partner credentials via an API.

orgId
required
integer <int64>
Example: 123456

Signifyd's unique identifier for the Organization.

userId
required
integer <int64>
Example: 123456

Signifyd's unique identifier for the user.

Request Body schema: application/json

member details

role
string (Role)
Enum: "REVIEWER" "MEMBER" "ADMIN"

The role the member will have on all underlying Teams.

  • REVIEWER - Can view Orders. Can not perform User managment.
  • MEMBER - Can view Orders and cancel guarantee Orders. Can not perform User managment.
  • ADMIN - Has full rights and privileges, can view Orders and perform User managment.

Responses

Request samples

Content type
application/json
{
  • "role": "REVIEWER"
}

Response samples

Content type
application/json
{
  • "orgId": 123456,
  • "userId": 123456,
  • "role": "REVIEWER"
}

Get Organization Member

Gets the details for an Organization member.

Authorizations:
Server-Side-Auth
path Parameters
partnerId
required
integer <int64>
Example: 123

Signifyd's unique identifier for the partner. This can also accept the placeholder "0" which will automatically populate with your partnerId using your partner credentials via an API.

orgId
required
integer <int64>
Example: 123456

Signifyd's unique identifier for the Organization.

userId
required
integer <int64>
Example: 123456

Signifyd's unique identifier for the user.

Responses

Response samples

Content type
application/json
{
  • "orgId": 123456,
  • "userId": 123456,
  • "role": "REVIEWER"
}

Remove Organization Member

Removes Organization membership from a user. This will remove the ability for that user to access information regarding all Teams belonging to the Organization.

Authorizations:
Server-Side-Auth
path Parameters
partnerId
required
integer <int64>
Example: 123

Signifyd's unique identifier for the partner. This can also accept the placeholder "0" which will automatically populate with your partnerId using your partner credentials via an API.

orgId
required
integer <int64>
Example: 123456

Signifyd's unique identifier for the Organization.

userId
required
integer <int64>
Example: 123456

Signifyd's unique identifier for the user.

Responses

Response samples

Content type
application/json
{
  • "messages": [
    ],
  • "traceId": "891f2e31d267dde",
  • "errors": {
    }
}

Teams

Typically equates to a single merchant. Orders are submitted to Signifyd under that Team and Users belonging to that Team can access those orders in the Signifyd Console

Create Team

A fundamental unit of the Signifyd API is a Team. A single Team typically equates to a single merchant. Orders are submitted to Signifyd under that Team and users belonging to that Team can access those orders in the Signifyd Console. Normally the merchant itself creates and manages its own Teams. The Signifyd Partners API is designed to allow Teams to be created, updated and associated programatically by a trusted third-party.

Authorizations:
Server-Side-Auth
path Parameters
partnerId
required
integer <int64>
Example: 123

Signifyd's unique identifier for the partner. This can also accept the placeholder "0" which will automatically populate with your partnerId using your partner credentials via an API.

Request Body schema: application/json

Team details

orgId
required
integer <int64>

Signifyd's unique identifier for the Organization to which this Team belongs.

name
required
string

The name of the Team.

website
required
string

The primary domain at which the Team receives eCommerce orders.

object (ChargebackSettings)

Chargeback Settings

merchantDescription
string

Description of the merchant.

Responses

Request samples

Content type
application/json
{
  • "orgId": 123456,
  • "name": "Initrode East Division",
  • "website": "initrode-east.com",
  • "chargebackSettings": {
    },
  • "merchantDescription": "A retail store owner."
}

Response samples

Content type
application/json
{
  • "teamId": 789123,
  • "orgId": 123456,
  • "name": "Initrode East Division",
  • "website": "initrode-east.com",
  • "chargebackSettings": {
    },
  • "merchantDescription": "A retail store owner."
}

Get Team

Gets the details for a Team

Authorizations:
Server-Side-Auth
path Parameters
partnerId
required
integer <int64>
Example: 123

Signifyd's unique identifier for the partner. This can also accept the placeholder "0" which will automatically populate with your partnerId using your partner credentials via an API.

teamId
required
integer <int64>
Example: 789123

Signifyd's unique identifier for the Team

Responses

Response samples

Content type
application/json
{
  • "teamId": 789123,
  • "orgId": 123456,
  • "name": "Initrode East Division",
  • "website": "initrode-east.com",
  • "chargebackSettings": {
    },
  • "merchantDescription": "A retail store owner.",
  • "status": "LIVE"
}

Update Team

Updates a Team. Any fields not supplied will not be changed. If one wishes to update the status or products of a Team one must use the endpoints specifically for that purpose rather than this one. The OrgId which links the Team to its Organization can not be changed.

Authorizations:
Server-Side-Auth
path Parameters
partnerId
required
integer <int64>
Example: 123

Signifyd's unique identifier for the partner. This can also accept the placeholder "0" which will automatically populate with your partnerId using your partner credentials via an API.

teamId
required
integer <int64>
Example: 789123

Signifyd's unique identifier for the Team

Request Body schema: application/json

Team details

name
string

The name of the Team.

website
string

The primary domain at which the Team receives eCommerce orders.

object (ChargebackSettings)

Chargeback Settings

merchantDescription
string

Description of the merchant.

Responses

Request samples

Content type
application/json
{
  • "name": "Initrode East Division",
  • "website": "initrode-east.com",
  • "chargebackSettings": {
    },
  • "merchantDescription": "A retail store owner."
}

Response samples

Content type
application/json
{
  • "teamId": 789123,
  • "orgId": 123456,
  • "name": "Initrode East Division",
  • "website": "initrode-east.com",
  • "chargebackSettings": {
    },
  • "merchantDescription": "A retail store owner."
}

Set Team Live

Change the team status from BURN_IN to LIVE. For teams created using the Partners API Teams, Signifyd will have to approve internally before this endpoint can work.

Authorizations:
Server-Side-Auth
path Parameters
partnerId
required
integer <int64>
Example: 123

Signifyd's unique identifier for the partner. This can also accept the placeholder "0" which will automatically populate with your partnerId using your partner credentials via an API.

teamId
required
integer <int64>
Example: 789123

Signifyd's unique identifier for the Team

Responses

Response samples

Content type
application/json
{
  • "teamId": 789123,
  • "status": "LIVE"
}

Add Team Product

Adds a product to the Team

Authorizations:
Server-Side-Auth
path Parameters
partnerId
required
integer <int64>
Example: 123

Signifyd's unique identifier for the partner. This can also accept the placeholder "0" which will automatically populate with your partnerId using your partner credentials via an API.

teamId
required
integer <int64>
Example: 789123

Signifyd's unique identifier for the Team

Request Body schema: application/json

Adds a product to a Team.

product
required
string
Enum: "GFP" "CBR" "RECS" "SCOR"

The Product offered to a Team.

  • GFP - GUARANTEED FRAUD PROTECTION - represents a client whose orders Signifyd will guarantee and take financial liability for fraud.
  • CBR - CHARGEBACK RECOVERY: represents a client whom signifyd will fight chargebacks for
  • RECS - RECOMMENDATIONS: represents a client who is receiving decisions & scores.
  • SCOR - SCORING: represents a client who is receiving only scores

Responses

Request samples

Content type
application/json
{
  • "product": "GFP"
}

Response samples

Content type
application/json
{
  • "teamId": 789123,
  • "product": "GFP"
}

Get Team Members

Gets a paginated list of details for all members at the Team level.

Authorizations:
Server-Side-Auth
path Parameters
partnerId
required
integer <int64>
Example: 123

Signifyd's unique identifier for the partner. This can also accept the placeholder "0" which will automatically populate with your partnerId using your partner credentials via an API.

teamId
required
integer <int64>
Example: 123456

Signifyd's unique identifier for the Team.

query Parameters
limit
integer [ 1 .. 100 ]
Default: 50

Specifies the max number of members to return in the response. This should be a positive integer.

offset
integer >= 0
Default: 0
Example: offset=50

Specifies the number of members to skip at the start of the response. This should be a positive integer. Combined with limit, this allows for paging through the members found in the search. Don’t include this parameter on the first call. Use the nextOffset value returned in a previous response to request the next page of members.

Responses

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "hasMore": true,
  • "nextOffset": 50
}

Add Team Member

Adds a user as a Team level member.

Authorizations:
Server-Side-Auth
path Parameters
partnerId
required
integer <int64>
Example: 123

Signifyd's unique identifier for the partner. This can also accept the placeholder "0" which will automatically populate with your partnerId using your partner credentials via an API.

teamId
required
integer <int64>
Example: 123456

Signifyd's unique identifier for the Team.

Request Body schema: application/json

Member details

userId
required
integer <int64>

Signifyd's unique identifier for the user.

role
required
string (Role)
Enum: "REVIEWER" "MEMBER" "ADMIN"

The role the member will have on all underlying Teams.

  • REVIEWER - Can view Orders. Can not perform User managment.
  • MEMBER - Can view Orders and cancel guarantee Orders. Can not perform User managment.
  • ADMIN - Has full rights and privileges, can view Orders and perform User managment.

Responses

Request samples

Content type
application/json
{
  • "userId": 123456,
  • "role": "REVIEWER"
}

Response samples

Content type
application/json
{
  • "teamId": 123456,
  • "userId": 123456,
  • "role": "REVIEWER"
}

Update Team Member

Updates a member at a Team level. Any fields not specified will not be changed.

Authorizations:
Server-Side-Auth
path Parameters
partnerId
required
integer <int64>
Example: 123

Signifyd's unique identifier for the partner. This can also accept the placeholder "0" which will automatically populate with your partnerId using your partner credentials via an API.

teamId
required
integer <int64>
Example: 123456

Signifyd's unique identifier for the Team.

userId
required
integer <int64>
Example: 123456

Signifyd's unique identifier for the user.

Request Body schema: application/json

member details

role
string (Role)
Enum: "REVIEWER" "MEMBER" "ADMIN"

The role the member will have on all underlying Teams.

  • REVIEWER - Can view Orders. Can not perform User managment.
  • MEMBER - Can view Orders and cancel guarantee Orders. Can not perform User managment.
  • ADMIN - Has full rights and privileges, can view Orders and perform User managment.

Responses

Request samples

Content type
application/json
{
  • "role": "REVIEWER"
}

Response samples

Content type
application/json
{
  • "teamId": 123456,
  • "userId": 123456,
  • "role": "REVIEWER"
}

Get Team Member

Gets the details for a Team member.

Authorizations:
Server-Side-Auth
path Parameters
partnerId
required
integer <int64>
Example: 123

Signifyd's unique identifier for the partner. This can also accept the placeholder "0" which will automatically populate with your partnerId using your partner credentials via an API.

teamId
required
integer <int64>
Example: 123456

Signifyd's unique identifier for the Team.

userId
required
integer <int64>
Example: 123456

Signifyd's unique identifier for the user.

Responses

Response samples

Content type
application/json
{
  • "teamId": 123456,
  • "userId": 123456,
  • "role": "REVIEWER"
}

Remove Team Member

Removes Team membership from a user.

Authorizations:
Server-Side-Auth
path Parameters
partnerId
required
integer <int64>
Example: 123

Signifyd's unique identifier for the partner. This can also accept the placeholder "0" which will automatically populate with your partnerId using your partner credentials via an API.

teamId
required
integer <int64>
Example: 123456

Signifyd's unique identifier for the Team.

userId
required
integer <int64>
Example: 123456

Signifyd's unique identifier for the user.

Responses

Response samples

Content type
application/json
{
  • "messages": [
    ],
  • "traceId": "891f2e31d267dde",
  • "errors": {
    }
}

Users

Users of a Partners entities.

Create User

Creates a User with a given email address or finds an already created User by the Partner. Although the Partner owns this User and can make any changes they want to the User, the User will initially not be a member of the Partner entities and have no visibility of Teams. The User can be added as a member at a Team, Organization or Partner level after creation.

Authorizations:
Server-Side-Auth
path Parameters
partnerId
required
integer <int64>
Example: 123

Signifyd's unique identifier for the partner. This can also accept the placeholder "0" which will automatically populate with your partnerId using your partner credentials via an API.

Request Body schema: application/json
email
required
string <email>

Email of the user. This will be used as a unique identifier for the user and is essentially the user's username. It can be used to access the Signifyd Console. When a user is first created they will be sent an email to confirm their email address and set up a password.

Responses

Request samples

Content type
application/json
{
  • "email": "user@mycompany.com"
}

Response samples

Content type
application/json
{
  • "userId": 123456,
  • "email": "user@mycompany.com"
}