Ravelin

Screen payments with Ravelin 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

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

Load the Ravelin provider in the Payrails Web Fraud SDK with your publishable key, or pass the device ID from your own Ravelin integration in meta.risk.sessions.
Add a Fraud Check step with your Ravelin integration to your workflow. See Authorization with fraud screening.

Request fields for Ravelin

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

Authorize request

{
  "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" }
      }
    }
  }
}

Getting Started

Payment Orchestration

Token Vault

Analytics & Reporting

Fraud Management

Chargebacks

Monitoring

Resources

Use Cases

Supported operations

Decisions

Before you begin

Request fields for Ravelin

Send order updates

Report disputes

Example authorize request

​Supported operations

​Decisions

​Before you begin

​Request fields for Ravelin

​Send order updates

​Report disputes

​Example authorize request

Supported operations

Decisions

Before you begin

Request fields for Ravelin

Send order updates

Report disputes

Example authorize request