> ## 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.

# Ravelin

> Screen payments with Ravelin in your Payrails workflow, report disputes, and see the request fields Ravelin requires.

Screen payments with [Ravelin](https://www.ravelin.com/) before or after authorization. Payrails sends Ravelin the order, customer, device and payment details and maps the Ravelin action to a Payrails decision your workflow acts on. Payrails also reports order updates and disputes to Ravelin, so its models learn from the outcome of each order.

## Supported operations

| Operation | Supported | Ravelin endpoint |
| - | - | - |
| Pre-authorization score | ✔ | Checkout, `checkoutPreAuth` score |
| Post-authorization score | ✔ | Checkout, `checkoutPostAuth` score, with the authorization result and 3D Secure data |
| Order updates | ✔ | Checkout, without a score |
| Dispute reporting | ✔ | Dispute |

Ravelin returns its decision in the response, so the Fraud Check step completes straight away. Payrails adds the Ravelin risk score to the result details.

## Decisions

| Ravelin action | Transaction optimisation | Payrails decision |
| - | - | - |
| `ALLOW` | `AUTHENTICATE` | `Challenge` |
| `ALLOW` | Any other | `Allow` |
| `REVIEW` | Any | `NoDecision` |
| `PREVENT` | Any | `Prevent` |

## Before you begin

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

| Field | Description |
| - | - |
| **Secret API Key** | Your Ravelin secret key. Payrails uses it to call Ravelin. |
| **Publishable API Key** | Your Ravelin publishable key. |
| **Use travel ticket departure country** | Optional. When on, Payrails sends the departure country of the first travel leg as the order country. |

5. Load the Ravelin provider in the [Payrails Web Fraud SDK](/docs/orchestration/checkout-sdks/payrails-web-fraud-sdk#ravelin) with your publishable key, or pass the device ID from your own Ravelin integration in `meta.risk.sessions`.
6. Add a **Fraud Check** step with your Ravelin integration to your workflow. See [Authorization with fraud screening](/docs/orchestration/workflow-studio/examples/authorization-with-fraud).

## Request fields for Ravelin

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 Ravelin when you include them.

| Field | Status | Description |
| - | - | - |
| `amount` | Required | Sent to Ravelin as the order price and transaction amount. |
| `meta.order.reference` | Required | Sent to Ravelin as the order ID. Keep it the same for the score, every order update and any dispute on the order. |
| `meta.order.lines` | Required | At least one line, each with a `quantity`. Sent to Ravelin as the order items, with `id`, `name`, `unitPrice` and `product.type`. |
| `meta.risk.sessions` | Required | An entry with `provider` set to `ravelin` and the Ravelin device ID as `sessionId`. Payrails falls back to `meta.risk.sessionId` when there's no Ravelin entry. |
| `meta.clientContext.ipAddress` | Required | Sent to Ravelin as the device IP address. |
| `meta.clientContext.userAgent` | Required | Sent to Ravelin as the device user agent. |
| `meta.clientContext.language` | Required | Sent to Ravelin as the device language. |
| `meta.customer.reference` | Optional | Sent to Ravelin as the customer ID. Payrails uses the phone number when it's missing. |
| `meta.customer.email` | Optional | Sent to Ravelin as the customer and order email. |
| `meta.customer.phone` | Optional | Sent to Ravelin as the customer telephone. |
| `meta.customer.createdAt` | Optional | RFC 3339 date-time. Sent to Ravelin as the registration time. |
| `meta.order.createdAt` | Optional | Sent to Ravelin as the order creation time. Payrails uses the execution creation time when it's missing. |
| `meta.order.deliveryAddress` | Optional | Sent to Ravelin as the delivery address. |
| `meta.order.billingAddress` | Optional | Sent to Ravelin as the payment method billing address. The name is also sent as the customer's name. |
| `meta.order.placement.country.code` | Optional | Sent to Ravelin as the order country. |
| `meta.order.lines[].travelTicket` | Optional | Sent to Ravelin as travel ticket details: passenger and route legs. |
| `meta.clientContext.osType` | Optional | Sent to Ravelin as the app platform. |
| `meta.vendor.name` | Optional | Sent to Ravelin as the app name. |

Payrails sends the payment method from the instrument: card BIN, last four digits and expiry for cards, the wallet for Apple Pay and Google Pay, and the PayPal email for PayPal. Before authorization, Payrails sends the payment method for card payments. After authorization, it sends it for every payment method, together with the authorization result and 3D Secure data.

## Send order updates

Add a **Fraud Update** step after each lifecycle action and set its `orderStatus`. Payrails sends Ravelin the matching order stage. Order updates also need the Ravelin session in `meta.risk.sessions`.

| Payrails order status | Ravelin stage | Reason |
| - | - | - |
| `pending` | `pending` | |
| `processing` | `accepted` | |
| `partiallyShipped`, `fullyShipped`, `partiallyDelivered`, `fullyDelivered`, `partiallyReplaced`, `fullyReplaced` | `fulfilled` | |
| `partiallyReturned`, `fullyReturned` | `refunded` | `returned` |
| `merchantCancelled` | `cancelled` | `merchant` |
| `customerCancelled` | `cancelled` | `buyer` |
| `noShow` | `cancelled` | `buyer` |
| `failed` | `failed` | `seller_rejected` |

## Report disputes

Payrails reports each dispute on an order to Ravelin, with its amount, reason code and stage, from early fraud warnings and retrievals through to chargebacks and arbitration. Ravelin links the dispute to the order through `meta.order.reference`.

## Example authorize request

```json Authorize request theme={null}
{
  "amount": { "value": "89.90", "currency": "GBP" },
  "paymentComposition": [
    {
      "integrationType": "api",
      "paymentMethodCode": "card",
      "amount": { "value": "89.90", "currency": "GBP" }
    }
  ],
  "meta": {
    "customer": {
      "reference": "customer-2044",
      "email": "sam.taylor@example.com",
      "createdAt": "2024-11-02T18:05:00Z"
    },
    "clientContext": {
      "ipAddress": "203.0.113.10",
      "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/128.0 Safari/537.36",
      "language": "en-GB"
    },
    "risk": {
      "sessions": [{ "provider": "ravelin", "sessionId": "rjs-8b2d41f0-6c7e-4a95-b3d1-0f9e2c5a7b64" }]
    },
    "order": {
      "reference": "order-58213",
      "lines": [
        {
          "id": "sku-771",
          "name": "Wireless headphones",
          "quantity": 1,
          "unitPrice": { "value": "89.90", "currency": "GBP" },
          "product": { "type": "physical" }
        }
      ],
      "deliveryAddress": {
        "street": "12 Brick Lane",
        "city": "London",
        "postalCode": "E1 6RF",
        "country": { "code": "GB" }
      }
    }
  }
}
```


## 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.