Overview

The Riskified API is organized around REST and exposes endpoints for HTTP requests. The API is designed to have predictable, resource-oriented URLs and uses standard HTTP response codes to indicate the outcome of operations.

This is Riskified's API reference version 2.0.0. See most recent changes here.

Find integration documentation here:

  • Getting Started: Basic information about sending and receiving data with Riskfiied
  • Use Cases: Understanding our product suite and the endpoints that comprise them
  • Models: Detailed breakdown of the data models to be sent to Riskified
  • Timeline: A general timeline of our integration process
  • Software Development Kits: Resources to help technically integrate our code with your own stack
  • Platforms: Integration guides for our platforms that Riskified provides support for
  • Beacon: Information regarding the client-side code to be implemented
Example Order
//Please refer to Overview for instructions on how to download the sample order JSON and export your Auth Token.
                                    
curl -O https://apiref.riskified.com/riskified_example_order.json
export rskfd_auth_token=<AUTH TOKEN>

Getting Started

Authentication

All requests to the Riskified API must include the following HTTP Headers. These are used to specify the current API version and to verify that the data has not been compromised.

We highly recommend using an SDK that handles the authentication flow automatically.

HTTP Headers


ACCEPT

Specify the version of the API to target.
For example, to target the latest version of the API, use the following: application/vnd.riskified.com; version=2

CONTENT_TYPE

As payloads are sent to Riskified in JSON format, value should be: application/json

X-RISKIFIED-SHOP-DOMAIN

Full domain name of shop that was registered.

X-RISKIFIED-HMAC-SHA256

Verification hash for the Request.
Generated by performing an SHA256 encryption on the request's POST body and calculating the HMAC hash of the result using your Riskified authentication token.
Please use UTF8 encoding.

Authentication
//Please refer to Overview for instructions on how to download the sample order JSON and export your Auth Token.
//To calculate the signature for the request, you can use the openssl command:
                                
$ openssl dgst \
   -sha256 \
   -hmac $rskfd_auth_token \
   < riskified_example_order.json
                                
//The signature is sent in the X-RISKIFIED-HMAC-SHA256 header. Notice that the request body must fit the signature verbatim, otherwise you'll get a 401 error response.
                                
$ curl -X POST \
   https://sandbox.riskified.com/api/create \
   --data-binary @riskified_example_order.json \
   -H "ACCEPT:application/vnd.riskified.com; version=2" \
   -H "Content-Type: application/json" \
   -H "X-RISKIFIED-SHOP-DOMAIN:< YOUR DOMAIN >" \
   -H "X-RISKIFIED-HMAC-SHA256:`openssl dgst \
     -sha256 \
     -hmac $rskfd_auth_token \
< riskified_example_order.json`"

HTTP Codes

Riskified uses conventional HTTP response codes to indicate success or failure of an API request. Most responses also include a payload detailing the nature of the error. See the Responses section for more.

  • HTTP Status 200 indicates request success.
  • HTTP Status 400 indicates an error that resulted from the provided information (e.g. a required parameter was missing, a parameter was given in the wrong format, etc.)
  • HTTP Status 401 indicates a missing or invalid X_RISKIFIED_HMAC_SHA256 (Hex) signature.
  • HTTP Status 404 indicates that the requested resource does not exist.
  • HTTP Status 500 indicates an internal error with Riskified's servers.

Riskified's SDKs validate the parameters before sending each request, which means you needn't worry about 4XX status codes. This also allows you to easily spot integration issues.

Responses

Every API call returns a payload that describes the result of the action requested.

Errors

Retries

General

Riskified recommends the below retry policy in the rare occurrence that an API call to our system returns an error code as outlined in this section.

Maximum hold times and delays between retries should be adjusted according to the system ability and fulfillment requirements of the merchant business.

If you have any questions on how your flow strategy (async/sync and pre/post auth) influences the retry policy, please contact your Integration Engineer or Account Manager for assistance.

Recommended Retry Policy

Async (or post-auth sync merchants)

Attempt up to 3 times on error responses, each attempt to be spaced 2 seconds apart

After 3 attempts, implement further attempts with additional delays:

Call once every 1 minute until 5 minutes
Call once every 5 minutes until 2 hours
Call once every 10 minutes until 4 hours

Orders should be held in queue until Riskified decision is received


Pre-Auth Sync

Attempt up to 3 times on error responses, each attempt to be spaced 0.5 seconds apart

Notifications

Riskified can send an automated decision notification when approving/declining an order to the endpoint of your choosing. Start out by specifying the endpoint in your account settings.

Riskified expects to find a HTTP/1.1 compliant web server listening at the endpoint. You can test your setup by initiating test decision notifications via the 'Test API' functionality in the settings page.

A decision notification is sent as a JSON encoded payload in a standard HTTP POST request, and is identical in structure to the common endpoint responses.

