Sardine SDK Integration

The Sardine Risk SDK Integration allows your application to collect device intelligence and behavioral
biometrics from your end-users and correlate them with Cybrid's server-side transfer screening. This gives
Sardine richer signals to assess transaction risk — including device fingerprinting, bot detection, and
behavioral anomalies — beyond what is available from PII and transaction data alone.

The integration involves two independent channels that are linked by a shared session key:

• Client side — Your application initializes the Sardine SDK, which collects device signals
  asynchronously and sends them directly to Sardine. The session key tags those signals to a specific
  user session.
• Server side — When creating a transfer or execution, you pass the Sardine session GUID to the
  Cybrid API, which forwards the session key to Sardine during screening so it can match the device
  signals to the transaction.

Process Overview

1. Prerequisites — Obtain Sardine access credentials, a clientId from Cybrid,
   and configure custom subdomains for the Sardine SDK.

2. Step 1 — Install the Sardine SDK in your client
   application and initialize it with your clientId, environment, and subdomains.

3. Step 2 — Create a Sardine session by calling the Cybrid API.
   The response contains a sardine_session_key to pass to the SDK and a guid to include in the
   transfer or execution request.

4. Step 3 — Update the SDK configuration with
   the session key. The SDK will collect and send device signals to Sardine. Await the SDK call before
   submitting a transfer or execution.

5. Step 4 — Include the
   Sardine session guid in the transfer or execution request. The platform uses it to enable
   device-enriched risk screening.

Prerequisites

Before starting the integration, ensure the following are in place:

✅

Request your Sardine access credentials from Cybrid

Cybrid issues your Sardine access credentials once the Sardine integration is included in your
signed agreement. Contact Cybrid to have them provisioned:

• An NPM access token for the private Sardine SDK packages. See Sardine's Web SDK overview for the available web SDKs.
• A GitHub access token if you are integrating a mobile SDK, to access Sardine's mobile SDK libraries. See Sardine's Mobile SDK overview.

1. Sardine clientId — Cybrid will provide you with the Sardine clientId for your integration at
   onboarding time. Do not generate this yourself — use the value provided by Cybrid.

2. Custom subdomains — Sardine recommends routing SDK traffic through custom subdomains under your
   own domain. This has several benefits:

   • Increased Performance — Using a custom subdomain can result in a significant increase in
     accuracy in browsers with strict privacy features, such as Safari or Firefox. This is because the
     custom subdomain allows for the recognition of cookies as "first-party", which can extend the
     lifetime of device IDs and improve performance.
   • Ad-blocker Resistance — Ad-blockers will not block the JavaScript agent from sending
     identification requests to the server, as sending data to an internal URL (such as a subdomain) is
     allowed. This makes it less likely that the data being sent will be blocked.
   • Harder to Detect — Routing through a custom subdomain makes the fingerprinting process harder
     for automated blockers and fraudsters to detect, because requests sent directly to a separate
     third-party domain are easier to identify and block.

⚠️

Custom subdomains require DNS configuration

You must create two subdomains under your domain (for example, api.example.com and
p.example.com) and configure CNAME records pointing to Sardine's infrastructure. See Sardine's
Custom Subdomain Integration Guide
for the full setup instructions, including CNAME records, CAA configuration, and certificate provisioning.

Step 1: Install and Initialize the Sardine SDK

Follow Sardine's recommendations on where and how to initialize the SDK in your application to best
capture device signals and behavior biometrics across your user flows.

⚠️

Behavior Biometrics consent required

If you use Sardine's Behavior Biometrics feature, ensure that your End User agrees to your privacy
policy before you begin collecting their Behavior Biometric data.

1.1 Install the SDK

Add the Sardine NPM access token to your .npmrc file:

//registry.npmjs.org/:_authToken=${NPM_TOKEN}

Then install the appropriate package for your framework:

npm install @sardine-ai/web-sdk

For mobile applications, refer to Sardine's Mobile SDK documentation.

1.2 Initialize the SDK

Initialize the SDK once at application startup, before any user interaction. Pass the clientId
provided by Cybrid and the target environment (sandbox or production). If you configured custom
subdomains in the Prerequisites, include them here.

import { setupSardine } from '@sardine-ai/web-sdk';

setupSardine({
  clientId: 'YOUR_CYBRID_PROVIDED_CLIENT_ID',
  environment: 'sandbox', // or 'production'
  apiSubdomain: 'api.example.com',   // recommended — your configured API subdomain
  pixelSubdomain: 'p.example.com',   // recommended — your configured pixel subdomain
});

ℹ️

More SDK options

The examples above cover the web JS and React SDKs. Sardine provides SDKs for other platforms — see Sardine's Risk SDK overview for the full list.

