---
title: "Coinme Risk SDK for Web"
url: "https://platformdocs.coinme.com/#/docs/using-the-coinme-risk-sdk-for-web"
markdown: "https://platformdocs.coinme.com/docs/using-the-coinme-risk-sdk-for-web.md"
summary: "The Coinme Risk Engine SDK is a library, distributed as an NPM package, that allows you to interact with the Coinme Risk Engine from your application. It provides utilities that allow you to integrate against the Coinme risk engine for the various transactional flows in your application so that Coinme may appropriately assess transactional risk when processing transactions."
surface: "caas"
platform: "web"
package: "@coinme-security/risk-sdk-js"
version: "1.2.0"
source: "https://docs.coinme.com/docs/using-the-coinme-risk-sdk-for-web"
updated: "2026-10-28"
---

# Coinme Risk SDK for Web

## Introduction

The Coinme Risk Engine SDK is a library, distributed as an NPM package, that allows you to interact with the Coinme Risk Engine from your application. It provides utilities that allow you to integrate against the Coinme risk engine for the various transactional flows in your application so that Coinme may appropriately assess transactional risk when processing transactions.

> In order to utilize Coinme transactional services from within your application, you must implement and use the Coinme risk engine SDK.

**What is it?**

The Coinme risk engine aggregates data about user behavior for your application. It collects:

- Device data such as the type of device, browser, etc.
- Location data such as where the user is connecting from.
- Connection data such as if the user is using a proxy or VPN, etc.
- Behavioral data such as how a user is interacting with your application, how quickly they are entering data into fields, etc.

This data is used to determine the relative riskiness of the user / transaction.

> **Why is Risk Tagging Important?**
>
> Risk tagging allows the SDK to **track user interactions tied to specific actions within your application**. When an element is tagged, the risk engine can better assess **whether a user is behaving normally or if suspicious automation patterns are detected**.
>
> As an example, if the risk engine determines that the user is connected with an unknown browser type, via a VPN or proxy, and that interactions with elements of your app are happening much faster than would be normal for a human, then the engine may determine automation is at play and may **rank the transaction as high risk**.

## How to Use the SDK

The Coinme Risk Engine SDK is an NPM package. You may install it as follows.

> **This package is not public**
>
> You will need an auth token in order to install it. You may obtain this by working with your Coinme integration contact.

### What You'll Need to Get Started

Before integrating the SDK, you will need the following credentials from your Coinme integration contact:

| Credential | Required For | Notes |
| --- | --- | --- |
| NPM auth token | Installing the package | Required to access the private npm registry |
| `clientId` | `setupCoinmeRiskEngine` | Environment-specific — you will need one for development and one for production |
| `x-partner-id` | `getSessionTag` | Passed via `additionalHeaders` |
| `x-ramp-id` | `getSessionTag` (Ramp partners only) | Passed via `additionalHeaders` |

### Installation

#### For SDK Consumers

To install the package, configure your `.npmrc` or `.yarnrc` (or equivalent) to include your authentication token:

```
@coinme-security:registry=https://npm.coinme.com/coinme-security-wrapper/
//npm.coinme.com/coinme-security-wrapper/:_authToken=<AUTHENTICATION_TOKEN>
always-auth=true
```

> Replace `<AUTHENTICATION_TOKEN>` with your provided token.

Then install via:

NPM:

```
npm install @coinme-security/risk-sdk-js
```

Yarn:

```
yarn add @coinme-security/risk-sdk-js
```

PNPM:

```
pnpm add @coinme-security/risk-sdk-js
```

#### Quick Start

You can use the Coinme Risk Engine SDK in your project by following the steps below.

#### Setup the Coinme Risk Engine

The setup function initializes the Risk Engine and applies all necessary configurations.

```typescript
import { setupCoinmeRiskEngine } from "@coinme-security/risk-sdk-js";

setupCoinmeRiskEngine({
  mode: "test",
  clientId: "client-id",
})
  .catch((error) => {
    console.error("Error setting up Risk Engine:", error);
  })
  .finally(() => {
    console.log("Risk Engine setup complete!");
  });
```

