Riskified

Riskified is an e-commerce fraud prevention platform that uses machine learning and behavioral analytics to provide real-time fraud decisions. Riskified’s anti-fraud decisions can be used in Flow to trigger any action.

Credentials

To configure a Riskified connection, you need to set the following credentials.

Credential	Description
Shop Domain	Your unique shop domain with Riskified
Auth Token	The authentication token for the Riskified API

Limited actions

By default, Gr4vy sends transaction status updates to Riskified for all transaction events, including refunds and voids. However, you can enable the Limited Actions flag in the connector configuration to limit these updates. When the Limited Actions flag is enabled, Gr4vy only sends transaction status updates to Riskified during the initial transaction processing. Status updates for refund or void events are not sent to Riskified.

Decision mapping

Decisions received from Riskified are mapped to the decisions according to the following logic.

Riskified decision	Decision
`approve`	`accept`
`decline`	`reject`
`captured`	`skipped`

As Riskified’s product does not have a manual review queue, only accept or reject decisions are returned. A captured response can also be returned by Riskified, if you have set up a configuration with Riskified to only review a part of your volume. If there is a technical issue reaching Riskified, the decision returns as an exception.

Data requirements

To receive accurate anti-fraud recommendations from Riskified, it is important to provide comprehensive transaction data. While Riskified attempts to process transactions with limited data, providing the following fields significantly improves the quality and accuracy of fraud decisions.

Recommended fields

For optimal fraud detection, it is highly recommended to include billing details with the following fields:

billing_details.first_name
billing_details.last_name
billing_details.phone_number
billing_details.address.line1
billing_details.address.country
billing_details.address.city
billing_details.address.postal_code
billing_details.address.state

If shipping details are provided, it is recommended to include the following fields:

shipping_details.first_name
shipping_details.last_name
shipping_details.phone_number
shipping_details.address.line1
shipping_details.address.country
shipping_details.address.city
shipping_details.address.postal_code
shipping_details.address.state

Browser information

For optimal fraud detection accuracy, Riskified benefits from the following browser data being associated with a transaction.

Requirement	Description
Language	The value of the `ACCEPT-LANGUAGE` header
User agent	The browser user agent
IP	The browser IP

When using Embed or one of the e-commerce plugins, all of these values are automatically set. If you create transactions by using direct API calls, it is recommended to include all transaction.browser_info fields. For the full list of fields, see the browser_info object in the new transaction API reference. Please refer to the IP address forwarding guide for more details on passing the IP address when making direct API calls.

Custom options

You can pass Riskified-specific options using connection options under the riskified-anti-fraud key.

These options mirror Riskified’s own API format, including its field names. Where a field also exists on a Gr4vy address, the Riskified name and format take precedence, so that you can write these options directly from Riskified’s reference.

Options	Description
`line_items`	Per-item overrides, matched by position against the cart items sent to Riskified.
`shipping_lines`	Per-delivery-charge overrides, matched by position against the `shipping_fee` cart items.
`additional_shipping_addresses`	Extra destinations for orders shipped to more than one address.

Line items

Field	Description
`delivered_to`	The delivery destination for the item. Valid values: `shipping_address`, `store_pickup`.
`shipping_address_id`	The address this item ships to. See Multiple shipping addresses.

Shipping lines

Field	Description
`shipping_address_id`	The address this delivery charge applies to.

Both options are matched by position, against two separate sequences.line_items entries are matched against the cart items Gr4vy sends to Riskified, which excludes discount, shipping_fee, sales_tax and store_credit items. A shipping fee in the middle of your cart_items shifts every override after it.shipping_lines entries are matched against the shipping_fee items only, in the order they appear in cart_items.

Multiple shipping addresses

A transaction holds one set of shipping details. For split shipments, supply the other destinations in additional_shipping_addresses. The transaction’s address is always sent first, and these are appended after it.