Step 2: Create a Sardine Session

Create a Sardine session by calling the Cybrid API to obtain the session key for your client SDK
integration. The response returns a sardine_session_key (the UUID to pass to the Sardine SDK in
Step 3) and a guid (the Cybrid session identifier to include in your transfer or execution request
in Step 4).

POST /api/sardine_sessions — Cybrid API docs

Required scope: sardine_sessions:execute

{
  "customer_guid": "customer_guid"
}

ℹ️

customer_guid is inferred for customer tokens

If your application uses a customer-scoped access token, customer_guid is derived from the token
automatically and the field may be omitted.

Request Body Field Reference

{
  "guid": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
  "sardine_session_key": "550e8400-e29b-41d4-a716-446655440000",
  "customer_guid": "customer_guid",
  "expires_at": "2026-01-01T01:00:00.000Z"
}

Response Field Reference

⚠️

Be mindful of expires_at

Check this value before submitting a transfer or execution and refresh the session if it is close to
expiry. See Session Key Lifecycle for when and how to refresh.

ℹ️

Store session values for subsequent steps

Store both the guid and the sardine_session_key in your application state for use in Steps 3 and 4.

Step 3: Configure the SDK and Collect Device Signals

Update the Sardine SDK configuration with the sardine_session_key returned in Step 2 and follow Sardine's recommendations on when and how to update the session key throughout your user flows to ensure device signals are captured before the transfer or execution is submitted.

The flow value is a label you define to identify the stage of your application (for example,
"transfer" or "checkout").

import { updateSardineConfig } from '@sardine-ai/web-sdk';

await updateSardineConfig({
  customerId: 'YOUR_CUSTOMER_ID',
  sessionKey: sardineSessionKey,  // sardine_session_key from Step 2
  flow: 'transfer',
});

⚠️

Always await the SDK call before submitting the transfer or execution

If you call the Cybrid API before the SDK callback completes, Sardine will not find device data for
that session and the request will be screened without device signals.

Step 4: Submit a Transfer or Execution with the Sardine Session GUID

Include the sardine_session_guid field using the guid returned in Step 2 when creating a transfer
or execution. The platform uses it to correlate the device signals collected by the Sardine SDK with
the screening request.

⚠️

Ensure device signals have been sent to Sardine before calling this API

Complete Step 3 and await the SDK callback before submitting a transfer or execution. If you call
this API before the SDK has finished sending signals, Sardine will not be able to match device data
to the session and the request will be screened without device intelligence.

ℹ️

Backward compatible

If sardine_session_guid is omitted or null, the transfer or execution is screened using
server-side data only. Existing integrations continue to work unchanged.

Transfers

POST /api/transfers — Cybrid API docs

Required scope: transfers:execute

The sardine_session_guid field is supported for funding and instant_funding transfer types.

{
  "quote_guid": "quote_guid",
  "transfer_type": "funding",
  "external_bank_account_guid": "external_bank_account_guid",
  "source_participants": [
    {
      "type": "customer",
      "guid": "customer_guid",
      "amount": 10000
    }
  ],
  "destination_participants": [
    {
      "type": "customer",
      "guid": "customer_guid",
      "amount": 10000
    }
  ],
  "sardine_session_guid": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"
}

Executions

POST /api/executions — Cybrid API docs

Required scope: executions:execute

{
  "plan_guid": "plan_guid",
  "sardine_session_guid": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"
}

Session Key Lifecycle

Expiry

The expires_at field in the session creation response indicates when the session key expires.

When expires_at is set:

• Check expires_at before submitting a transfer or execution. If the session has expired, create
  a new one before calling updateSardineConfig / updateSardineConfigAsync and proceeding.
• Refresh at least whenever the user's session is refreshed. A Sardine session should not outlive
  the user's authenticated session.

Reuse Across Transactions

You may reuse the same Sardine session key across multiple transfers within the same user session.
Reusing the key allows Sardine to accumulate device signals across the session, which can improve risk
assessment accuracy. There is no need to create a new session for each transfer as long as the session
has not expired.

When to Create a New Session

Create a new Sardine session when:

• The current session has expired (expires_at is in the past).
• The user logs out and back in.
• You receive an invalid_sardine_session or sardine_session_expired error on a transfer or
  execution (see API Errors below).

API Errors

Session Creation Errors

Transfer and Execution Errors

These errors are returned when POST /api/transfers or POST /api/executions includes a
sardine_session_guid that is not found or has expired. When you receive either error, create a new
Sardine session (Step 2), re-initialize the SDK with the new session key (Step 3), and resubmit the
request with the new sardine_session_guid.

For full API schema details, see the
Create Sardine Session API reference.