> setupCoinmeRiskEngine is **not sufficient** in and of itself to use the risk SDK; this call is to be made when your app starts up in order to initialize the risk engine. There are other conditions which will require you to update additional parameters dynamically during the user session, such as when a user starts a high-risk action like a transaction, after a user has onboarded and now there is a customerId, etc. In these cases, use updateCoinmeRiskEngine.

> **Key Takeaway: When should I use this?**
>
> You should call setupCoinmeRiskEngine when your application instantiates.

> You will need two clientIds, one for your development builds and one for your prod builds; you may obtain these from your Coinme integration contact. It is very important that you pass the correct mode and clientId properties into the risk engine based on development or production usage, otherwise you may not stream your behavioral data to the correct environment, which can severely impact the risk engine’s ability to assess risk. This would ultimately negatively impact your transaction approvals.

#### Get Current Configuration

To check which risk parameters are applied, use:

```typescript
import { getCoinmeRiskEngineConfig } from "@coinme-security/risk-sdk-js";

const config = getCoinmeRiskEngineConfig();
console.log(config);
```

> The Risk Engine configuration is only available after setup completes.

#### Update Coinme Risk Engine Configuration

While setup handles initial configuration, you can and should manually update specific parameters when needed. An example would be after a user has onboarded or logged in, as at this point you will have a customerId available to you; this helps the risk engine associate user behavior with your user.

Another example is when you wish to update the flow identifier being sent to the risk engine. This is necessary so that when your user is entering a specific flow in your app such as **onboarding**, **linking a payment method**, or **transacting**, these special activities will be properly tagged; the risk engine examines user behavior in such flows closely. Therefore, you should tag these flows by updating the risk engine config by providing a flow identifier as seen below.

> **What is a Flow Identifier?**
>
> A flow identifier is a string that acts as a tag to uniquely identify that data the risk engine is logging belongs to a contiguous and related flow of user actions.

```typescript
import { updateCoinmeRiskEngine } from "@coinme-security/risk-sdk-js";

updateCoinmeRiskEngine({
  customerId: "customer-123",
  flow: "customer-onboarding",
})
  .catch((error) => {
    console.error("Error updating configuration:", error);
  })
  .finally(() => {
    console.log("Configuration updated");
  });
```

#### Flow Types

There are certain flows that are universal, and which are important to the operation of the coinme risk engine. You can use a pre-defined FlowType in these cases to ensure you are properly tagging these flows. We export a FlowType enumeration that exposes these common flows which our risk engine can understand and use when making risk decisions. This enum is structured as follows:

```typescript
export enum FlowType {
  Onboarding = 'customer-onboarding',
  CardTransaction = 'card-transaction',
  CardLinking = 'payment-method-linking',
}
```

For maximum value, you should use the appropriate FlowType as the flow identifier when you are onboarding users, adding a payment method, or undertaking a transaction.

> **Why Use Flow Identifiers?**
>
> Flow identifiers help **group multiple actions into a single session** so that risk is assessed based on **contextual user behavior**. Instead of analyzing each interaction separately, the risk engine can **detect patterns within a specific user journey**.
>
> For example:
>
> - If a user **enters payment details too quickly** after onboarding, this might indicate a **scripted attack** rather than a real person.
> - If a user **switches IP addresses** midway through a transaction, it could indicate a **fraud attempt**.
> - If a user **is interacting normally but suddenly switches to rapid inputs**, the system can **adapt its risk evaluation in real time**.
>
> By tagging actions with the correct FlowType, your application **provides the risk engine with the necessary context** to assess transactional legitimacy.

> The Coinme risk engine requires the specific flow identifiers exposed by the risk SDK for any of these pre-defined flow types; **if you do not use the supported identifier, your users and transactions may not be appropriately scored and you will be at risk of high denial rates for your transactions.**

**Usage Examples**

Each example demonstrates when and how to use updateCoinmeRiskEngine with a **specific flow type**.

**Example 1: Onboarding Flow**

When a **new user signs up**, you must tag their session as **onboarding** so the risk engine can monitor suspicious activities.

```typescript
import { updateCoinmeRiskEngine, FlowType } from "@coinme-security/risk-sdk-js";

updateCoinmeRiskEngine({
  customerId: "new-user-456",
  flow: FlowType.Onboarding,
})
  .catch((error) => {
    console.error("Error updating configuration:", error);
  })
  .finally(() => {
    console.log("User onboarding flow tracked.");
  });
```