Field	Description
`id`	Required. Unique identifier, referenced by `shipping_address_id`. Cannot be `base-shipping-address`.
`first_name`, `last_name`, `phone`	The recipient at this address. `phone` must be formatted according to the E164 standard.
`address1`, `address2`	The first and second lines of the address.
`city`, `zip`, `company`	The city, zip or postal code, and company name for the address.
`country_code`	The country for the address in ISO 3166 format, for example `US`.
`province`, `province_code`	The state or province, and its code.

The country name sent to Riskified is derived from country_code and cannot be supplied directly.

province_code follows Riskified’s format, which is the subdivision code on its own, for example NY. This differs from the Gr4vy state_code field on a buyer or transaction address, which is ISO 3166-2 and includes the country prefix, for example US-NY. Gr4vy converts state_code to Riskified’s format automatically for the transaction’s own address.

Address ids

The address derived from the transaction always uses the reserved id base-shipping-address. Ids are only sent when an order ships to more than one destination, so a single-destination order sends no ids at all and shipping_address_id must not be provided in that case. shipping_address_id is optional on every entry. When an order ships to more than one destination, Gr4vy sends an address id on every line item and shipping line, using the transaction’s address for anything you did not target.

{
  "cart_items": [
    { "name": "Blue Shirt", "quantity": 1, "unit_amount": 4999, "product_type": "physical" },
    { "name": "Shipping", "quantity": 1, "unit_amount": 500, "product_type": "shipping_fee" },
    { "name": "Red Shoes", "quantity": 1, "unit_amount": 8000, "product_type": "physical" }
  ],
  "connection_options": {
    "riskified-anti-fraud": {
      "additional_shipping_addresses": [
        {
          "id": "secondary-address",
          "first_name": "Jane",
          "last_name": "Roe",
          "address1": "456 Market Street",
          "city": "New York",
          "province": "New York",
          "province_code": "NY",
          "zip": "10001",
          "country_code": "US"
        }
      ],
      "line_items": [
        { "delivered_to": "shipping_address" },
        { "delivered_to": "shipping_address", "shipping_address_id": "secondary-address" }
      ],
      "shipping_lines": [{ "shipping_address_id": "secondary-address" }]
    }
  }
}

The overrides line up as follows. Note that the shipping fee sits between the two products in cart_items, but does not take up a position in line_items:

Override	Applies to
`line_items[0]`	Blue Shirt
`line_items[1]`	Red Shoes
`shipping_lines[0]`	Shipping

Blue Shirt ships to the transaction’s address, since its override sets no shipping_address_id. Red Shoes and the delivery charge ship to secondary-address.

Cart items

Gr4vy maps cart_items to line_items in the Riskified payload.

The sum of all cart item amounts must equal the transaction’s total amount.
It is recommended to include a shipping line item if there are physical items.
If a shipping line item is included, its title is mandatory. Set the title to store_pickup for store pickup orders.
If the order is not a store pickup order, shipping details must be attached to the transaction. You can provide them in one of the following ways:
- Store them against the buyer using the new buyer shipping detail API.
- Include them directly on the transaction using the buyer.shipping_details field in the new transaction API.

Device fingerprinting

Device fingerprinting is recommended when using Riskified. Please refer to the device fingerprinting guide for more information on the universal solution. If needed, you could load the fingerprint script for Riskified directly and pass the session_id value as the anti_fraud_fingerprint to the new transaction API.

Introduction

Aggregators

Methods

Digital wallets

Anti-fraud

Browse

Credentials

Limited actions

Decision mapping

Data requirements

Recommended fields

Browser information

Custom options

Line items

Shipping lines

Multiple shipping addresses

Address ids

Cart items

Device fingerprinting

​Credentials

​Limited actions

​Decision mapping

​Data requirements

​Recommended fields

​Browser information

​Custom options

​Line items

​Shipping lines

​Multiple shipping addresses

​Address ids

​Cart items

​Device fingerprinting

Credentials

Limited actions

Decision mapping

Data requirements

Recommended fields

Browser information

Custom options

Line items

Shipping lines

Multiple shipping addresses

Address ids

Cart items

Device fingerprinting