Riskified Documentation

Magento Integration & User Guide


The Magento fraud protection extension by Riskified was developed to support a simple and efficient integration process using Magento’s backend infrastructure.

This guide provides an overview of the integration process as well as step-by-step instructions to completing it. Please note that you can also use the instructions provided within the integration management application to guide you through the steps of the integration. You will gain access to the integration management application after an account is created for you by an account executive and 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 will need to be finalized.

The main steps of the integration are:

  1. Technical integration with Riskified’s sandbox environment
  2. Activating your production account
  3. Technical integration with Riskified’s production environment
  4. Account settings

It is recommended that steps 1-3 be completed by a Developer, and step 4 be completed by the Account Owner.

Following this process, your account will be on hold while Riskified analytics and automation teams are building models and ensuring you receive the full benefits of the solution from the moment you begin submitting orders.



Integration overview

The two main technical components required for a full integration are the Riskified Magento extension and the notification endpoint. Through the extension, your shop will share with Riskified all order data, including user behavior and session data. The notification endpoint will allow you to automatically receive Riskified's order decision and to streamline the post-checkout for all your order flows.


Data flow

Riskified’s Magento extension receives 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 the notification endpoint. This notification can be used to trigger events in your system that will synchronize the order status with Riskified’s system and trigger 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 - Development and testing

The Riskified Magento extension was developed to support a simple and efficient integration process. While it saves substantial development time, it does require significant attention and effort to complete testing and ensure the integration’s coverage answers your needs and order flows.

Before starting any work with the extension, we strongly recommend that you define your UAT (user acceptance testing) by mapping all your end-to-end use cases and order flows (gateways, sources etc). You can find more information about testing below.

Step-by-step instructions and tools are provided within the integration management application to guide you through the integration process.

Detailed instructions for every step are listed below.


Step 1: Sandbox
Action 1: Install the Riskified Extension

The first step of the integration is installing the Riskified extension on your sandbox Magento environment. The extension allows your shop to send Riskified order data required for the review process. As part of the extension's installation process, a beacon is embedded on your website. Riskified’s 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.

Get the key
  1. Go to Magento Connect
  2. On Riskified’s 'Magento Connect' page, click the 'Install' button
  3. Copy the extension key (see screenshot below)
Enter the key
  1. Go to system > Magento Connect > Magento Connect Manager
  2. Paste the extension key into the Install New Extension dialogue box (Step 2), click 'Install' and then 'Proceed' (see screenshot below)

Note: For the extension to be activated, remember to log out of the Magento Admin and then log in again.

Action 2: Configure the Riskified Extension

In this step, you will need to configure your Megento Sandbox environment so that it points to Riskified’s Sandbox, using your store credentials. This will allow you to send Riskified order data. You will not be able to proceed to steps 3 and 4 until it is successfully completed.

Go to the Magento Configuration (see screenshot on the right):
  1. Return to the Magento Admin
  2. Go to System > Configuration
  3. Go to the 'RISKIFIED' section in the sidebar.
  4. Click the 'Settings' tab
Configure your Riskified credentials
Within the integration management application, you will be provided with:
  1. Shop URL as recorded in Riskified’s system
  2. An authorization token

Copy your shop URL and the Riskified authorization token into the Magento configuration settings (see screenshot below). Make sure you are set to the sandbox environment.

* This window will also later be used for synchronizing Riskified’s decisions with your Magento account.
Action 3: Validate Order Data

In this step, you will be required to send several different orders to make sure the data in them is formatted properly in accordance with Riskified’s requirements.

Submitting orders for validation

Once you have successfully configured the Riskified extension, the data sent must be validated by Riskified to ensure there are no issues with its format, content, or structure.

Created orders will appear in the order validation table and be automatically scanned for data issues. Any issues found will appear in the table under the icon. To see the results for a specific order, click the red icon beside it.

To select an order from the table to be sent for manual validation, click the box beneath the word “Choose” appearing to its direct left. When you have finished selecting orders, click the “Validate” button. It is required that you send real order data as received by your system.