Each decision notification also includes a X-RISKIFIED-HMAC-SHA256 header that can be used to validate the integrity of the notification's payload. This header is generated using the same method described under Authentication.

Upon an HTTP error (any return code other than 2xx) Riskified will reattempt to send the notification in the following frequency: 10 times in gaps of 5 minutes each and then 10 more times in gaps of 1 hour each.

Make sure that the URL is meeting the following requirements:

  1. The host URL is not an IP address (IPv4 or IPv6)
  2. The URL Top Level Domain (TLD) and Second Level Domain (SLD) must end with one of the following:

* TLD: .com, .net, .co, .org, .io or a Country-code
* SLD: co. or .net.

Use Cases

Chargeback Guarantee



Pre-Authorization

Checkout Create

The base checkout model is used for this endpoint.


The /checkout_create endpoint's purpose is to send data to Riskified during the checkout process, prior to the payment information being entered. Receiving the data at this stage allows us to ensure a quicker response time when a follow-up fraud analysis request is made (/decide or /create).

Chargeback Guarantee Base URL
Sandbox: https://sandbox.riskified.com/api/
Production: https://wh.riskified.com/api/

Checkout Denied (Pre-Auth)

The base checkout model is used for this endpoint.


The /checkout_denied endpoint is used to inform Riskified that the gateway declined the payment authorization. The gateway's authorization error message and error code are passed to us. Riskified does not review the order or provide a decision when this API is called.


This endpoint improves decision accuracy, helps prevent fraud rings and Account take over attacks, and helps Riskified identify risky carding behavior. Without implementation, Riskified won't be aware when a gateway declines a transaction. This endpoint shares the reason for the decline and allows us to track the number of transaction attempts. If the customer eventually has a successful payment authorization and a resulting order is submitted to Riskified for review, we will be better equipped to analyze the order for fraud.


This endpoint can be utilized in either a pre-auth integration or post-auth integration with Riskified, in order to inform us about a failed authorization event. /Checkout_denied can be called multiple times per the same ID.


Please make sure you fill out the Authorization Error object within the Payment Details section, as indicated in the example.

Decide

The base order model is used for this endpoint.


The /decide endpoint is used to request that Riskified review an order for fraud after the customer has input their payment data and completed the purchase. This allows us to analyze the full order data when providing a decision. Riskified's decision is returned synchronously in the response to the /decide API request. If order data changes after an initial approved decision, the /decide API is called to update Riskified and receive a decision based on the new order data.


When the /decide API is used to send Riskified updated order details, be sure to pass the same order ID in the payload as was used in the initial decide request.


Endpoint
POST/decide
Post-Authorization

Create

The base order model is used for this endpoint.


The /create endpoint's purpose is to send data to Riskified after the gateway authorizes the transaction for fraud analysis. Since this is an asycnhronous endpoint, our decision is returned to you through a pre-defined URL. If your account is under Shop Protection, the transaction will be automatically submitted for review.

Responses:
With this endpoint, you will receive a synchronous response indicating receipt of the order, as well as Riskified's response with the decision, sent to your pre-configured notification endpoint (see responses for more information).

Endpoint
POST /create

Submit

The base order model is used for this endpoint.


The /submit endpoint's purpose is to submit any transaction to Riskified for fraud review. Since this is an asycnhronous endpoint, Riskified's decision is returned to a pre-defined notification endpoint URL. See possible responses here.

note: If the most updated transaction data was already sent to Riskified (e.g. by a previous /create call) and you just wish to submit it for review - you can simply call /submit with only one field assigned: id (to match the id sent in the previous call).

Endpoint
POST /submit

Update

The base order model is used for this endpoint.


Use this endpoint to update a previously submitted order to Riskified. The id parameter is used to locate the original order.

Endpoint
POST /update

Decide (Sync)

The base order model is used for this endpoint.


The /decide endpoint is used to request that Riskified review an order for fraud after the customer has input their payment data and completed the purchase. This allows us to analyze the full order data when providing a decision. Riskified's decision is returned synchronously in the response to the /decide API request. If order data changes after an initial approved decision, the /decide API is called to update Riskified and receive a decision based on the new order data.


When the /decide API is used to send Riskified updated order details, be sure to pass the same order ID in the payload as was used in the initial decide request.


Endpoint
POST/decide

Checkout Denied (Post Auth)

The base checkout model is used for this endpoint.


The /checkout_denied endpoint is used to inform Riskified that the gateway declined the payment authorization. The gateway's authorization error message and error code are passed to us. Riskified does not review the order or provide a decision when this API is called.


