---
name: coinme-risk-web
description: "Add the Coinme Risk SDK to a web app: install from the private registry, set up the Risk Engine with the client ID, tag the inputs it should observe, and get a session tag right before each add-payment-method call and each order. Use when asked to add risk, fraud or device signals, a session tag or the Coinme Risk Engine to a website or web app."
metadata:
  surface: "caas"
  package: "@coinme-security/risk-sdk-js"
  version: "1.2.0"
---

# Coinme Risk SDK on the web

## When to use this skill

The human wants Coinme's Risk Engine in a web app, which Coinme requires before any transactional service is used from the app. The Widget SDK carries its own risk signals; this skill is for a partner's own app and its own transaction calls.

## Which integration this is

This skill is for the **Coinme-as-a-Service (CaaS) integration**: the partner keeps its own users and its own screens, and Coinme performs regulated services for them (onboarding and KYC, card vaulting, risk signals, transactions). The users are the partner's customers, not Coinme users. There is no Coinme Widget here, so no `rampId`, `partnerKey`, widget URL or embed allowlist. If the human wants to embed the Coinme Widget instead, this is the wrong skill: read [Two ways to build on Coinme](https://platformdocs.coinme.com/agents/surfaces.md) and pick a Widget skill.

## What you will produce

A web app that initialises the Risk Engine at launch with the client ID, tracks the inputs the guide names, gets a session tag right before each add-payment-method call and each order, and, where the SDK has a submit call, submits its data immediately before each transaction-initiating call to the backend, with the credentials kept out of source.

## Before you start: ask the human for these

The documentation does not contain them and you cannot derive them. Stop and ask, then continue. Never write a real value into a tracked file; keep each where the row says.

| Value | What it is | Where it goes |
| --- | --- | --- |
| `registry token` | Read-only token for the private registry that serves the Coinme SDKs. The install steps below read it from an environment variable they name; set that variable. | An environment variable or a gitignored registry config read at install time; CI reads it from a secret. Never in a committed file. |
| `clientId` | Identifies the integration to the Risk Engine; the SDK refuses to initialise without it. One per environment. Not a secret: it runs in the client, but the partner access token and client secret never go there with it. | Runtime configuration, not source; keep the development and production values apart. |
| `Partner ID (and Ramp ID for Ramp partners)` | Identifiers the session-tag call carries so the Risk Engine attributes the session: on the web the x-partner-id (and x-ramp-id) headers in getSessionTag additionalHeaders; on iOS, Android and React Native the partnerId (and rampId) options of getPartnerSessionTag. | Runtime configuration passed to the SDK; never hard-coded. |

## Rules for this skill

- Follow the steps in order and keep the code as written; change only identifiers the human gives you and the places marked as yours.
- Do not invent configuration fields, event names or API methods. What exists is what this skill shows plus what the installed package declares in its type definitions; check those before adding anything.
- Samples show the environment (such as `'sandbox'`, `'test'` or a staging base URL) as a literal so each stays self-contained. In the project, read it from the runtime configuration the human's build uses (for Vite, `VITE_*` variables in a gitignored `.env.local` with a committed `.env.example`), with a value per environment.
- This integration has no `rampId`, `partnerKey`, widget URL or embed allowlist. Do not ask for them or add them; they belong to the Widget skills. The one exception is the Risk SDK's optional `x-ramp-id` header, which only a Ramp partner sends.
- When a step needs a value you do not have, ask; do not substitute a placeholder that could ship.
- Read the linked pages when a step is unclear; they are the source this skill was generated from.

## Read first

Get the session tag right before each add-payment-method call and each order (getSessionTag on the web, getPartnerSessionTag on iOS, Android and React Native) and send it as webSessionId: a tag lives 30 minutes from when it was issued, using it doesn't extend that, and calling again while it is live returns the same tag. Never persist a tag across reloads or relaunches to reuse it. The device fingerprint is optional from 1.2.0: the Coinme SDKs share one. The app reads it with getDeviceFingerprint() and sends it to its server with each request; never call getDeviceFingerprint() on the server. Where the SDK has a submit call (submitCoinmeRiskData on React Native, CoinmeRiskEngine.submit on iOS and Android), make it immediately before every transaction-initiating server call. The guide's session-flow section is the contract.

Store listings and privacy disclosures in the guide are requirements, not suggestions; include them in what you hand back.

The Risk SDK takes no auth token from the app. In a partner app the session tag comes from the partner session-tag call (getPartnerSessionTag on iOS, Android and React Native; getSessionTag with the x-partner-id header on the web), which needs no token. Never pass the partner access token or a Transient Auth Token to the Risk SDK.

## Procedure

Follow the guide below in order. It is the integration guide for this platform as published, so the section names are the guide's own.

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

## Verify

Build and run the app. Confirm the Risk Engine initialises without an error, that a session tag is obtained with the headers the guide names right before each add-payment-method call and each order, that the submit call (where the SDK has one) completes right before a transaction call, and that no client ID or token is in a committed file. Hand back the privacy and store-listing items the guide requires.

### Reading the result

**Done when:** Setup completes, a session tag comes back for the customer, and the same device fingerprint is sent on later Coinme calls from this device.

**Stop and ask the human when** the client ID is refused, or the partner is unknown (`143-404-317-704`).

Judge every Coinme call by its body, not its HTTP status: a refused request usually comes back as HTTP 200 with the error in the body. [Reading results](https://platformdocs.coinme.com/agents/results.md) has the rule, what each common error code asks you to do, and what to send your Coinme integration contact when something fails.

## Reference
- [Coinme Risk SDK](https://platformdocs.coinme.com/docs/coinme-risk-sdk.md)
- [Coinme Risk SDK for Web](https://platformdocs.coinme.com/docs/using-the-coinme-risk-sdk-for-web.md)
- [Build: the Library of SDKs and documents](https://platformdocs.coinme.com/pages/build/library.md)
