Integration Basics

Below are the basics of API integration with Riskified. Technical integrations encompass development work in both the sandbox and production environments. 

Main Integration Steps

• Step 1: Sandbox Integration
• Step 2: Production Validation
• Step 3: Go Live Preparation
• Step 4: Your Account is Live

It is recommended that your Developer(s) be the primary contact during the integration process, as it can be highly technical. During steps 4 and 5, the Account Owner will be looped in to complete non-technical tasks.

Integration Elements

The integration with Riskified includes three main elements used to communicate with your system:

1. Order Data Endpoints - Riskified’s endpoints enable your system to send data to Riskified about key stages in an order’s lifecycle. The endpoints are used to allow your system to notify Riskified whenever any of the following events occur:

• Payment system response
• Submission for review
• Order updates
• Order partial or full refunds

Pre-Authorization Flow

Post-Authorization Flow

2. Order Decision Notifications (required for asynchronous integrations) - Riskified uses the notification endpoint to send order decisions back to your system. This allows you to streamline your order flow and completely automate the post-checkout process, both for approvals and declines.

3. Storefront Beacon - Riskified's storefront beacon collects information about a customer’s device, IP address, and behavior and transmits it back to Riskified. This process occurs behind the scenes and does not have any negative effect on page load time for customers. Riskified offers the beacon for both websites and mobile native applications.

Data Flow

Riskified’s endpoints receive information from your system about every order placed on your store. However, you retain full control over which orders are actually submitted for review. When an order is submitted for review, Riskified reviews it using machine learning models, elastic linking, and data enrichment.

When a decision is made on a submitted order, Riskified notifies your store’s back-end via a simple REST call. This notification can be used to trigger events in your system that will synchronize the order status with Riskified’s system and trigger your own system’s post-decision processes.

Finally, Riskified is notified about the final status of the order, whether it is fulfilled, refunded, cancelled, or if a chargeback was incurred.

Integration Process

Disclaimer: Below are the general steps for Riskified's integration process. In-depth technical documentation (including API Ref) will provided by your dedicated Account Executive and Integrations Engineer. 

Step 1: Sandbox

Action 1: Connect to Riskified

In this step, you will be required to connect your sandbox environment to Riskified’s sandbox and send order data to Riskified. You will not be able to proceed to steps 2 and 3 until it is successfully completed.

Within your Riskified Sandbox Control Center, under settings -> 'developers' you will be provided with:

• Your shop URL as recorded in Riskified’s system
• An authorization token

Copy your shop URL and the authorization token into the code lines relevant to verifying requests to and from Riskified, as defined in Riskified API reference document (contact your Account Executive or your Dedicated Integration Engineer to provide you with the link). 

Riskified offers several endpoints to enable you to create, submit, and manage orders throughout their lifecycle.

The Riskified API reference document contains all relevant information needed to interact with our system, including SDKs for PHP, Java, and .NET. you can contact your Account Executive or your dedicated Integration Engineer to provide you with the link.

Order Actions

The following order actions are used for triggering submission/ order analysis:

• "Create"
• "Submit"
• "Update"
• "Decide" (for Sync merchants only)

Riskified also offers additional order actions, including:

• "Checkout_denied"
• "Cancel / Full Refund"
• "Partial Refund"
• "Fulfill"
• "Decision"
• "Chargeback"

Submission Order Actions

Used to request Riskified review of an order for fraud after the customer has input their payment data and completed the checkout process. This allows Riskified to capture and/or analyze the full order data when providing a decision.

• A-synchronous flow: Submit
• Synchronous flow: Decide

Additional Order Actions

These order-action endpoints are highly recommended for implementation in order to maximize the benefits of the integration and reduce your manual workload.

• Decision - Allows you to notify Riskified when you approve, decline a transactions.  It is highly recommended you use this order action to provide Riskified’s machine learning models with data integral to improving the accuracy of order decisions. For Pre-authorization cases, this endpoint is mandatory for notifying Riskified upon a successful authorization.
• Checkout_denied - Informs Riskified that the gateway declined the payment authorization.
• Cancel / Full Refund - Allows you to notify Riskified when a submitted order is cancelled or fully refunded. Use this order action to trigger a reimbursement of Riskified’s approval fee when an ordered item is not shipped. Using this action for an order also cancels Riskified’s chargeback guarantee.
• Partial Refund - Allows you to notify Riskified when an order is partially refunded. Use this in case some of the ordered items run out of stock or are not shipped for any other reason. Upon receiving this notification, Riskified will adjust the approval fee to reflect the new order value.
• Fulfill - Allows you to notify Riskified when an order is successfully fulfilled. Use this to provide Riskified with insight into the order’s entire lifecycle and improve the accuracy of order decisions (Note: this one is mandatory for physical goods merchants)
• Chargeback - Notifies Riskified that a chargeback has been submitted for a specific order.

Action 2: Set sandbox notification endpoint (For Asynchronous Flow)

In this step, you will set the designated URL to which Riskified will send order decisions. Riskified sends notifications to the endpoint in order to allow you to integrate these decisions directly into your fulfillment and payment processing systems.

Endpoint Test

Riskified will send a message with a fabricated order ID to the endpoint. If a code 200 response is received from your server, the test will be considered successful.

Click the “Test Endpoint” button to troubleshoot problems. If the test is successful, Riskified will save the endpoint. If the test fails, a log describing the error type will appear.  

Action 3: Test order flow 