This endpoint improves decision accuracy, helps prevent fraud rings and Account take over attacks, and helps Riskified identify risky carding behavior. Without implementation, Riskified won't be aware when a gateway declines a transaction. This endpoint shares the reason for the decline and allows us to track the number of transaction attempts. If the customer eventually has a successful payment authorization and a resulting order is submitted to Riskified for review, we will be better equipped to analyze the order for fraud.


This endpoint can be utilized in either a pre-auth integration or post-auth integration with Riskified, in order to inform us about a failed authorization event. /Checkout_denied can be called multiple times per the same ID.


Please make sure you fill out the Authorization Error object within the Payment Details section, as indicated in the example.

Post-Decision

Decision

Update the existing order external status.
Let us know what was your decision on your order.

Fulfill

Notifies Riskified that the fulfillment information has been generated for a particular order, including successful and failed attempts. It can be called more than once if there are multiple shipments per order. This endpoint is required for fully automated chargeback submission. Without it, merchants have to manually upload proof of delivery through the Web App. It also allows Riskified to generate compelling evidence documents for chargeback disputes.

Partial-Refund

The /refund endpoint's purpose is to send data to Riskified about partially refunded orders for non-fraud and non-gateway decline reasons, either by the customer or by the merchant. This automatically notifies us to facilitate partial refunds of the original approval fee. Without this endpoint, you will have to manually request a refund in the Web App for each cancelled order.

Cancel/Full-Refund

The /cancel endpoint's purpose is to send data to Riskified about cancelled orders for non-fraud and non-gateway decline reasons, either by the customer or by the merchant. This automatically notifies us to facilitate refunds of the original approval fee. Without this endpoint, you will have to manually request a full refund in the Web App for each cancelled order.

Chargeback

Please contact us before implementing this API flow

/chargeback notifies Riskified that a chargeback has been submitted for a specific order.
Note: Riskified offers fully automated chargeback gateway integrations for major gateways: Braintree, Stripe, Ayden, PayPal; this process automates end-to-end chargeback handling from chargeback reporting to the disputing process.

Riskified stands behind its chargeback guarantee for all approved orders.


Account Secure

The Customer Trust suite is designed to protect both merchants and customers from fraud and abuse. Account Secure guards the security of customer store accounts - protecting against chargebacks, data theft and more. Policy Enforcement ensures that customers aren't abusing store policies and promotions.


Note: Riskified's beacon/mobile SDK implementation is crucial to providing effective Account Secure

Login

/login is the core endpoint for Account Secure. This synchronous call is executed upon an active login attempt to your site/app. Riskified will respond with one of the following decisions: 'allow' / 'verify'.
Note: avoid calling /login upon silent or automated logins

Responses:
Riskified responses are returned in a synchronous manner to the request. They contain one parameter, decision indicating our decision. The value of this parameter will be either allow, notify or challenge.

Account Secure Base URL
Sandbox: https://api-sandbox.riskified.com/customers
Production: https://api.riskified.com/customers

Reset Password Request

/reset_password notifies Riskified when a customer changes their password. This is especially critical for post account take over attacks situations, so we understand that the account has been secured

Customer Create

/customer_create notifies Riskified of a new customer account registration. For Account Secure, this data is used to analyze future login attempts to this account.

Customer Update

/customer_update notifies Riskified of any changes made within a user's registered account. Some types of updates can be indications of fraudulent activity. Other updates are important for analysis of future login attempts

Verification

Sends Riskified events relating to email verifications and associated verification actions. Refer to the VerificationSessionDetails section for details on building the model and constructing individual fields.

Contact

/contact is the endpoint that notifies Riskified of an event in which a customer contacted the merchant. This data will be used to finetune analysis of future login attempts for this customer's account.

Payment Optimization

Advise (Screen)

Screen provides a multi-layered, proactive fraud review before checkout is completed, providing a quick synced analysis before they hit your business and bank authorization rates.

The base checkout model is used for this endpoint.


Creates a new checkout. Returns a synchronous response, indicating Riskified's authentication recommendation.
Should be called before attempting payment authorization and order creation.

Note the additional required fields in the PaymentDetails model when calling this endpoint.

Advise(Screen) Response

Payment Optimization Base URL
Sandbox: https://sandbox.riskified.com/api/
Production: https://wh.riskified.com/api/

Advise (PSD2)

Riskified's PSD2 Optimization product, which is complementary to our Chargeback Guarantee product, is designed to minimize the friction associated with SCA and maximize conversions - all while meeting full PSD2 compliance.

The base checkout model is used for this endpoint.


Creates a new checkout. Returns a synchronous response, indicating Riskified's authentication recommendation.
Should be called before attempting payment authorization and order creation.

Note the additional required fields in the PaymentDetails model when calling this endpoint.

Advise(PSD2) Response

Models

Address

Use this model to provide address information. It is used primarily for billing address and shipping address but is also used for pick-up and drop-off addresses.

Authentication Result

