Introduction

This guide provides step-by-step instructions for integrating with the Embermind Antifraud System. It covers the complete onboarding process — from obtaining account credentials to configuring fraud detection and migrating historical transaction data. Who is this guide for? This guide is intended for developers and technical integrators who need to:

• Connect their payment system to Embermind Antifraud
• Migrate existing transaction history
• Configure fraud scoring and alert rules
• Integrate the fingerprint collection SDK

By following this guide, you will:

1. Set up your company account with proper access controls
2. Configure commission calculation for transaction gates
3. Define customer grouping rules for fraud correlation
4. Enable and customize scoring generators
5. Migrate your historical transaction data
6. Integrate real-time fingerprint collection on your checkout pages

Estimated time: 2-4 hours for initial setup, plus time for data migration depending on volume.

Step 1. Obtaining an Account to Work with the System

To start working with the antifraud system, you need to contact your account manager and obtain login credentials.

Example of login credentials:

{
    "companyId": "7992110d-617e-40c5-82323b9a-94e8248ad2f1",
    "companyTitle": "Company_777",
    "permGroupTitle": "root",
    "userId": "f0fab777-fd19-43303-2229-8f4431239a1acf",
    "userEmail": "[email protected]",
    "userLogin": "test",
    "userPass": "secret_pass",
    "apiKeyId": "787987b3-7884c-4888-95183-a9889777e",
    "apiKeyTitle": "root",
    "apiKeyValue": "xxx-yyy-zzz"
}

The first user will have administrator rights (unlimited permissions for working in the admin panel and calling API methods).

An administrator can create other users and assign them permissions.

The role-based access control system is implemented through:

• user
• access group
• permissions assigned to an access group

One user can belong to multiple access groups. A user’s effective permissions are the sum of permissions of all assigned access groups.

Authentication

The Embermind API supports two authentication methods. You can use either one depending on your use case.

Method 1: API Key (Recommended for integrations)

Use API Key for server-to-server communication. The key is permanent and doesn't expire. Header:

x-api-key: YOUR_API_KEY_VALUE

Example:

curl -X GET 'https://api.embermind.ch/api/v1/client/profile/me' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: xxx-yyy-zzz'

Your API Key (apiKeyValue) is provided by your account manager along with other credentials.

Method 2: Access Token

Use Access Token for session-based authentication. Obtain a token by calling the login endpoint.

Step 1. Get token:

curl -X POST 'https://api.embermind.ch/api/v1/client/auth/login' \
  -H 'Content-Type: application/json' \
  -d '{
    "loginOrEmail": "[email protected]",
    "password": "secret_pass"
  }'

Response:

{
  "xAccessToken": "abc123xyz..."
}

Step 2. Use token in requests:

x-access-token: abc123xyz...

Example:

curl -X GET 'https://api.embermind.ch/api/v1/client/profile/me' \
  -H 'Content-Type: application/json' \
  -H 'x-access-token: abc123xyz...'

Authentication Errors

Step 2. API Whitelisting (Optional)

To work with the antifraud API, provide your manager with a list of IP addresses from which API calls will be made.

If you plan to receive data from the antifraud system via API, request a list of our IP addresses and add them to your own whitelist.

Step 3. Gate Commission Configuration (Optional)

Commission - a fee for attempting to process a transaction through a gate.

The anti-fraud system has a commission calculation mechanism.

Commission calculation priority: gate → bank. You can also submit calculated commission values ​​when submitting a transaction; in this case, commission calculation will not occur, but the commissions received via the API will be saved.

Commissions are calculated in the transaction currency and in dollars.

Before data migration, you can configure commission calculation for each gate and bank.

During data migration, commissions will be calculated and saved in the system.

Fee calculation algorithm.

Settings are configured separately for each gate for the accept and decline status.

The approval and rejection fees consist of three components:

1. Fixed. Can be set as an absolute value or as a percentage of the transaction amount.
2. Percentage. A percentage of the transaction amount.
3. Minimum. An absolute value.