> **When to use?**
>
> Call this **when the user starts** the signup process.

**Example 2: After Onboarding or Sign-in**

After a **new user finishes signing up**, or after a **user has signed in**, you must update the risk engine with their userID so that data can now be associated with the user rather than a session. This allows the risk engine to aggregate and interpret data over time.

```typescript
import { updateCoinmeRiskEngine, FlowType } from "@coinme-security/risk-sdk-js";

updateCoinmeRiskEngine({
  customerId: "user-456",
})
  .catch((error) => {
    console.error("Error updating configuration:", error);
  })
  .finally(() => {
    console.log("User ID now tracked.");
  });
```

> **When to use?**
>
> Call this **right after the user completes** the signup **or login** process and the user’s permanent ID is known.

**Example 3: Linking a New Card**

If a user is adding a **new payment method**, this is a **high-risk action** that must be monitored.

```typescript
import { updateCoinmeRiskEngine, FlowType } from "@coinme-security/risk-sdk-js";

updateCoinmeRiskEngine({
  customerId: "user-789",
  flow: FlowType.CardLinking,
})
  .catch((error) => {
    console.error("Error updating configuration:", error);
  })
  .finally(() => {
    console.log("Card linking flow tracked.");
  });
```

> **When to use?**
>
> Call this **when the user enters a process to add a payment method**.

**Example 4: Processing a Card Transaction**

When a user makes a **purchase or transaction**, you should explicitly tag it.

```typescript
import { updateCoinmeRiskEngine, FlowType } from "@coinme-security/risk-sdk-js";

updateCoinmeRiskEngine({
  customerId: "user-123",
  flow: FlowType.CardTransaction,
})
  .catch((error) => {
    console.error("Error updating configuration:", error);
  })
  .finally(() => {
    console.log("Card transaction flow tracked.");
  });
```

> **When to use?**
>
> Call this **when the user enters a transactional flow** such as when they start a buy or sell transaction.

> **Proper Use**
>
> The updateCoinmeRiskEngine function is designed to modify the risk engine's configuration after the initial setup. However, since both setupCoinmeRiskEngine and updateCoinmeRiskEngine are **asynchronous**, calling them sequentially without ensuring the setup is complete may cause the update function to override the initial configuration.

#### How to Update Correctly

- Ensure that setupCoinmeRiskEngine is completed before calling updateCoinmeRiskEngine.
- If calling both on the first render (e.g., in a React setup), chain them properly using await or a state check.
- Calling updateCoinmeRiskEngine before setupCoinmeRiskEngine finishes may lead to an incomplete or overridden configuration.

**Example: Correct Usage - Await the Setup Before Updating**

```typescript
async function initializeRiskEngine() {
  await setupCoinmeRiskEngine({
    mode: "test",
    clientId: "client-id",
  });

  console.log("Setup complete:", getCoinmeRiskEngineConfig());

  await updateCoinmeRiskEngine({
    customerId: "a@mail.com",
    flow: "flow-id",
  });

  console.log("Update complete:", getCoinmeRiskEngineConfig());
}

initializeRiskEngine();
```

> **Why is this correct?**
>
> - Ensures setup completes before update can be called

**Example: Incorrect Usage - Running Setup and Update in Parallel**

```typescript
setupCoinmeRiskEngine({
  mode: "test",
  clientId: "client-id",
});

updateCoinmeRiskEngine({
  customerId: "a@mail.com",
  flow: "flow-id",
});
```

> **Why is this wrong?**
>
> - updateCoinmeRiskEngine may execute before setupCoinmeRiskEngine completes.
> - The update call might override important setup details.
> - Leads to unpredictable behavior in the risk engine configuration.

> **Key Takeaway: When should I use this?**
>
> You should call updateCoinmeRiskEngine:
>
> - After a user has onboarded or logged in, and you have a customerId
> - By updating the risk engine with the customerId, you ensure that the risk engine can understand the user’s behavior over time, which leads to better risk modeling.
> - When a user begins a flow that needs to be explicitly identified, such as onboarding, linking a payment method, or transacting.
> - **These are key actions that should be tagged** with the correct flow identifier.

