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.