To calculate the fee, we calculate the fixed value + a percentage of the amount.

Then we compare the calculated value with the minimum fee. If the minimum is greater than the calculated value, we use the minimum. If the calculated value is greater than the minimum, we use the calculated value.

Saving commissions in the anti-fraud system.

To save commissions, you must first create a tariff by calling the Create CommissionTariff method in Company.

curl -X POST 'https://api.embermind.ch/api/v1/client/commission-tariffs/create' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: xxx-yyy-zzz' \
  -d '{
    "title": "CommissionTariffExample",
    "priorityOne": "COUNTRY",
    "priorityTwo": "CARD_BRAND",
    "priorityThree": "MCC_ID"
  }'

Response (200 OK):

{
  "id": "69e45d20-98a9-4c75-ab60-1188d64d510a",
  "title": "CommissionTariffExample",
  "priorityOne": "COUNTRY",
  "priorityTwo": "CARD_BRAND",
  "priorityThree": "MCC_ID"
}

Next, you need to configure the commission calculation rule for the created tariff by calling the method the Create CommissionRule method in Company.

Parameters:

• commissionTariffId — Tariff ID received earlier
• direction — ACCEPT or DECLINE. If ACCEPT, the commission will be calculated for gates with the ACCEPT status. If DECLINE, for gates with the DECLINE status.

curl -X POST 'https://api.embermind.ch/api/v1/client/commission-rules/create' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: xxx-yyy-zzz' \
  -d '{
    "commissionTariffId": "69e45d20-98a9-4c75-ab60-1188d64d510a",
    "direction": "ACCEPT",
    "percent": 10,
    "fixPercent": 10,
    "fixAmount": 15,
    "minAmount": 5,
    "cardBrand": "VISA",
    "country": "RU",
    "mccId": "mccExample"
  }'

Response (200 OK):

{
  "commissionRuleId": "550e8400-e29b-41d4-a716-446655440000"
}

Assigning Commissions to Gates

Commissions are assigned to gates at the moment the gate is created.

Before creating a gate, you must first create a bank, as a gate cannot exist without an associated bank.

Creating a Bank

Call the following API method: POST /api/v1/client/banks-crud/create

curl -X POST 'https://api.embermind.ch/api/v1/client/banks-crud/create' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: xxx-yyy-zzz' \
  -d '{
    "title": "Bank Title",
    "externalId": "BANK_EXTERNAL_ID",
    "commissionTariffId": "69e45d20-98a9-4c75-ab60-1188d64d510a"
  }'

Response (200 OK):

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "title": "Bank Title",
    "externalId": "BANK_EXTERNAL_ID",
    "commissionTariffId": "69e45d20-98a9-4c75-ab60-1188d64d510a"
  }
}

Creating a Gate

After the bank is created, create a gate using: POST /api/v1/client/gates-crud/create

curl -X POST 'https://api.embermind.ch/api/v1/client/gates-crud/create' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: xxx-yyy-zzz' \
  -d '{
    "title": "Gate Title",
    "externalId": "GATE_EXTERNAL_ID",
    "currency": "EUR",
    "bankId": "550e8400-e29b-41d4-a716-446655440000",
    "commissionTariffId": "69e45d20-98a9-4c75-ab60-1188d64d510a"
  }'

Response (200 OK):

{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "title": "Gate Title",
    "externalId": "GATE_EXTERNAL_ID",
    "currency": "EUR",
    "bankId": "550e8400-e29b-41d4-a716-446655440000",
    "commissionTariffId": "69e45d20-98a9-4c75-ab60-1188d64d510a"
  }
}

Step 4. Customer Grouping Configuration

A Customer is a set of transaction attributes that represent a single user.

Customer grouping can be based on:

• email
• phone
• card token
• fingerprint
• IP address

Example: If grouping by email is enabled and two transactions have the same email, they will be merged into one customer even if other fields differ.