#### Tagging Elements

You can add Risk attributes to elements, components, or strings with the addCoinmeRiskTag function. The risk engine SDK automatically detects these tags and will flow behavioral metrics into the risk engine from any tagged entities automatically.

**Examples:**

- Returning a pre-tagged HTML element:

```typescript
import { addCoinmeRiskTag } from "@coinme-security/risk-sdk-js";

// Using a raw HTML string
const elementAsString = addCoinmeRiskTag({
  element: '<div>Hello, World!</div>',
  riskIdentifier: 'my-element',
});

console.log(elementAsString); // Outputs a div with the risk data attribute 'my-element' added.
```

- Tagging an existing DOM element:

```typescript
import { addCoinmeRiskTag } from "@coinme-security/risk-sdk-js";

// Using an existing DOM element
const divElement = document.createElement('div');

divElement.textContent = 'Hello, World!';

const taggedElement = addCoinmeRiskTag({ element: divElement, riskIdentifier: 'my-element' });

console.log(taggedElement.outerHTML); // Outputs a div with the risk data attribute 'my-element' added.
```

- Tagging a React-Like object:

```typescript
import { addCoinmeRiskTag } from "@coinme-security/risk-sdk-js";

// Tagging a React/Vue-style object
const reactLikeObject = {
  type: 'div',
  props: { children: 'Hello, World!' },
};

const taggedObject = addCoinmeRiskTag({ element: reactLikeObject, riskIdentifier: 'my-element' });

console.log(taggedObject); 
// Outputs a react / vue style object with the risk data attribute 'my-element' added.
```

## Core concepts

#### Client ID Requirement

> You must provide your clientId to use the SDK. If you don't have your clientId, ask your Coinme integration contact.

The clientId uniquely identifies your partner integration within the Risk Engine.

- It is provided by Coinme during onboarding.
- Issued alongside your other Coinme credentials. It is not a secret and is meant to run in the browser; never put your partner access token or client secret in the browser alongside it. The Risk SDK itself takes no auth token.
- Without it, the SDK will throw an error and refuse to initialize.

#### Understanding sessionKey

The sessionKey is a unique identifier for tracking a specific user session.

> **In-Memory Only**
>
> The SDK does **not** persist session keys to localStorage, sessionStorage, or cookies. The session key is only held in memory. On page refresh, the key is lost. Don't persist a session tag to rehydrate it later: call `getSessionTag()` again right before the call that needs it.

| Behavior | Outcome |
| --- | --- |
| Provide sessionKey in setup | Used & cached in memory |
| Provide sessionKey in update | Overrides & caches in memory |
| No sessionKey provided, stored key exists | Stored key reused automatically |
| No sessionKey provided, no stored key | A stand-in key is cached; Coinme refuses it as a `webSessionId`, so read the session ID with `getWebSessionId()` (from 1.2.0) rather than `getCoinmeRiskEngineConfig().sessionKey`, which is deprecated for this |
| Call getSessionTag() | webSessionID from server becomes the cached sessionKey |
| Call clearSessionKey() | Clears the in-memory key; from 1.2.0 also the user identity (`customerId`, `flow`, `parentSessionKey`), keeping `partnerId` and the `enable*` flags |

> When you call `getSessionTag()`, the returned `webSessionID` automatically becomes the active session key. All subsequent calls to `updateCoinmeRiskEngine()` will use this session key unless you explicitly provide a different one.

> **Why this matters**
>
> It is essential that the Risk Engine use the session tag returned by this endpoint once it is called. If you change the session key after this call is made, risk metrics will not be properly associated with your user. When you call `getSessionTag()`, you are signifying that you want Coinme to track your user's session — your own session ID is no longer relevant to this tracking.

> **A session tag lives 30 minutes**
>
> Coinme keeps a session tag for 30 minutes from when it issued it, and using it doesn't extend that. You can't tell from the browser how long a tag has left, so don't store a `webSessionID` and reuse it on later page loads.

> **Call `getSessionTag()` right before each add-payment-method call and each order.**
>
> Send the `webSessionID` it returns as `webSessionId` on that call. Calling `getSessionTag()` again while a tag is still live returns the same tag, so it doesn't start a new risk assessment session; once the tag is 30 minutes old it returns a new one.

