Riskified Documentation

Stripe Platform Integration Guide


This guide provides an overview of the integration process for merchants who would like to use Riskified for stripe transactions only, and it includes step-by-step instructions to completing the integration. If you would like Riskified to review any other payment methods, please integrate via our API, or see our Guide for API Integration with Stripe as Gateway.

Please note, you can also use the instructions provided within the integration management application to guide you through the integration steps. You will gain access to the integration management application after a Riskified Account Executive creates an account or you and an invitation to activate your account will be sent to your inbox.

The stripe platform integration encompasses some 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 three main technical components required for a full integration are: connecting Riskified with Stripe, setting a notification endpoint, and embedding the Riskified storefront beacon.


Data flow

Riskified’s 3rd party access to Stripe ensures that Stripe information pertaining to every order placed in your store is relayed. 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 callback. 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 will receive notice about the final status of the order, whether it is refunded, cancelled, or if a chargeback was incurred directly from Stripe.


Integration process - Development and testing

Riskified’s Stripe platform integration was developed to deliver a simple and efficient process. While it saves substantial development time, it does require significant testing to 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 (sources / product types 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: Connect Riskified with Stripe

In this step, you will connect Stripe’s test environment with Riskified’s Sandbox environment.

  1. Within the Riskified integration management application, click the 'Connect with Stripe' button. Once you click the button, you will be directed to a Stripe authorization page (see screenshot below)

    You can also use the following link.

  2. To connect Riskified with Stripe, you must be logged in to your Stripe account. If you are not signed in to Stripe, click 'Sign in with Stripe to connect'. If you are already logged in to Stripe, click 'Connect my Stripe account'.

  3. You will then be redirected back to your Riskified Sandbox environment You will not be able to proceed to steps 2 and 3 until step 1 is successfully completed.

Action 2: Validate Order Data

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

Providing order data

You will need to add risk-related data to every Stripe-created charge. This includes:

  • Billing and shipping details - Riskified requires the charge's billing and shipping address (for physical goods). This information is provided using the standard Stripe Charge object. Please make sure your data Includes Stripe’s standard billing and shipping address.

  • Riskified-specific fields - Riskified requires additional data fields that will be sent through Stripe’s Charge Metadata hash. Please add the following fields to the metadata (note that Stripe has a 500 character limitation for the metadata field):

    1. ip (string) - The IP address of the browser used by the customer when placing the order
    2. user_agent (string) - The full User-Agent string sent from the client (usually browser)
    3. device_id (string) - The session id that this order was created on, this value should match the session id value that is passed in the beacon JavaScript.
    4. line_items (JSON String) - a shortened version of the Riskified API ‘line_items’ model as specified in our API. Each line_item hash should contain the following 3 fields only: title, quantity and price. They have been shortened to a single letter to ensure the JSON does not exceed the Stripe API metadata 500 character limit:
      • t
      • q
      • p
Example

The example below, written in Ruby, shows details of an entire order in correct format. Below it is the metadata hash:

        Stripe:Charge.create(amount: 100,
        currency: 'usd',
        customer: 'cus_2xRw4xWfm7ybdg',
        ....
        card: {
        address_line1: '9367 Route 41',
        address_line2: '6834 Aspen Court',
        address_city: 'Marshfield',
        address_country: 'IL',
        address_zip: '23320',
        address_state: 'VA'
        },
        shipping: {
          address: {
          line1: '9367 Route 41',
          line2: '6834 Aspen Court',
          city: ‘Marshfield',
          country: 'IL',
          postal_code: ‘23320',
          state: ‘VA'
         }
        },
        metadata: {
         ip: '200.123.123.113',
         device_id: '8355c377-4347-4a4f-9fe7-b0158cbfab29',
         user_agent: 'Mozilla/5.0 (Linux; U; Android 4.3; it-it; GT-I9300 Build/JSS15J) AppleWebKit/534.30 (KHTML, like Gecko) Version/4.0 Mobile Safari/534.30'
        },
        line_items:'[{"t":"milk","q":2,"p":10.00},{"t":"eggs","q":12,"p":15.00}]'
        });
      

Submitting orders for Validation

Once you’ve defined the fields necessary to relay order data, the data sent must be validated by Riskified to ensure there are no issues with format, content, or structure.

Created orders will appear in the order validation table and will 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 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 3: Set notification endpoint

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 4: 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 order flows/sources.

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.

Follow these steps to perform an end-to-end test:

  1. Click on the “Submit” button. The order status will change to “Under Review”

  2. Click either the "Approve" or "Decline" button. The order status will change accordingly and an email notification will be sent to your inbox

  3. Check that the processes set to be triggered within your systems by an approve or decline decision work as expected

After completing these 4 actions in the Sandbox environment, your account is ready to be moved to production. In the Sandbox menu, click “Activate my production account” in order 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. The user completing step 1 will be prompted to set their password within the integration management application. All other users we be sent an email inviting them to set their own password for their personal production login.


Step 3: Production

Action 1: Connect Riskified with Stripe

In this step, you will connect Stripe’s test environment with Riskified’s production environment.

  1. Within the Riskified integration management application, click the 'Connect with Stripe' button. Once you click the button, you will be directed to a Stripe authorization page (see screenshot below)

    You can also use the following link.

  2. To connect Riskified with Stripe, you must be logged in to your Stripe account. If you are not signed in to Stripe, click 'Sign in with Stripe to connect'. If you are already logged in to Stripe, click 'Connect my Stripe account'.

  3. You will then be redirected back to your Riskified Sandbox environment You will not be able to proceed to actions 2 and 3 until action 1 is successfully completed.

Action 2: 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.

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 Front-End Beacon

In this step you will implement the Riskified front-end 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 web beacon can be found here.
Detailed instructions for embedding the mobile beacon can be found herehere.

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.

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.