Customer grouping settings can be configured:

• in the Admin Panel: Settings → Customer Grouping
• or via API: Update CompanySettings by companyId

Parameters:

curl -X POST 'https://api.embermind.ch/api/v1/client/company-settings/update' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: xxx-yyy-zzz' \
  -d '{
    "isCompanyCustomerGroupByExternalId": true,
    "companyCustomerGroupByExternalIdRegExp": null,
    "isCompanyCustomerGroupByEmail": true,
    "companyCustomerGroupByEmailRegExp": null,
    "isCompanyCustomerGroupByPhone": true,
    "companyCustomerGroupByPhoneRegExp": null,
    "isCompanyCustomerGroupByCardToken": true,
    "companyCustomerGroupByCardTokenRegExp": null,
    "isCompanyCustomerGroupByFingerpint": true,
    "companyCustomerGroupByFingerpintRegExp": null,
    "isCompanyCustomerGroupByIpAddress": false,
    "companyCustomerGroupByIpAddressRegExp": null
  }'

Response (200 OK): Returns updated company settings.

If all grouping attributes are disabled, customers will not be merged. Each transaction will create a new customer.

Each grouping attribute can be validated using a regular expression. If a value does not match the regex, grouping will not occur.

Step 5. Scoring Configuration

Default scoring settings are created automatically when a company is created.

You can modify scoring settings:

• in the Admin Panel: Settings → Score Generator
• or via API.

Detailed instructions on setting up scoring will be provided separately.

During data migration, it is recommended to disable scoring generators to speed up the process.

To completely disable scoring, please contact your manager.

Step 6. Alert Configuration (Optional)

Alerts are notifications generated in the anti-fraud system when anomalies are detected.

Alerts can be configured in your personal account under Settings - Alert Validators, or via the API.

Detailed instructions on setting up notifications will be provided separately.

Alerts are not required during data migration, so it is recommended to disable them.

To completely disable notifications, please contact the manager.

Step 7. Data Migration

The Transaction processing (Risk-score) Single Item method is used to transfer data: POST /api/v1/client/transaction-process

This method is used to calculate the transaction score, but it also stores transaction data in the system.

A separate method call must be made for each transaction.

Example request:

curl -X POST 'https://api.embermind.ch/api/v1/client/transaction-process' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: xxx-yyy-zzz' \
  -d '{
    "externalId": "txn_12345",
    "status": "ACCEPT",
    "type": "PAYMENT",
    "dateStart": "2024-01-15T10:30:00.000Z",
    "dateEnd": "2024-01-15T10:31:00.000Z",
    "currency": "EUR",
    "amount": "100.50",
    "merchantExternalId": "merchant_001",
    "merchantTitle": "My Merchant",
    "merchantAccountExternalId": "account_001",
    "merchantAccountTitle": "Main Account",
    "email": "[email protected]",
    "phone": "+79998887766",
    "cardToken": "card_token_hash",
    "cardBin": "411111",
    "cardCountry": "DE",
    "cardLastFourDigit": "1234",
    "cardExpireDate": "08/28",
    "cardHolder": "John Doe",
    "ipAddress": "1.2.3.4",
    "ipAddressCountry": "DE",
    "fingerprint": "fp_abc123",
    "cascade": {
      "externalId": "cascade_001",
      "title": "Main Cascade",
      "gateList": [
        {
          "externalId": "gate_001",
          "title": "Gate 1",
          "bankExternalId": "bank_001",
          "bankTitle": "Bank 1",
          "currency": "EUR",
          "serialNumber": 1,
          "status": "ACCEPT"
        }
      ]
    }
  }'

Response (200 OK):