#### Clearing the sessionKey

```typescript
import { clearSessionKey } from "@coinme-security/risk-sdk-js";

clearSessionKey();
```

> This clears the **in-memory** session key. From 1.2.0 it clears the whole in-memory user identity: the session key plus the `customerId`, `flow` and `parentSessionKey` you passed to setup or update. App-level settings (`partnerId` and the `enable*` flags) are kept. The next setup or update starts from a clean identity, so nothing from the previous user is sent with the next user's session. It doesn't reset Sardine's own state; Sardine takes the next user's values through its normal update. Before 1.2.0 it clears only the session key. Use this in SPAs when:
>
> - Logging out users (without a page refresh)
> - Switching accounts
> - Resetting state for tests
>
> For non-SPA apps or full page reloads, the in-memory key is cleared automatically. If you stored a session key yourself (for example in `localStorage`), remove it as well; the SDK can't clear storage it doesn't own.

#### Typical Session Flow Example

```typescript
// Setup with auto-generated sessionKey
await setupCoinmeRiskEngine({
  mode: 'prod',
  clientId: 'client-id',
});

// Later — Update without providing sessionKey (uses stored one)
await updateCoinmeRiskEngine({
  flow: 'customer-onboarding',
});

// On session end (e.g., logout in a SPA)
clearSessionKey();

// Start new user/session
await setupCoinmeRiskEngine({
  mode: 'prod',
  clientId: 'client-id',
});
```

#### Session Flow with getSessionTag (Recommended for Transactions)

```typescript
import {
  setupCoinmeRiskEngine,
  getSessionTag,
  clearSessionKey,
} from "@coinme-security/risk-sdk-js";

// Once, when your app starts
await setupCoinmeRiskEngine({
  mode: 'prod',
  clientId: 'client-id',
});

// Right before each add-payment-method call and each order:
// a session tag lives 30 minutes, so fetch it every time
async function freshWebSessionId(customerId) {
  const sessionData = await getSessionTag({
    apiBaseUrl: 'https://api.example.com',
    // From 1.2.0 you may leave fingerprint out; earlier releases require it.
    customerId,
    additionalHeaders: {
      'x-partner-id': 'your-partner-id',
      'x-ramp-id': 'your-ramp-id', // only needed for ramp partners
    },
  });
  return sessionData.webSessionID;
}

const webSessionId = await freshWebSessionId('customer-123');
// Send webSessionId with the payment-method or order call.

// On logout or account switch (SPA only; a page refresh clears it)
clearSessionKey();
```

## API Reference

The Coinme Risk Engine SDK provides the following functions for interacting with the Risk Engine.

You can find detailed information about each function below or in the **API Reference** (internal to Coinme, not public)**.**

### setupCoinmeRiskEngine

Sets up the Coinme Risk Engine with the provided options.

**Parameters:**

| Param | Type | Required | Description |
| --- | --- | --- | --- |
| mode | `'test' \| 'prod'` | ✅ | Operating environment |
| clientId | string | ✅ | Partner-specific risk engine client ID |
| partnerId | string | optional | Partner identifier |
| customerId | string | optional | Customer identifier |
| sessionKey | string | optional | Custom session tracking key |
| flow | `string \| FlowType` | optional | Flow context |

**Example:**

```typescript
import { setupCoinmeRiskEngine } from "@coinme-security/risk-sdk-js";

setupCoinmeRiskEngine({ mode: "test", clientId: "client-id" })
  .catch((error) => {
    console.error("Error setting up Risk Engine:", error);
  })
  .finally(() => {
    console.log("Risk Engine setup complete!");
  });
```

### getCoinmeRiskEngineConfig

Retrieves the latest risk assessment settings applied to the current session.

**Returns:**

- `Partial<RiskEngineConfig>`: An object containing the current Risk Engine configuration. All fields are optional and include: `partnerId`, `customerId`, `sessionKey`, `flow`, `parentSessionKey`, `enableBiometrics`, `enableGeoLocation`, `enablePortScanning`.
- If no configuration has been set, it returns `{}`.

