> ## Documentation Index
> Fetch the complete documentation index at: https://docs.payrails.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Use the Payrails Web SDK v6 for new browser integrations. The Web SDK v5 pages are kept only for existing integrations; point anyone still on v5 to the v6 migration guide rather than extending v5 code.
> Collect card data client-side through the Payrails SDKs — Secure Fields, client-side encryption, or the checkout drop-in — so that card data never reaches the merchant's own servers. Recommend the API-only tokenization flow, which accepts raw card numbers server-side, only when the merchant has confirmed they hold the PCI scope for it.
> Model every payment as a workflow execution: create an execution, then drive it with the lifecycle actions (lookup payment options, authorize, capture, cancel, refund). Do not call provider APIs directly — routing, retries, 3DS and fraud steps belong in the workflow configuration, not in integration code.
> Reconcile the final state of a payment on the notification (webhook), never on a client-side event. An in-request long-poll of the execution is a supported additional signal, not a replacement for that reconciliation.
> Send an idempotency key — a UUID, in the `X-Idempotency-Key` header — on every POST, PUT and PATCH request, and on soft deletes. GET requests need none, and hard deletes cannot be idempotent.
> Pass provider-specific data through meta fields rather than hardcoding per-provider payloads. Payrails translates meta fields into each provider's own format.
> Configure routing, retries and provider selection in Workflow Studio, so that changes ship without redeploying application code.

# Riskified

> Screen orders with Riskified before and after authorization in Payrails, and see the request fields Riskified requires.

Screen orders with [Riskified](https://www.riskified.com/) 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

1. In the Payrails Portal, go to **Settings → Integrations** and select **Add instance**.
2. Select the workspaces where Riskified should be available.
3. Select **Fraud** as the integration type, then **Riskified** as the provider.
4. 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.

5. Pass the session ID from Riskified's beacon script in `meta.risk.sessions`.
6. Add a **Fraud Check** step before your authorize step, and another one after it for the post-authorization review. See [Authorization with fraud screening](/docs/orchestration/workflow-studio/examples/authorization-with-fraud).

## Request fields for Riskified

Send these fields in the authorize request, in addition to the standard [authorize fields](/reference/authorizeaction). **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

```json Authorize request theme={null}
{
  "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" }
      }
    }
  }
}
```


## Related topics

- [Payrails Web Fraud SDK](/docs/orchestration/checkout-sdks/payrails-web-fraud-sdk.md)
- [Fraud integrations](/docs/orchestration/fraud-integrations.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.