{
  "transactionId": "69e45d20-98a9-4c75-ab60-1188d64d510a",
  "transactionExternalId": "txn_12345",
  "isNeedCheckReturnUrl": false,
  "scoreResultList": [
    {
      "gateExternalId": "gate_001",
      "scoreValue": 15,
      "badScoreBorder": 41,
      "scoreItemList": [
        {
          "type": "CARD_COUNT_PER_ONE_FINGERPRINT",
          "scoreValue": 5
        },
        {
          "type": "EMAIL_COUNT_PER_CUSTOMER",
          "scoreValue": 10
        }
      ]
    }
  ]
}

Request parameter description:

• externalId - The transaction identifier in the client's system. It is unique within a single company in the antifraud system. This means that two transactions cannot be submitted with the same externalId.
• status - The transaction status. Possible values: NEW (the transaction is not yet being processed), PENDING (the transaction is being processed), ACCEPT (the transaction was successfully completed), DECLINE (the transaction was rejected).
• type - The transaction type. Possible values: PAYMENT, WITHDRAW.
• paymentMethod - Payment method information.
• description - Transaction description.
• dateStart - The transaction start date.
• dateEnd - The transaction end date.
• currency - The transaction currency.
• amount - The transaction amount.
• cascade - Cascade information. If the cascade has not previously been created in the system, it will be created.
  • cascade.externalId - The external identifier of the cascade.
  • cascade.title - The external name of the cascade.
  • cascade.gateList - information about gates in a cascade.
    • cascade.gateList.externalId - external identifier of a gate in a cascade. Will be created if it doesn't exist.
    • cascade.gateList.title - name of a gate in a cascade.
    • cascade.gateList.bankExternalId - external identifier of a gate's bank. Will be created if it doesn't exist.
    • cascade.gateList.bankTitle - name of a gate's bank.
    • cascade.gateList.currency - currency of a gate.
    • cascade.gateList.serialNumber - number of a gate in a cascade.
    • cascade.gateList.status - status of a gate. Possible values: NEW, ACCEPT, DECLINE.
    • cascade.gateList.declineBy - whether the transaction was rejected by the system or the bank.
    • cascade.gateList.errorReason - reason for rejecting the transaction at the gate.
    • cascade.gateList.commissionInfo.amountGateCurrency - calculated commission in the gate currency.
    • cascade.gateList.commissionInfo.amountTransactionCurrency - calculated commission in the transaction currency.
• merchantExternalId - external merchant identifier. Will be created if it doesn't exist.
• merchantTitle - merchant name.
• merchantAccountExternalId - external merchant account identifier. Will be created if it doesn't exist.
• merchantAccountTitle - merchant account name.
• customerExternalId - customer's external identifier.
• mccId - MCC identifier.
• isFtd - flag indicating the customer's first transaction.
• successReturnUrl - link to redirect the user to after a successful payment.
• failReturnUrl - link to redirect the user to after a payment is canceled.
• fingerprint - customer's fingerprint.
• email - customer's email.
• phone - customer's phone number.
• phoneCountry - customer's phone country code.
• dateOfBirthday - customer's date of birth.
• withdrawalCount - number of customer's withdrawals.
• depositCount - number of customer's deposits.
• isKycPassed - KYC passed indicator.
• registrationDate - customer's registration date.
• lastLoginDate - customer's last login date.
• cardToken - card token.
• cardBin - card BIN.
• cardCountry - card country code.
• cardLastFourDigit - last 4 digits of card.
• cardExpireDate - card expiration year and month.
• cardHolder - cardholder's first and last name.
• ipAddress - customer's IP address.
• ipAddressCountry - the country code of the customer's IP address.
• browserTimezone - the customer's time zone in UTC+4 format.
• addressFull - the customer's full address.
• address1 - the first line of the address.
• address2 - the second line of the address.
• city - the customer's city.
• country - the customer's country.
• postalCode - the customer's postal code.
• region - the customer's region.
• lang - the customer's language code.
• customData - arbitrary data in JSON format.
• browserData - the customer's browser data.

To update transaction information, you must submit the transaction in a new status. This means that a transaction can only be submitted three times: NEW → PENDING → ACCEPT or DECLINE. It is not possible to revert the status.

