Riskified

Screen orders with Riskified at two points in your workflow. Before authorization, Riskified advises whether to proceed. After a successful authorization, Payrails submits the order for review, and Riskified sends its final decision to Payrails by webhook. Payrails also keeps Riskified updated on cancellations, refunds, fulfilment and declined payments.

Supported operations

Operation	Supported	Riskified endpoint
Pre-authorization score	✔	Advise, with the decision in the response
Post-authorization score	✔	Submit, with the decision by webhook
Order updates	✔	Cancel, refund, decision and checkout denied
Dispute reporting	✖

After a post-authorization score, the Fraud Check step pauses until Riskified’s decision arrives. Payrails verifies the webhook’s signature with your secret key, then resumes the workflow with the decision.

Decisions

Riskified result	Payrails decision
Advise: `proceed`	`Allow`
Advise: `decline`	`Prevent`
Webhook: `approved`	`Allow`
Webhook: `declined`	`Prevent`

Before you begin

In the Payrails Portal, go to Settings → Integrations and select Add instance.
Select the workspaces where Riskified should be available.
Select Fraud as the integration type, then Riskified as the provider.
Enter your Riskified credentials and save:

Field	Description
Shop Domain	Your shop domain registered with Riskified.
Secret Key	Your Riskified authentication token. Payrails signs every request with it and verifies Riskified’s webhooks.

In test mode, Payrails sends requests to the Riskified sandbox.

Pass the session ID from Riskified’s beacon script in meta.risk.sessions.
Add a Fraud Check step before your authorize step, and another one after it for the post-authorization review. See Authorization with fraud screening.

Request fields for Riskified

Send these fields in the authorize request, in addition to the standard authorize fields. Required fields must be present for the score to succeed. Payrails sends Optional fields to Riskified when you include them.

Field	Status	Description
`amount`	Required	Sent to Riskified as the order total price.
`meta.customer.email`	Required	Sent to Riskified as the order and customer email.
`meta.customer.name`, `meta.customer.lastName`	Required	Sent to Riskified as the customer’s first and last name.
`meta.customer.createdAt`	Required	Sent to Riskified as the customer account creation date.
`meta.clientContext.ipAddress`	Required	Sent to Riskified as the browser IP address.
`meta.clientContext.userAgent`	Required	Sent to Riskified in the client details.
`meta.clientContext.language`	Required	Sent to Riskified as the accepted language.
`meta.risk.sessions`	Required	An entry with `provider` set to `riskified` and the beacon session ID as `sessionId`. Sent to Riskified as the cart token. Payrails falls back to `meta.risk.sessionId` when there’s no Riskified entry.
`meta.order.lines`	Required	At least one line. Sent to Riskified as line items, with `id`, `name`, `quantity`, `unitPrice`, `categoryId`, `product.type` and `brand`. Tax and discount lines are left out.
`meta.order.billingAddress`	Required	Sent to Riskified as the billing address.
`meta.order.deliveryAddress`	Optional	Sent to Riskified as the shipping address. Payrails uses the billing address when it’s missing.
`meta.order.createdAt`	Optional	Sent to Riskified as the order creation time. Payrails uses the execution creation time when it’s missing.
`meta.order.shipping`, `meta.order.shippingType`	Optional	Sent to Riskified as the shipping line price and title.
`meta.order.totalDiscount`	Optional	Sent to Riskified as the order discounts.
`meta.customer.reference`	Optional	Sent to Riskified as the customer ID.
`meta.customer.phone`	Optional	Sent to Riskified as the customer phone.
`meta.customer.birthDate`	Optional	Sent to Riskified as the customer’s date of birth.
`meta.customer.previousPurchaseCount`	Optional	Sent to Riskified as the customer’s order count.
`meta.customer.previousOrders`	Optional	Payrails adds up the amounts and sends the total to Riskified as the customer’s total spend.
`meta.clientContext.clientType`	Optional	Sets the order source to desktop web, mobile web or mobile app.
`meta.subscription`	Optional	Sets the order source to subscription.
`meta.vendor.name`	Optional	Sent to Riskified as the vendor name.
`meta.risk.skipFraudDecision`	Optional	Set it to `true` for an order you already trust, for example after a liability shift. The post-authorization submit then completes with `Allow` straight away, and Riskified records the order as a rule decision.

For a post-authorization score, Payrails also sends the authorization from the earlier authorize step: the PSP as the gateway, the PSP reference as the authorization ID, the card or wallet details, AVS and CVV results, and the 3D Secure result.

Send order updates

Add a Fraud Update step after each lifecycle action and set its orderStatus. Payrails picks the Riskified endpoint from the status.

Payrails order status	Riskified update
`merchantCancelled`	Cancel, merchant initiated
`customerCancelled`	Cancel, customer initiated
`partiallyReturned`	Refund, partial return. Needs the refunded amount.
`fullyReturned`	Refund, customer return. Needs the refunded amount.
`partiallyShipped`, `fullyShipped`, `partiallyDelivered`, `fullyDelivered`, `partiallyReplaced`, `fullyReplaced`	Decision, `approved`
`failed`	Decision, `declined`
`noShow`	Decision, `declined_business`

When the authorize step fails, a Fraud Update step on that path sends Riskified a checkout denied update with the declined payment, whatever the order status.

Example authorize request

Authorize request

{
  "amount": { "value": "64.00", "currency": "USD" },
  "paymentComposition": [
    {
      "integrationType": "api",
      "paymentMethodCode": "card",
      "amount": { "value": "64.00", "currency": "USD" }
    }
  ],
  "meta": {
    "customer": {
      "reference": "customer-3307",
      "name": "Maya",
      "lastName": "Johnson",
      "email": "maya.johnson@example.com",
      "createdAt": "2023-06-21T14:12:00Z",
      "previousPurchaseCount": 4
    },
    "clientContext": {
      "ipAddress": "203.0.113.10",
      "userAgent": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_5 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.5 Mobile/15E148 Safari/604.1",
      "language": "en-US",
      "clientType": "mobileWeb"
    },
    "risk": {
      "sessions": [{ "provider": "riskified", "sessionId": "c8a1f0e2-7b4d-4c39-9a51-3e2d6f8b1a07" }]
    },
    "order": {
      "lines": [
        {
          "id": "sku-1290",
          "name": "Yoga mat",
          "quantity": 2,
          "unitPrice": { "value": "32.00", "currency": "USD" },
          "product": { "type": "physical" }
        }
      ],
      "billingAddress": {
        "name": "Maya",
        "lastName": "Johnson",
        "street": "450 Market Street",
        "city": "San Francisco",
        "state": "CA",
        "postalCode": "94105",
        "country": { "code": "US" }
      }
    }
  }
}

Getting Started

Payment Orchestration

Token Vault

Analytics & Reporting

Fraud Management

Chargebacks

Monitoring

Resources

Use Cases

Supported operations

Decisions

Before you begin

Request fields for Riskified

Send order updates

Example authorize request

​Supported operations

​Decisions

​Before you begin

​Request fields for Riskified

​Send order updates

​Example authorize request

Supported operations

Decisions

Before you begin

Request fields for Riskified

Send order updates

Example authorize request