After requesting validation, the action status will automatically change to “Analysis in progress”. You will be unable to submit additional orders for validation until you receive a response from Riskified regarding those under review. Therefore, you should send orders from a variety of payment gateways, order flows and product types to ensure a complete validation.

Riskified will then analyze your submitted orders and provide you with feedback via email once the validation is complete. Below is a list of possible outcomes:

  1. Issues found with your data: This means a problem with one or more submitted orders prevented a successful validation. In this case, you will be notified of the issues detected and informed of the changes necessary to format future orders in accordance with Riskified’s requirements. After implementing these changes, you must submit new, properly formatted, orders for validation.
  2. Data Validation completed: This means that all orders submitted for review were validated, and there are no outstanding issues.
Action 4: Set notification endpoint

In this step you will set the designated URL that will receive Riskified’s decisions. Riskified sends notifications to the endpoint in order to allow you to integrate these decisions directly into your fulfillment and payment processing systems. The general format of this URL is https://mymagentoshop.com/full/response/getresponse/

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 5: Test order flow

This is one of the most important steps in the integration process. As a prerequisite, we recommend defining your UAT (user acceptance testing) by mapping all your order flows, so that every step is familiar and clear. As a general guideline, make sure you test an approval and a decline order flow for each of your payment gateways and order sources.

Order Status Sync

The Riskified ‘Order Status Sync’ feature allows you to sync your Magento status with Riskified’s decisions. Once enabled, orders being reviewed by riskified (Processing) will be labeled “On Hold.” When Riskified decides on an order, the status will be updated accordingly in Magento.

The following Magento statuses correspond to stages in Riskified’s order review process:
  1. Orders submitted to Riskified will be labeled 'On Hold'
  2. Orders approved by Riskified will be labeled 'Processed'
  3. Orders declined by Riskified will be labeled 'Cancelled'
To enable this feature:
  1. Make sure that your notifications endpoint is set up correctly
  2. On your Magento Admin panel, click 'System' and then click 'Configuration'
  3. Scroll down to 'Riskified' settings
  4. Click on the arrow to expand > Change 'Order Status Sync' to 'Enable'
    (see animated gif below)
Auto Capture

The Riskified ‘Auto capture’ feature (Automatic Invoice creation) allows you to fully automate your order flow. Once enabled, an invoice will automatically be created when Riskified approves an order, and the funds captured. All orders declined by Riskified will be labeled as 'Cancelled'.

To enable this feature:
  1. Before enabling ‘Auto Capture’, please ensure you have enabled Order Status Sync
    (see instructions above)
  2. On your Magento Admin panel, click 'System' and then click 'Configuration'
  3. Scroll down to 'Riskified' settings
  4. Under 'Automatic Invoice Creation' choose 'Yes' to enable the feature and make sure 'Capture Case' is set to 'Online Capture' (see animated gif below).
Simulating Riskified decisions

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:This test will only work after a notification endpoint has been set, and is only applicable on sandbox.

Follow these steps to perform an end-to-end test:
  1. Use your Magento Admin to submit an order to Riskified (see animated gif below)
  2. Click either the "Approve" or "Decline" button in the Riskified integration management application. The order status will change accordingly and an email notification will be sent to your inbox (see screenshot below)
  3. Check that the processes set to be triggered within your systems by an approve or decline decision work as expected

Once the testing process is completed, your account is ready to be moved to production. In the sandbox menu, click “Activate my production account” to continue the integration process in Riskified’s production environment.


Step 2: Create your production account

In order to activate your production account, Riskified requires all users to set their production password. After completing step 1, user will be prompted to set his or her password within the integration management application. All other users we receive an email inviting them to set their own password for their personal production login.


Step 3: Production
Action 1: Install the Riskified Extension

You will need to install the Riskified extension on your Production Magento environment, as you previously did in Sandbox

Get the key
  1. Go to Magento Connect
  2. On Riskified’s 'Magento Connect' page, click the 'Install' button
  3. Copy the extension key (see screenshot below)