In this step, Riskified enables you to test your end-to-end order flow before setting up your production account. You can simulate “approve” or “decline” decisions and make sure post-decision processes work as expected. (Note: For asynchronous integrations - this test will only work after a notification endpoint has been set.)

How to perform an end-to-end test:

• Go to your Riskified Sandbox Control Center, settings -> 'Developers' -> 'Test Order Flow'
• Click on 'view test orders'. This will redirect you to the orders screen.
• Click on the order that you want to test, and click on the screwdriver icon, the following options will be shown:
• Then, you can either mark the "Approve" or "Decline" button and click 'test'.
  The order status will change accordingly and a notification will be sent to your endpoint.
• Check that the processes set to be triggered within your systems by an approve or decline decision work as expected. 

Action 4: Validate order data

Once your order actions (checkout, order creation, cancellations, etc.) are implemented, the next step is to validate the data using the Sandbox Validation Tool to verify that the order data sent from your system is complete, properly structured, and aligned with Riskified’s requirements. This preliminary data validation ensures that your integration is functioning correctly before moving to production.

1. Enter the order IDs according to the designed test scenarios. Ensure that each order was successfully sent to your Riskified Sandbox Account.
2. After submitting the order IDs, the tool will process them and check for issues related to format, content, data completeness, and compliance with Riskified’s specifications and expected flows.
3. Once the validation is complete, the tool will present the results and provide a summary of the findings. If any issues are identified, you will need to update your integration accordingly and resubmit corrected orders for validation.
4. When all flows and scenarios have been successfully completed and all issues resolved, each scenario will be marked as `Validated`. At this point, contact your dedicated Integration Engineer to confirm that a validated test order ID exists for every scenario and request a final sign-off to proceed to the next integration step and deploy your integration to Production.

Step 2: Production

Once everything is validated within Sandbox, your dedicated Integrations Engineer will open a production account for you. 

Users who previously had access to Sandbox will be automatically granted access to Production. Just keep in mind that these users will receive an email invite to set up a separate login for Production. If you need to add any additional users to Production, here are instructions on how to do so. 

Action 1: Connect to Riskified

This step ensures your system can properly communicate with Riskified’s production environment. You will not be able to proceed to the next action until it is successfully completed.

Within the integration management application, you will be provided with:

• Shop URL as recorded in Riskified’s system
• an authorization token

Copy your shop domain and Riskified authorization token into the code lines relevant to verifying requests to and from Riskified, as defined in Riskified API reference document. 

Action 2: Set production notification endpoint (Only for Asynchronous Flow)

In this step, you will set the designated URL to which Riskified will send order decisions when working with your production environment. Riskified sends notifications to the endpoint in order to allow you to integrate these decisions directly into your fulfillment and payment processing systems. 

Action 3: Integrate Riskified’s beacon

In this step, you will integrate the Riskified's Beacon into your website and/or any native mobile application available to your customers.

The beacon collects important information about a customer’s device, IP address, and on-site behavior, securely transmitting it to Riskified. This process runs seamlessly in the background and does not affect page load time or user experience.

Riskified provides beacon solutions for both web and mobile implementations. Detailed instructions for embedding the beacon will be shared by your dedicated Integration Engineer on the integration kick-off call.
 

Action 4: Send Historical Orders

In this step, you will send historical order data and chargebacks via CSV format. Generally, we require a minimum of 6 months data. Your dedicated Integration Engineer will provide you with a template to follow. This process ensures your account is reaching the optimal performance from the first day you go live. If we find any data issues during this process, we will work with you to remedy them. 

Action 5: Production Data Validation

Following the sandbox validation and historical data upload, you will perform tests in production before going live. You will start sending your real-time production orders. You will see Riskified decision for these, but you should not act upon them while we are still calibrating the models and finalizing your account. 

Please note:

• Riskified will not charge any order fees in Production until you go live.
• As you send in orders, Riskified will be validating the data being sent. There may be cases where you need to make additional changes if we find any issues.

Action 6: Shadow Mode

After production data validation, your account will move into shadow mode before going live. Shadow mode is typically around 2 weeks (depending on the volume) of real-time data. During this time, our analytics team is calibrating the models and making custom adjustments to ensure optimal performance. 

Step 3: Go Live Preparation

Action 1: Add users to your account

Make sure all the relevant team members have access to your account before you go live (i.e., adding in your fraud prevention, customer service, and operations teams). 

• Learn about user roles and permissions
• How to add users to your account

Action 2: Confirm billing details

Prior to go live, our team will check that we have the proper billing information and set up for your account. 

Action 3: Decide on chargeback submission type

Our team needs to know how you will be submitting chargebacks. There are multiple options, and your Integrations Engineer will be able to discuss the pros and cons of each one with you:

• Chargeback Gateway Integration (highly recommended)
• Chargeback API
• Manual Upload via Riskified's web application (Control Center)

Depending on your preference, additional effort may be required to set this up.

Step 4: Your Account is Live

Action 1: Official Go Live

Your dedicated Integrations Engineer will coordinate a date/time for official go live. Once you are live, you are can start acting on our decision, and our Analytics team will be closely monitoring your account performance and making adjustments as needed.

Action 2: Control Center Training

Our Customer Success team will reach out to your Account Owner with learning resources that you can share with your team. The content is centered on how to use Riskified's web application (Control Center), including guides on how to take actions on a granular level (i.e., on specific orders) and monitoring on a macro level (i.e., performance dashboards for our products).