When updating a transaction, any field can be updated except dateStart.

This method never deletes information; it only adds to it. For example, if the first time a transaction was submitted, the first 10 gates were used, and when the transaction is resubmitted, the gates are replaced with 10 more gates, then 20 gates will be stored in the system.

When a transaction is saved, the transaction amount is also stored in dollars.

The conversion rate to dollars is obtained from openexchangerate.org.

Step 8. Actions after data transfer

Step 8.1 Enabling scoring

After data transfer is complete, you need to enable scoring (contact your manager and activate the necessary score generators) and begin saving data in real time using the Transaction processing method: POST /api/v1/client/transaction-process (see Step 7).

Step 8.2 Link Detect

Link detect is a feature for checking final links where the user will be redirected after payment. Links are checked against the merchant's list of available sites. This means that each merchant can have its own list of trusted URLs.

Checking logic:

1. If a merchant has enabled link detection, the transaction selection mechanism for link checking is triggered for transactions in the new and pending statuses (described below).
2. If a transaction has been selected for link validation, then upon transitioning to the accept or decline state, asynchronous link validation begins. Depending on the transaction status, the link passed in the request is validated (for accept, the successReturnUrl is checked, and for decline, the failReturnUrl is checked).
3. The robot, having certain parameters to simulate a real user, follows the specified link (successReturnUrl or failReturnUrl) and tries to reach the final link (regardless of how many redirects there are).
4. The resulting final link is compared against a list of approved URLs, and the result is recorded in the anti-fraud system. It's also possible to create alerts in the event of payments made through unauthorized links.

Transaction selection mechanism for link verification:

Links are verified for every nth transaction. By default, every 50th transaction is verified, but this number can be changed by contacting your manager.

Step 8.3 Fingerprints

A browser fingerprint is a unique digital identifier created from a combination of browser and device data (OS version, screen resolution, installed fonts, plugins, time zone, language, etc.).

We have developed our own SDK for collecting fingerprints, which are automatically sent to the anti-fraud system.

To begin the integration, contact a manager to obtain your personal domain and API key.

Next, add the SDK to your page:

<script>
    const fp = new EmbermindFingerprint.Fingerprint({
        domain: 'https://fp.yourcompany.com',
        apiKey: 'YOUR_API_KEY',
        sessionId: 'TRANSACTION_ID'
    });
</script>

Examples of HTML integration:

 <!DOCTYPE html>
<html>
<head>
    <title>Checkout</title>
</head>
<body>
    <!-- Your checkout form -->
    
    <script src="https://fp.yourcompany.com/sdk.js"></script>
    <script>
        const fp = new EmbermindFingerprint.Fingerprint({
            domain: 'https://fp.yourcompany.com',
            apiKey: 'YOUR_API_KEY',
            sessionId: 'txn_12345',
            extendedChecks: true
        });
        
        fp.onComplete((success, error) => {
            if (!success) {
                console.error('Fingerprint error:', error);
            }
        });
    </script>
</body>
</html>

React integration examples:

import { useEffect } from 'react';
import { Fingerprint } from '@embermind/embermind-fingerprint';
function CheckoutPage({ transactionId }: { transactionId: string }) {
    useEffect(() => {
        const fp = new Fingerprint({
            domain: 'https://fp.yourcompany.com',
            apiKey: process.env.REACT_APP_EMBERMIND_KEY,
            sessionId: transactionId,
            extendedChecks: true
        });
        
        fp.onComplete((success) => {
            console.log('Fingerprint:', success ? 'sent' : 'failed');
        });
    }, [transactionId]);
    
    return <div>Your checkout form</div>;
}

Next.js integration example:

