This guide provides an overview of the integration process as well as step-by-step instructions to complete 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:
- Technical integration with Riskified’s sandbox environment
- Activating your production account
- Technical integration with Riskified’s production environment
- 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.
Table of Contents
Integration overview
Data flow
Integration process - Development and testing
Step 1: Sandbox
Action 1: Connect to Riskified
Action 2: Set sandbox notification endpoint
Action 3: Test order flow
Action 4: Validate order Data
Step 2: Create your production account
Step 3: Production
Action 1: Connect to Riskified
Action 2: Set production notification endpoint
Action 3: Implement Riskified’s Front-end Beacon
Action 4: Send Historical orders
Action 5: Send historical chargebacks
Action 6: Test order flow
Action 7: Sending Real-Time Orders in Shadow Mode:
Step 4: Set account
Action 1: Set users
Action 2: Provide billing details
Action 3: Read Chargeback guarantee
Integration overview
The integration with Riskified includes three main touchpoints used to communicate with your system:
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
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.
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.
The following diagram illustrates the order creation, submission, and decision notification processes within Riskified's API.
Integration Process - Development and Testing
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: 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", and "Update" (Or "Decide" - for Sync merchants).
Riskified also offers additional order actions - "Checkout_denied", "Cancel / Full Refund", "Partial Refund", "Fulfill", "Decision", "Chargeback" etc.
The submission order actions are:
Asynchronous Flow:
- Create - Allows you to create an order in Riskified’s database.
- Submit - Allows you to submit an order for review by Riskified. This action overrides any submission filters configured on your account. Submit also creates an order in Riskified’s database if it wasn’t created already.
- Update - Allows you to update the details of an existing order in Riskified’s database. Use this to change an order’s details after its creation.
Synchronous Flow:
- Decide - used to request that Riskified review an order for fraud after the customer has input their payment data and completed the checkout process. This allows us to analyze the full order data when providing a decision.
The additional order actions are:
These order-action endpoints are highly recommended for implementation, in order to maximize the benefits of the integration and reduce your manual workload.
- 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)
- 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.
- Chargeback - Notifies Riskified that a chargeback has been submitted for a specific order.
- Checkout_denied - Informs Riskified that the gateway declined the payment authorization.
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.
Follow these steps 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
In this step, you will be required to send several different orders to make sure the data in them is formatted properly and in accordance with Riskified’s requirements.
Preliminary Data Validation
Once the order actions are implemented within your system, the data sent must be validated by Riskified to ensure there are no issues with its format, content, or structure.
- Go to the 'Preliminary Data Validation' section on the 'Developers' section
- Add the order IDs (comma-separated) that you would like to validate. The results of the preliminary validations will be sent via email.
- Make sure to enter order IDs that were sent to Riskified Sandbox Account
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 complete validation.
After submitting your orders for validation, reach out to your dedicated Integration engineer and share the order IDs per pre-defined validation scenarios.
Riskified will then analyze your submitted orders and provide you with feedback via email once the validation is complete, with its initial feedback of data issues discovered.
After completing these 4 steps in the sandbox environment, your account is ready to be moved to production. In the sandbox menu, click “Complete integration ” in order to let the Riskified Integrations team know that you are ready to start the Production testing.
Step 2: Create your production account
In order to activate your production account, Riskified requires all users to set their production password. The user completing step 1 will be prompted to set their password within your Riskified Control Center, under settings -> 'developers'. All other users will be sent an email inviting them to set their own password for their personal production login.
Step 3: Production
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 (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.
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: Implement Riskified’s storefront beacon
In this step, you will implement the Riskified storefront beacon on your website and/or any native mobile application available to your customers. 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. Riskified offers the beacon for both websites and mobile native applications. For optimal performance, the beacon performance status should be at least “good.”
Detailed instructions for embedding the storefront beacon will be shared by your dedicated Integration Engineer on the integration kick-off call.
Detailed instructions for embedding the mobile beacon can be found here.
Action 4: Send historical Orders
In this step, you will be requested to send your historical order data and statuses dating back to a minimum of 6 months prior to the integration. 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 analysis of the historical orders will be communicated to you by your dedicated Integration engineer or Account executive.
Required Data: All order parameters previously configured for the sandbox order data validation such as shipping address, billing address, payment details, etc. must be included in the order data of all orders sent for historical order analysis. In addition, you must provide Riskified with the status of every order - whether it was approved, declined, or if a chargeback was incurred.
You can provide an order’s final status via the “decision” object provided in Riskified’s API. For every order, add one of the following tags to the “external_status” field:
- “approved” - approved orders
- “declined_fraud”- declined orders (refunded or voided) due to suspected fraud
- “cancelled” - declined orders (refunded or voided) for non-fraudulent reasons (e.g. item out of stock)
- “chargeback_fraud” - orders for which a fraud-related chargeback was incurred (e.g. unauthorized card usage)
- “chargeback_not_fraud” - orders for which a non-fraud-related chargeback was incurred (e.g. item not received)
Alternatively, you can upload a CSV file of order decisions - contact your Integration Engineer for more details.
The process:
Initially, you will receive a custom-made pre-defined template and will be requested to share a small, initial test batch in order to validate the data structure is correct. Once confirmed, you can extract the full needed data.
Once you have prepared all historical orders, please notify your dedicated Integration Engineer and share the full file according to the pre-defined template that will be shared at the beginning of the process.
Action 5: Send historical chargebacks
Please provide your historical chargebacks to Riskified with historical in a CSV format.
The historical chargeback CSV should contain two columns:
- Order ID (the same parameter included in the order JSON as “id”)
- Final order status - This field can receive two parameters: “chargeback_fraud”, “chargeback_not_fraud”.
Once you have generated the CSV file - send it to Riskified as mentioned above.
Action 6: Test order flow
We encourage you to test your end-to-end order flow in production, before going live. You can simulate “approve” or “decline” decisions and make sure post-decision processes work as expected within your production environment. Please make sure to set a notification endpoint before testing your order flow.
You can create a test order by adding the order_type field to the order JSON and setting it to “test”. Alternatively, you can convert real-time orders to test orders while viewing the “real-time order” list. To do this, access the list, and then click the ‘Mark as test’ button that corresponds with the order you wish to convert. This will change the order type to “test”.
Note: You will not be able to revert the order type back to live after having made the change.
When your orders are labeled with order_type = test, you'll be able to follow the steps in Action 3: Test order flow section above.
- Riskified will not charge any fees for conducting tests in Production.
- This test will only work after a notification endpoint has been set.
- Test actions are only available for test orders.
After completing these steps, the technical integration with Riskified is complete. You are now ready to set the operational aspects of your account before going live.
Action 7: Sending Real-Time Orders in Shadow Mode:
It is highly recommended to start sending your real-time production orders in shadow mode (capture mode) at this point. Sending orders in real-time should not interfere with any of your current flows - Riskified will not send any decisions on these orders until the integration process is completed.
Riskified requires around 2 weeks (depending on the volume) of real-time data before going live, as this is the minimal time frame the automation and analytics teams need to analyze your data and build your customized automation models. The data will help in detecting any data issues with production orders well before going live when data issues cost time and money.
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:
- Enter the billing information as you would like it to appear on your monthly invoice.
- 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.
- 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.
You will be unable to complete the integration until certifying that you have read and understood Riskified's chargeback guarantee.
After completing the above steps, click the “Click here to complete setup” button in the set account menu to finalize 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.
For additional information or for any questions, email integrations@riskified.com