An object describing the authentication 3DS result from the issuer.

Authorization Error

An object describing the failed result of an authorization attempt by a payment gateway.

Chargeback Details

An object containing the chargeback details as received from the gateway or the issuer

Charge Free Payment Details

Charge free payment details, where a merchant can pass a partial sum of an order as non risk (e.g. gift card amount)

Client Details

Technical information regarding the customer's browsing session.

Contact Method

An object containing details on the method the customer used to reach out to the merchant.

Customer

An object containing information about the customer.

Decision Details

An object describing the decision made by the merchant of an order.
Notice: decision details does not hold Riskified's decision on an order.

Discount Code

Discount codes that were applied to the order.

Dispute Details

An object containing information about the dispute as sent to the gateway or issuer

Fulfillment Details

Use this model to describe the fulfillment of an order.

Line Items

An object containing information about an item (product) in the order.
Sub-products should have the required general fields as well as the required fields for their section.

Login Status

An object containing details of the customer's login attempt.

Passenger

Applicable for merchants of the travel industry only.
Passenger information for each passenger included in this order.
Each passenger is assumed to be assigned to all tickets in the order (all line-items).

Payment Details

An object containing information about the payment. The fields are dependant on the payment type - credit card or paypal.

Recipient

An object containing information about the recipient of digital goods.

Refund Details

An object containing information about a partial refund.

Seller

An object containing information about the seller (relevant for marketplaces).

Session Details

An object containing basic information regarding the session.

Shipping Line

Details the shipping methods used to deliver the items.
* Please note That this can either be an array or a standalone object

Social Details

An object containing information about the customer.

Verification Session Details

An object containing basic information regarding the verification session.

Timeline

Riskified Integration Timeline

Software Development Kits


PHP


Our PHP SDK Github repository can be found here.


Package Management:

Our PHP SDK can also be installed via Composer, here.

Java


Our Java SDK Github repository can be found here.


Package Management:

Our Java SDK can also be installed via Maven, here.

C#


Our C# SDK Github repository can be found here.


Package Management:

Our C# SDK can also be installed via NuGet, here.

Platforms


Magento

Riskified's Magento fraud protection extension supports a simple and efficient integration process using Magento's backend infrastructure. This guide provides an overview of the process and step-by-step instructions to complete it. You will gain access to the integration management application after an account is created for you by an account executive. After this step is complete, an invitation to activate your account will be sent to your inbox. Technical integrations encompass development work in both the sandbox and production environments. After completing the technical requirements of the integration, the account's settings can be finalized.


Our Github repository for Magento 1 can be found here.

Our Github repository for Magento 2 can be found here.


Integration Guide:

Our Magento 1 integration guide can be found, here.

Our Magento 2 integration guide can be found, here.

Shopify

Riskified's Shopify fraud protection plugin supports a simple and efficient integration process using Shopify's backend infrastructure. This guide provides an overview of the process and step-by-step instructions to complete it.


Integration Guide:

Our Shopify integration guide can be found, here.

Salesforce Commerce Cloud (SFCC)


Integration Guide:

Our SalesForce Commerce Cloud integration guide can be found, here.

Beacon

The Riskified store front beacon is a snippet of code embedded in the pages of your webstore. It is important that the code be added into the header or footer of your website so data is collected from every page. It loads asynchronously and does not affect page load time.

Store Front Beacon

Implementation steps:
  • Copy the JavaScript snippet below, and replace the highlighted variables with:
    • Your store domain - the same domain you use for logging into the app.
    • Session ID - the unique identifier created when a user arrives at your website. The session ID must be created at the start of the user's visit to your store, and not just when the shopping cart is created.

      *Please note, character limit should not exceed 100 characters

      • Note: The session ID should also be passed to Riskified in the cart_token field.
  • Paste the modified beacon JavaScript snippet into the HTML of your website.

Single Page Application (SPA)

The Riskified Store Front Beacon supports sites whose content is loaded dynamically without traditional full page loads. To track dynamically loaded content as distinct pageviews you can send a pageview hit to Riskified's Beacon and specify the page name as a String type parameter.


For Single Page Applications that may need to change the value of the session ID (due to user inactivity, for instance), specify the newly generated session ID as a String type parameter.
Single Page Application (SPA)
RISKX.go('/new-page')
Single Page Application (SPA)
RISKX.go(url) // sends a beacon reading with the session ID
//sent in the < script > tag
RISKX.setSid('B') // changes the session ID to 'B'
RISKX.go(url) // sends a beacon reading with the session ID 'B'

Mobile SDKs

Find more information here: Mobile SDK documentation.

Android

Package Management:

Our Android SDK can be installed via Maven, here.

Our React Native SDK can be found here.

iOS


Our iOS SDK Github repository can be found here.

Our React Native SDK can be found here.