**Example:**

```typescript
import { getCoinmeRiskEngineConfig } from "@coinme-security/risk-sdk-js";

const config = getCoinmeRiskEngineConfig();
console.log(config); // Outputs: { partnerId: "...", sessionKey: "...", ... }
```

### updateCoinmeRiskEngine

Updates the Coinme risk assessment settings for the current session. This ensures that risk evaluations, such as device fingerprinting and geolocation tracking, are correctly applied.

**Parameters:**

| Param | Type | Required | Description |
| --- | --- | --- | --- |
| partnerId | string | optional | Partner identifier |
| customerId | string | optional | Customer identifier |
| sessionKey | string | optional | Override session key |
| flow | `string \| FlowType` | optional | Flow context |
| parentSessionKey | string | optional | Parent session key |
| enableBiometrics | boolean | optional | Enable biometric signals |
| enableGeoLocation | boolean | optional | Enable geo-location |
| enablePortScanning | boolean | optional | Enable port scanning |

**Example:**

```typescript
import { updateCoinmeRiskEngine } from "@coinme-security/risk-sdk-js";

updateCoinmeRiskEngine({
  customerId: "customer-123",
  flow: "onboarding",
})
  .catch((error) => {
    console.error("Error updating configuration:", error);
  })
  .finally(() => {
    console.log("Configuration updated");
  });
```

### addCoinmeRiskTag

Enhances an element, component, or string representation of HTML by tagging the element with a risk tag. The risk engine SDK automatically detects these tags and will flow metrics into the risk engine from any tagged entities automatically.

**Parameters:**

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| element | `HTMLElement \| string \| object` | ✅ | Target element |
| riskIdentifier | string | ✅ | Unique risk tag |

**Returns:**

- The same element with the risk tag applied.

**Example:**

```typescript
import { addCoinmeRiskTag } from "@coinme-security/risk-sdk-js";

const element = addCoinmeRiskTag({
  element: '<div>Hello, World!</div>',
  riskIdentifier: 'my-element',
});

console.log(element); // Outputs a div tagged with the specified risk tag
```

### withCoinmeRiskTag

Creates a higher-order component that adds a risk tag to the wrapped component's output. The tagging behavior depends on what the component returns:

- **String**: the string output is wrapped in a new `<div data-sardine-id="...">` element.
- **HTMLElement**: the `data-sardine-id` attribute is added directly to the element.
- **Object with `props`** (React/Vue-style): `data-sardine-id` is added to the `props` object.

**Parameters:**

| Param | Type | Required | Description |
| --- | --- | --- | --- |
| Component | function | ✅ | The component function to wrap. |
| id | string | ✅ | Unique risk tag to apply. |

**Returns:**

- A wrapped component with the risk tag attribute added to props or its equivalent.

**Examples:**

Wrapping a simple component:

```typescript
import { withCoinmeRiskTag } from "@coinme-security/risk-sdk-js";

const MyComponent = (props) => `<div>${props.text}</div>`;

const TaggedComponent = withCoinmeRiskTag(MyComponent, 'my-element');

console.log(TaggedComponent({ text: 'Hello, world!' }));
// The string output is wrapped in a new tagged div:
// <div data-sardine-id="my-element"><div>Hello, world!</div></div>
```

Wrapping a object-based component:

```typescript
import { withCoinmeRiskTag } from "@coinme-security/risk-sdk-js";

const MyObjectComponent = (props) => ({
  type: 'div',
  props: { children: props.text },
});

const WrappedObject = withCoinmeRiskTag(MyObjectComponent, 'object-component');

console.log(WrappedObject({ text: 'Hello, world!' }));
// Outputs an object tagged with the specified risk tag
```

### getSessionTag

Retrieves the Sardine session tag data from the public `/pub/get-session-tag` endpoint. This call obtains the session information needed for transaction risk assessment. Upon successful retrieval, the `webSessionID` is automatically used to update the Sardine configuration and is stored as the active session key for all subsequent SDK calls.

**Parameters:**