Enter the key
  1. Go to system > Magento Connect > Magento Connect Manager
  2. Paste the extension key into the Install New Extension dialogue box (Step 2), click 'Install' and then 'Proceed' (see screenshot below)

Note: For the extension to be activated, remember to log out and then back in to the Magento Admin.

Action 2: Configure the Riskified Extension

You will need to configure your Megento production environment so that it points to Riskified’s production, using your store credentials. This will allow you to send Riskified order data. You will not be able to proceed to steps 3 and 4 until this step is successfully completed.

Go to the Magento Configuration (see screenshot on the right):
screenshot
  1. Return to the Magento Admin
  2. Go to System > Configuration
  3. Go to the 'RISKIFIED' section in the sidebar.
  4. Click the 'Settings' tab
Configure your Riskified credentials
Within the integration management application, you will be provided with:
  1. Shop URL as recorded in Riskified’s system
  2. An authorization token

Copy your shop URL and the Riskified authorization token into the Magento configuration settings (see screenshot). Make sure you are set to the production environment.

* This window will also later be used for syncing Riskified’s decisions with your Magento store.

Action 3: Set notification endpoint

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. The general format of this URL is https://mymagentoshop.com/full/response/getresponse/

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 4 - Send Historical Orders

In this step, you will use a script to send historical order data and statuses. Riskified analyzes historical orders using elastic linking and machine learning engines. This process ensures you get the benefit of an optimal approval rate from the day you go live.

The status of the historical order analysis will be communicated to you both by email and within the integration management application.

Run the script

Open a shell connection to your production server, open your main Magento installation folder and run the following command: php lib/riskified_scripts/riskified_historical_upload.php

If at any point, Riskified encounters an error or problem with the provided historical data, the process will be halted. When this occurs, you will be notified of the detected issues and informed of the changes required in order to be in compliance with Riskified’s requirements. You must re-start the process from the beginning, making all necessary corrections beforehand.

If the script for some reason fails mid way and you want to resume uploading historical orders from the last uploaded page, please use the following command line: php lib/riskified_scripts/riskified_historical_upload.php -p (where p = page# from which to resume upload)

Action 5: Send historical chargebacks

In this step you will need to provide Riskified with historical chargebacks for the orders you sent. This data will be provided using a .CSV file via the Riskified integration management application.

The historical decision CSV file should contain two columns:
  1. Order ID (the same parameter included in the order JSON as “id”)
  2. Final order status - This field can receive two parameters:“chargeback_fraud”, “chargeback_not_fraud”.

Once you have generated the CSV file, click “Upload” to send it to Riskified.


Step 4: Set account

Only the account owner will be able to complete the actions in this step.

Action 1: Set users

Add the users to grant access to the Riskified management application, including respective roles. Please note that you can add users within this screen, but not configure their notification settings. Full user management capabilities will be available in your Riskified account, after the integration is complete.

More information about User Roles and Permissions can be found here.
More information about multiple user management can be found here.

Action 2: Provide billing details
In this action, you will perform these 3 steps:
  1. Enter the billing information as you would like it to appear on your monthly invoice.
  2. Enter the email addresses where you would like to receive invoices from Riskified. This can be done by clicking “Add” on the bottom right hand side of the screen.
  3. Enter the credit card you will be using to make payments to Riskified. This can be done by clicking “Add card” at the bottom left hand side of the screen. Merchants who pay by other methods will be presented with their chosen method of payment.

Please note that all settings available here will continue to be available to you after the integration is complete.

Action 3: Read Chargeback Guarantee

In this action, you are required to read through a summary of Riskified’s chargeback guarantee.

This step should be performed by the Account Owner. You will be unable to complete the integration until certifying that you have read and understood its terms and conditions.

After completing these steps, click the “Click here to complete setup” button in the set account menu to finalize the integration.

This concludes the integration. Important: Riskified is committed to ensuring you receive the full benefits of the integration from the moment your account is live. To that end, the status of your account will be “On hold” for up to five days after real-time data begins flowing to Riskified. Our automation and analytics teams use this time period to research and analyze your order data and build your customized automation models. You will be notified when this process is complete and you can begin submitting orders for review.