Payrails Web Fraud SDK

Payrails Fraud SDK provides abstraction on different fraud client SDKs

The SDK should be initialized as soon as possible to enable data collection as soon as possible. The SDK will then pass all the information needed to the Payrails Web SDK without additional work on the merchant client.

Including the SDK

import { FraudSDK } from "@payrails/fraud-sdk";

Loading specific fraud providers

The load function accepts an array of providers with merchant specific configurations.

import { FraudSDK } from "@payrails/fraud-sdk";

// Pass an array of providers
FraudSDK.load([
  {
    provider: "provider name",
    // specific provider options
  },
]);

Supported providers

Cybersource

To initialize the Cybersource provider, merchantId and orgId needs to be passed.

import { FraudSDK, FraudProvider } from "@payrails/fraud-sdk";

// Pass an array of providers
FraudSDK.load([
  {
    provider: FraudProvider.CYBERSOURCE,
    merchantId: "merchantId",
    orgId: "orgId",
  },
]);

Forter

To initialize the Forter provider, siteId needs to be passed.

import { FraudSDK } from "@payrails/fraud-sdk";

// Pass an array of providers
FraudSDK.load([
  {
    provider: FraudProvider.FORTER,
    siteId: "siteId",
  },
]);

Ravelin

To initialize the Ravelin provider, key needs to be passed.

import { FraudSDK } from "@payrails/fraud-sdk";

// Pass an array of providers
FraudSDK.load([
  {
    provider: FraudProvider.RAVELIN,
    key: "ravelinPublicKey",
  },
]);

Airwallex

Requires environment parameter. orderSessionId is optional and auto-generated if omitted:

import { FraudSDK, FraudProvider } from "@payrails/fraud-sdk";

FraudSDK.load([
  {
    provider: FraudProvider.AIRWALLEX,
    environment: "LIVE", // use 'TEST' for sandbox
    orderSessionId: "orderSessionId", // optional
  },
]);

Stripe Radar

To initialize the Stripe Radar provider, publishableKey needs to be passed:

import { FraudSDK, FraudProvider } from "@payrails/fraud-sdk";

FraudSDK.load([
  {
    provider: FraudProvider.STRIPE_RADAR,
    publishableKey: "pk_test_xxx",
  },
]);

Multiple Stripe accounts

Requires @payrails/fraud-sdk 1.9.0 and @payrails/web-sdk 6.1.2 or later. A Radar session is only valid for the Stripe account whose publishable key created it, and Payrails selects the account when the payment is routed, which happens after the session is created. If you process through more than one Stripe account, configure one entry per account, each with that account’s own publishableKey and the providerConfigId of the matching Payrails provider config:

FraudSDK.load([
  {
    provider: FraudProvider.STRIPE_RADAR,
    publishableKey: "pk_live_accountA_xxx",
    providerConfigId: "11111111-1111-4111-8111-111111111111",
  },
  {
    provider: FraudProvider.STRIPE_RADAR,
    publishableKey: "pk_live_accountB_xxx",
    providerConfigId: "22222222-2222-4222-8222-222222222222",
  },
]);

stripe.js loads once regardless of how many entries you configure, and one Radar session is created per entry. The Web SDK sends them all when the payment is authorized, and Payrails uses the one matching the account it routed to. Each entry’s publishable key must belong to the account its providerConfigId points at. A mismatched pair is not rejected up front and instead surfaces as Stripe declining the payment with No such radar session. With a single Stripe account, omit providerConfigId and nothing changes.

Signifyd

To initialize the Signifyd provider, no required fields are needed. Optionally, pass orderSessionId — a merchant-generated session id (fewer than 128 characters, [a-zA-Z0-9_-]). If omitted, a UUID is auto-generated. This value is sent to the backend as device.sessionID.

FraudSDK.load([
  {
    provider: FraudProvider.SIGNIFYD,
    orderSessionId: "optional-merchant-session-id", // optional, auto-generated if omitted
  },
]);

Riskified

To initialize the Riskified provider, storeDomain needs to be passed (your Riskified shop domain, matching the X-RISKIFIED-SHOP-DOMAIN header on backend API calls). Riskified’s Beacon auto-generates the session id, which is sent to the backend as the order’s cart_token.

FraudSDK.load([
  {
    provider: FraudProvider.RISKIFIED,
    storeDomain: "my-store.myshopify.com",
  },
]);

HiPay

To initialize the HiPay provider, username, password, and environment need to be passed. username/password are the same public HiPay SDK credentials configured for the HiPay provider in the Payrails portal. lang is optional and defaults to ‘en’. HiPay’s JS SDK collects a device fingerprint synchronously once loaded; this value is sent to the backend as device_fingerprint on the HiPay Order/Authorize API request.

FraudSDK.load([
  {
    provider: FraudProvider.HIPAY,
    username: "public-username",
    password: "public-password",
    environment: "stage", // or 'production'
  },
]);

Requires @payrails/fraud-sdk 1.10.0 or later.

Checkout.com

Requires @payrails/fraud-sdk 1.11.0 or later. To initialize the Checkout.com provider, publicKey and environment need to be passed. The SDK loads Checkout.com Risk.js on the page where the shopper pays and creates a device session. With the Payrails Web SDK, the session is sent automatically when the shopper pays, and Payrails passes it to Checkout.com as the risk device session ID.