| Param | Type | Required | Description |
| --- | --- | --- | --- |
| apiBaseUrl | string | ✅ | The base URL of the API endpoint |
| fingerprint | string | optional | The device fingerprint, sent as `x-device-fingerprint`. From 1.2.0, when omitted the SDK sends the one the other Coinme SDKs on this device share, or creates and shares one (see [Device fingerprint](https://platformdocs.coinme.com/docs/using-the-coinme-risk-sdk-for-web.md#device-fingerprint)); earlier releases require it |
| customerId | string | ✅ | The customer ID, sent as the `accountId` query parameter |
| additionalHeaders | `Record<string, string>` | ✅ | Additional headers. Must include `x-partner-id` with the value provided by your Coinme integration contact. Example: `additionalHeaders: { 'X-Partner-ID': 'partner-123' }` |
| timeout | number | optional | Request timeout in milliseconds (default: 10000) |

**Returns:**

- `Promise<SessionTagData>`: A promise that resolves with the session tag data containing `webSessionID` and `orgID`. The Sardine configuration is automatically updated with the `webSessionID` as the session key.

**Example:**

```typescript
import { getSessionTag } from "@coinme-security/risk-sdk-js";

const sessionData = await getSessionTag({
  apiBaseUrl: 'https://api.example.com',
  // From 1.2.0 you may leave fingerprint out; earlier releases require it.
  customerId: 'customer-123',
  additionalHeaders: {
    'x-partner-id': 'your-partner-id',
  },
});

// The webSessionID is automatically set in Sardine configuration
const webSessionId = sessionData.webSessionID;
const orgId = sessionData.orgID;
```

> **When to use?**
>
> Call this **right before each add-payment-method call and each order** to retrieve the session tag and automatically configure Sardine with the proper session key, then send the returned `webSessionID` as `webSessionId` on that call. A session tag lives 30 minutes from when it was issued, and using it doesn't extend that.

> After calling `getSessionTag()`, the `webSessionID` becomes the stored session key. You do not need to pass it to subsequent `updateCoinmeRiskEngine()` calls — the SDK will automatically use it. If you need to override this behavior, explicitly pass a different `sessionKey` to `updateCoinmeRiskEngine()`.

> **No token needed.**
>
> Don't pass an `authToken` or an `Authorization` header to `getSessionTag()`: this call authenticates with your `customerId` and `x-partner-id`. Never put your partner access token or client secret in the browser.

## Device fingerprint

Coinme ties risk checks to a device ID sent as the `X-Device-Fingerprint` header. On the web and React Native you don't have to supply one.

- If you pass a fingerprint, this SDK uses it and shares it with the other Coinme SDKs in your app. Pass the same value to every Coinme SDK, or pass it to the Risk SDK first, which shares it with the others.
- If you don't, the SDK uses the one another Coinme SDK already set in your app, or creates one.
- Every Coinme SDK in your app must send the same value. If they differ, adding a payment method and placing orders fail with `WEB_SESSION_ID_MISMATCH`.
- Leaving the header out needs these releases or later: Risk SDK for Web 1.2.0, Risk SDK for React Native 1.1.0, Vault SDK for JavaScript 1.3.0, Vault SDK for React Native 1.3.0, Onboarding SDK for JavaScript & React 1.7.0, Onboarding SDK for React Native 1.2.0. With an older release, pass every Coinme SDK the same `X-Device-Fingerprint` you give the Risk SDK.
- Calls your server makes to Coinme for this user (for example orders) must send the same value. Read it in your web page or app with the SDK's `getDeviceFingerprint()` (on React Native it returns a Promise) and send it to your server with the request. Never call `getDeviceFingerprint()` on your server.
- On the web the value belongs to the browser and the site's origin, not the device: a page on another origin gets a different one.
- A `:` in the value is replaced with `-`.
- A risk session tag lives 30 minutes from when it was first issued. Fetch it right before adding a payment method or placing an order, and send the tag it returns as `webSessionId`.

## Reading the session tag

From 1.2.0, `getWebSessionId()` returns the session ID to send as `webSessionId`: the `webSessionID` from your last `getSessionTag()` call, or a session key you passed yourself. It returns `undefined` when there is none. Use it instead of `getCoinmeRiskEngineConfig().sessionKey`, which is deprecated for this: before a session tag exists, `sessionKey` holds a stand-in the SDK made up, which Coinme refuses.