import { useEffect } from 'react';
import { Fingerprint } from '@embermind/embermind-fingerprint';
export default function CheckoutPage({ transactionId }: { transactionId: string }) {
    useEffect(() => {
        if (typeof window !== 'undefined') {
            const fp = new Fingerprint({
                domain: 'https://fp.yourcompany.com',
                apiKey: process.env.NEXT_PUBLIC_EMBERMIND_KEY,
                sessionId: transactionId,
                extendedChecks: true
            });
        }
    }, [transactionId]);
    
    return <div>Your checkout form</div>;
}

Vue.js integration example:

<script setup lang="ts">
import { onMounted } from 'vue';
import { Fingerprint } from '@embermind/embermind-fingerprint';
const props = defineProps<{ transactionId: string }>();
onMounted(() => {
    const fp = new Fingerprint({
        domain: 'https://fp.yourcompany.com',
        apiKey: import.meta.env.VITE_EMBERMIND_KEY,
        sessionId: props.transactionId,
        extendedChecks: true
    });
});

Configuration options:

Configuration example:

const fp = new EmbermindFingerprint.Fingerprint({
    // Required - provided by your manager
    domain: 'https://fp.yourcompany.com',
    apiKey: 'em_live_abc123...',
    
    // Required - your transaction ID
    sessionId: 'txn_payment_98765',
    
    // Recommended
    extendedChecks: true,
    
    // Optional: FingerprintJS Pro integration
    fpcomApiKey: 'your-fingerprintjs-pro-key',
    fpcomDomain: 'https://metrics.yoursite.com'
});

If your page URL contains ?client_transaction_id=XXX, the SDK will use it automatically:

https://yoursite.com/checkout?client_transaction_id=txn_abc123

In this case you can omit sessionId in options - it will be extracted from URL.

FingerprintJS Pro Integration (Optional)

If you have a FingerprintJS Pro subscription, you can include their visitorId in the fingerprint data:

const fp = new EmbermindFingerprint.Fingerprint({
    domain: 'https://fp.yourcompany.com',
    apiKey: 'YOUR_API_KEY',
    sessionId: 'txn_12345',
    
    // FingerprintJS Pro credentials
    fpcomApiKey: 'YOUR_FINGERPRINTJS_PRO_KEY',
    fpcomDomain: 'https://fpmetrics.yoursite.com'
});

This sends both Embermind fingerprint and FingerprintJS Pro visitorId for enhanced accuracy.

Extended Checks

When extendedChecks: true is enabled, the SDK collects additional data for VM and bot detection:

• CPU timing patterns
• Memory access patterns
• Timer precision analysis
• Canvas rendering timing
• Crypto operation timing

Detects:

• Virtual machines (VMware, VirtualBox, Hyper-V)
• Headless browsers (Puppeteer, Playwright, Selenium)
• Browser automation tools
• Emulators

Recommendation: Always enable extendedChecks: true for payment and registration pages.

Completion Callback

Track when fingerprint collection completes:

const fp = new EmbermindFingerprint.Fingerprint({
    domain: 'https://fp.yourcompany.com',
    apiKey: 'YOUR_API_KEY',
    sessionId: 'txn_12345'
});
fp.onComplete((success, error) => {
    if (success) {
        console.log('Fingerprint sent successfully');
        // Proceed with payment/action
    } else {
        console.error('Fingerprint failed:', error);
        // Handle error (optional - don't block user)
    }
});

Browser Compatibility

Best Practices

1. Initialize early - Add SDK at the start of page load
2. Use transaction ID - Always pass your transaction/session ID for correlation
3. Enable extended checks - Use extendedChecks: true on sensitive pages
4. Don't block on errors - If fingerprint fails, allow user to proceed
5. Use HTTPS - Your page must be served over HTTPS

Troubleshooting

Fingerprint not sending

1. Check browser console for errors
2. Verify domain and apiKey are correct
3. Ensure page is served over HTTPS
4. Verify DNS is configured for your domain

onComplete not firing

1. Verify domain is provided
2. Check if page closes before collection completes

Support

For integration support, contact your Embermind manager.