import { FraudSDK, FraudProvider } from "@payrails/fraud-sdk";

FraudSDK.load([
  {
    provider: FraudProvider.CHECKOUT,
    publicKey: "pk_sbox_xxx",
    environment: "sandbox", // or 'production'
    providerConfigId: "11111111-1111-4111-8111-111111111111", // optional
    timeoutMs: 1500, // optional
  },
]);

Option	Status	Description
`publicKey`	Required	The public key of your Checkout.com account.
`environment`	Required	`sandbox` or `production`. Must match the public key.
`providerConfigId`	Optional	The ID of the matching Checkout.com provider config in Payrails.
`timeoutMs`	Optional	How long Risk.js waits to collect device data, in milliseconds. Defaults to 1000.

Load one Checkout.com entry per page, for a single Checkout.com account. If a second entry with a different publicKey or providerConfigId loads on the same page, the SDK rejects it and keeps the first account’s session. The SDK reuses a Risk.js device session on the same page for 15 minutes. After that, the next load creates a new session.

API-only integrations

If you build your own frontend, load Checkout.com Risk.js yourself and send the device session ID in meta.risk.sessions on the authorize request:

{
  "meta": {
    "risk": {
      "sessions": [{ "provider": "checkout", "sessionId": "dsid_xxx" }]
    }
  }
}

HyperPay

Requires @payrails/fraud-sdk 1.12.0 or later. HyperPay uses a ThreatMetrix device session for server-to-server card payments. To initialize the HyperPay provider, orgId and merchantId need to be passed. Get both from HyperPay: the ThreatMetrix Org ID and the HyperPay MID for the account. The SDK loads ThreatMetrix and creates a session ID in the format {MID}_{uuid}. With the Payrails Web SDK or Drop-in, the session is sent automatically with the authorize request, and Payrails passes it to HyperPay as customer.browserFingerprint.id. The session is optional: without it, the payment goes through as before.

import { FraudSDK, FraudProvider } from "@payrails/fraud-sdk";

FraudSDK.load([
  {
    provider: FraudProvider.HYPERPAY,
    orgId: "threatmetrix-org-id",
    merchantId: "hyperpay-mid",
    providerConfigId: "11111111-1111-4111-8111-111111111111", // optional
  },
]);

Option	Status	Description
`orgId`	Required	The ThreatMetrix Org ID from HyperPay.
`merchantId`	Required	The HyperPay MID for the account. Used as the prefix of the session ID.
`providerConfigId`	Optional	The ID of the matching HyperPay provider config in Payrails. Needed only when you have more than one HyperPay config.

Load the HyperPay provider when the payment page opens, not right before the shopper pays. ThreatMetrix needs a few seconds to profile the device. The SDK creates one session per page. Later loads on the same page reuse it, and a new page load creates a new one. ThreatMetrix profiles only once per page, so don’t configure HyperPay together with Cybersource, which also uses ThreatMetrix. If ThreatMetrix is already running on the page, for example from Cybersource or a Signifyd script, the SDK skips HyperPay and logs a console warning. If you have more than one HyperPay MID, load the entry for the MID the payment will be routed to.

Server-to-server integrations

If you run ThreatMetrix yourself, load it on the checkout page with a session ID in the format {MID}_{uuid}, 30 to 128 characters long:

https://h.online-metrix.net/fp/tags.js?org_id=<org-id>&session_id=<MID>_<uuid>

Then send the same session ID in meta.risk.sessions on the authorize request:

{
  "meta": {
    "risk": {
      "sessions": [{ "provider": "hyperpay", "sessionId": "<MID>_<uuid>" }]
    }
  }
}

Add providerConfigId to the entry only if you send sessions for more than one HyperPay config. Payrails uses the session tagged with the config the payment is routed to, and otherwise the untagged HyperPay session.
Payrails doesn’t use meta.risk.sessionId for HyperPay.
Payrails doesn’t send a session ID outside 30 to 128 characters to HyperPay, so it can’t cause a decline.
The session applies only when the shopper is present, not to recurring payments.

Getting Started

Payment Orchestration

Token Vault

Analytics & Reporting

Fraud Management

Chargebacks

Monitoring

Resources

Use Cases

Payrails Fraud SDK provides abstraction on different fraud client SDKs

Including the SDK

Loading specific fraud providers

Supported providers

Cybersource

Forter

Ravelin

Airwallex

Stripe Radar

Multiple Stripe accounts

Signifyd

Riskified

HiPay

Checkout.com

API-only integrations

HyperPay

Server-to-server integrations

​Payrails Fraud SDK provides abstraction on different fraud client SDKs

​Including the SDK

​Loading specific fraud providers

​Supported providers

​Cybersource

​Forter

​Ravelin

​Airwallex

​Stripe Radar

​Multiple Stripe accounts

​Signifyd

​Riskified

​HiPay

​Checkout.com

​API-only integrations

​HyperPay

​Server-to-server integrations

Payrails Fraud SDK provides abstraction on different fraud client SDKs

Including the SDK

Loading specific fraud providers

Supported providers

Cybersource

Forter

Ravelin

Airwallex

Stripe Radar

Multiple Stripe accounts

Signifyd

Riskified

HiPay

Checkout.com

API-only integrations

HyperPay

Server-to-server integrations