Scoring Rules

Score generators analyze transaction patterns and calculate risk scores. Each transaction receives a score from 0-100, where higher values indicate higher fraud risk.

Overview

Default scoring settings are automatically created when your company account is set up. The system creates one SYSTEM generator for each type.

You can modify scoring settings:

In the Admin Panel: Settings → Score Generator
Via API: Score Generators endpoints

System vs Manual Generators

Score generators are divided into two categories based on createType:

Create Type	Description	Can Delete	Can Change Targets
`SYSTEM`	Created automatically when company is set up. One per type. Applied globally.	No	No
`MANUAL`	Created by user via API. Must be linked to specific Cascade/Gate/Merchant.	Yes	Yes

Key differences:

SYSTEM generators — apply to all transactions by default (when no MANUAL generator of the same type is linked to transaction's cascade/gate/merchant)
MANUAL generators — override SYSTEM generators for specific cascades, gates, or merchants

Score Generator Types

Type	Description	Parameters
`BW_LIST_SYSTEM`	System-wide blacklist/whitelist check	—
`BW_LIST_COMPANY`	Company-specific blacklist/whitelist check	—
`USE_VPN`	VPN usage detection	—
`CARD_COUNT_PER_ONE_FINGERPRINT`	Number of different cards used from same fingerprint	`optCount`
`FINGERPRINT_COUNT_PER_ONE_CARD`	Number of different fingerprints used with same card	`optCount`
`EMAIL_COUNT_PER_CUSTOMER`	Number of different emails per customer	`optCount`
`IP_ADDRESS_COUNT_PER_CUSTOMER`	Number of different IPs per customer	`optCount`
`COUNTRY_COUNT_PER_CUSTOMER`	Number of different countries per customer	`optCount`
`ERROR_RATE_PER_CUSTOMER`	Transaction error rate per customer	`optPeriodSec`, `optPercent`
`THREEDS_TIMEOUT_COUNT_PER_CUSTOMER`	3DS timeout count per customer	`optCount`, `optPeriodSec`
`THREEDS_TIMEOUT_COUNT_PER_CARD`	3DS timeout count per card	`optCount`, `optPeriodSec`
`THREEDS_ERROR_COUNT_PER_CUSTOMER`	3DS error count per customer	`optCount`, `optPeriodSec`
`THREEDS_ERROR_COUNT_PER_CARD`	3DS error count per card	`optCount`, `optPeriodSec`
`IP_ADDRESS_COUNTRY_EQUAL_BIN_COUNTRY`	IP country matches card BIN country	—
`BROWSER_TZ_EQUAL_IP_ADDRESS_TZ`	Browser timezone matches IP address timezone	—
`CHARGEBACK_COUNT_PER_CUSTOMER`	Chargeback count per customer	`optCount`, `optPeriodSec`
`REFUND_COUNT_PER_CUSTOMER`	Refund count per customer	`optCount`, `optPeriodSec`
`TRANSACTION_COUNT_PER_CUSTOMER`	Total transaction count per customer	`optCount`, `optPeriodSec`
`TRANSACTION_COUNT_PER_CUSTOMER_AND_GATE`	Transaction count per customer and gate	`optCount`, `optPeriodSec`
`TRANSACTION_COUNT_PER_CUSTOMER_AND_CASCADE`	Transaction count per customer and cascade	`optCount`, `optPeriodSec`
`TRANSACTION_SUCCESS_COUNT_PER_CUSTOMER`	Successful transaction count per customer	`optCount`, `optPeriodSec`
`TRANSACTION_SUCCESS_COUNT_PER_CUSTOMER_AND_GATE`	Successful transaction count per customer and gate	`optCount`, `optPeriodSec`
`TRANSACTION_SUCCESS_COUNT_PER_CUSTOMER_AND_CASCADE`	Successful transaction count per customer and cascade	`optCount`, `optPeriodSec`

Generator Parameters

Different generator types require different parameters:

Parameter	Type	Description	Example
`optCount`	integer	Threshold count. Score is added when actual count exceeds this value	`10`
`optPercent`	integer	Threshold percentage (0-100)	`50`
`optPeriodSec`	integer	Time period in seconds for counting events	`14400` (4 hours)

Default values:

optCount: 10
optPercent: 50
optPeriodSec: 14400 (4 hours)

Action When No Parameter (actionNoParam)

Defines behavior when required parameter is not set:

Value	Description
`NO_SCORE`	Do not add any score points (default)
`MAX_SCORE`	Add maximum score value
`ERROR`	Return an error

Generator Selection for Transaction

When a transaction is processed, the system selects which generator to apply for each type:

Check for MANUAL generators linked to transaction's cascade, gate, or merchant
If found — use the MANUAL generator based on priority settings
If not found — use the SYSTEM generator

Priority order is determined by company settings (scoreGeneratorPriorityOne, scoreGeneratorPriorityTwo, scoreGeneratorPriorityThree).

Uniqueness constraint: Only one generator of each type can be linked to a specific cascade/gate/merchant. You cannot create two CARD_COUNT_PER_ONE_FINGERPRINT generators for the same gate.

Score Generator Priority

Score generators can be configured at three levels with different priorities:

Priority	Entity	Description
`CASCADE`	Cascade	Apply to all gates in a cascade
`GATE`	Gate	Apply to specific gate only
`MERCHANT`	Merchant	Apply to all transactions of a merchant

Configure priority order in company settings:

curl -X POST 'https://api.embermind.ch/api/v1/client/company-settings/update' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{
    "scoreGeneratorPriorityOne": "GATE",
    "scoreGeneratorPriorityTwo": "CASCADE",
    "scoreGeneratorPriorityThree": "MERCHANT"
  }'

Bad Score Border

The badScoreBorder threshold determines when a transaction is considered risky:

scoreValue < badScoreBorder → Transaction is likely safe
scoreValue >= badScoreBorder → Transaction may be fraudulent

Default value: 50

curl -X POST 'https://api.embermind.ch/api/v1/client/company-settings/update' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{
    "badScoreBorder": 41
  }'

API Reference

Base URL: https://api.embermind.ch/api/v1/client/score-generators

Get Generator Types

Get list of all generator types with their required parameters.

curl -X GET 'https://api.embermind.ch/api/v1/client/score-generators/type-list' \
  -H 'x-api-key: YOUR_API_KEY'

Response:

{
  "data": {
    "CARD_COUNT_PER_ONE_FINGERPRINT": {
      "options": {
        "optCount": 10
      }
    },
    "ERROR_RATE_PER_CUSTOMER": {
      "options": {
        "optPeriodSec": 14400,
        "optPercent": 50
      }
    }
  }
}

Get Generator List

Get all score generators in your company.

curl -X POST 'https://api.embermind.ch/api/v1/client/score-generators/get-list' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{
    "type": "CARD_COUNT_PER_ONE_FINGERPRINT",
    "searchValue": "my generator",
    "merchantIdList": ["uuid-1", "uuid-2"]
  }'

All parameters are optional. Use them to filter results.

Get One Generator

Get detailed information about a specific generator.

curl -X POST 'https://api.embermind.ch/api/v1/client/score-generators/get-one' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{
    "scoreGeneratorId": "69e45d20-98a9-4c75-ab60-1188d64d510a"
  }'

Response includes:

Generator settings (title, type, scoreValue, isActive, etc.)
Linked entities (cascadeList, gateList, merchantList)

Create Generator

Create a new MANUAL generator linked to specific targets.

curl -X POST 'https://api.embermind.ch/api/v1/client/score-generators/create' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{
    "title": "High risk card limit",
    "type": "CARD_COUNT_PER_ONE_FINGERPRINT",
    "scoreValue": 25,
    "actionNoParam": "NO_SCORE",
    "isPriority": false,
    "optCount": 5,
    "targetEntityType": "GATE",
    "targetIdList": ["gate-uuid-1", "gate-uuid-2"]
  }'

Required fields:

Field	Type	Description
`title`	string	Generator name
`type`	string	Generator type (see types table)
`scoreValue`	number	Score points to add when triggered
`actionNoParam`	string	`NO_SCORE` / `MAX_SCORE` / `ERROR`
`isPriority`	boolean	Mark as priority generator
`targetEntityType`	string	`CASCADE` / `GATE` / `MERCHANT`
`targetIdList`	array	UUIDs of target entities

Type-specific parameters (depending on generator type):

optCount — threshold count
optPercent — threshold percentage
optPeriodSec — time period in seconds

Update Generator

Update an existing generator.

curl -X POST 'https://api.embermind.ch/api/v1/client/score-generators/update' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{
    "scoreGeneratorId": "69e45d20-98a9-4c75-ab60-1188d64d510a",
    "title": "Updated title",
    "scoreValue": 30,
    "optCount": 3,
    "isActive": true
  }'

Important:

For SYSTEM generators: you can update title, scoreValue, actionNoParam, isPriority, isActive, and type-specific parameters
For SYSTEM generators: you cannot change targetEntityType or targetIdList
For MANUAL generators: you can update all fields including targets

Toggle Priority

Enable or disable priority flag for a generator (MANUAL only).

curl -X POST 'https://api.embermind.ch/api/v1/client/score-generators/toggle-priority' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{
    "scoreGeneratorId": "69e45d20-98a9-4c75-ab60-1188d64d510a",
    "isPriority": true
  }'

Toggle Active

Enable or disable a generator without deleting it.

curl -X POST 'https://api.embermind.ch/api/v1/client/score-generators/toggle-active' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{
    "scoreGeneratorId": "69e45d20-98a9-4c75-ab60-1188d64d510a",
    "isActive": false
  }'

Remove Generator

Permanently delete a generator (MANUAL only).

curl -X POST 'https://api.embermind.ch/api/v1/client/score-generators/remove' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{
    "scoreGeneratorId": "69e45d20-98a9-4c75-ab60-1188d64d510a"
  }'

Note: SYSTEM generators cannot be deleted. Use toggle-active to disable them instead.

Examples

Example 1: Create a New Score Generator

Scenario: You want to add a custom chargeback limit for a specific merchant — trigger scoring when a customer has more than 3 chargebacks in 24 hours.

Step 1: Check available generator types and their required parameters:

curl -X GET 'https://api.embermind.ch/api/v1/client/score-generators/type-list' \
  -H 'x-api-key: YOUR_API_KEY'

Response (excerpt):

{
  "data": {
    "CHARGEBACK_COUNT_PER_CUSTOMER": {
      "options": {
        "optCount": 10,
        "optPeriodSec": 14400
      }
    }
  }
}

This tells us that CHARGEBACK_COUNT_PER_CUSTOMER requires two parameters: optCount (threshold) and optPeriodSec (time period).

Step 2: Get your merchant ID. You can use the merchants endpoint:

curl -X POST 'https://api.embermind.ch/api/v1/client/merchants/get-list' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{}'

Response (excerpt):

{
  "dataList": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "title": "My Online Store"
    }
  ]
}

Step 3: Create the generator:

curl -X POST 'https://api.embermind.ch/api/v1/client/score-generators/create' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{
    "title": "Strict chargeback limit for My Online Store",
    "type": "CHARGEBACK_COUNT_PER_CUSTOMER",
    "scoreValue": 50,
    "actionNoParam": "NO_SCORE",
    "isPriority": false,
    "optCount": 3,
    "optPeriodSec": 86400,
    "targetEntityType": "MERCHANT",
    "targetIdList": ["a1b2c3d4-e5f6-7890-abcd-ef1234567890"]
  }'

Response:

{
  "message": "ok"
}

Now transactions for this merchant will get +50 score points if the customer has more than 3 chargebacks in the last 24 hours (86400 seconds).

Example 2: Update an Existing Score Generator

Scenario: You want to make the SYSTEM generator for CARD_COUNT_PER_ONE_FINGERPRINT stricter — reduce the threshold from 10 cards to 5.

Step 1: Get the list of existing generators and find the one you want to update:

curl -X POST 'https://api.embermind.ch/api/v1/client/score-generators/get-list' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{
    "type": "CARD_COUNT_PER_ONE_FINGERPRINT"
  }'

Response:

{
  "dataList": [
    {
      "id": "11111111-2222-3333-4444-555555555555",
      "title": "DEFAULT_CARD_COUNT_PER_ONE_FINGERPRINT",
      "type": "CARD_COUNT_PER_ONE_FINGERPRINT",
      "createType": "SYSTEM",
      "scoreValue": 10,
      "actionNoParam": "NO_SCORE",
      "isPriority": false,
      "isActive": true,
      "optCount": 10,
      "optPercent": null,
      "optPeriodSec": null,
      "cascadeList": [],
      "gateList": [],
      "merchantList": []
    }
  ]
}

We found the SYSTEM generator with id: "11111111-2222-3333-4444-555555555555" and current optCount: 10.

Step 2: (Optional) Get detailed info about this generator:

curl -X POST 'https://api.embermind.ch/api/v1/client/score-generators/get-one' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{
    "scoreGeneratorId": "11111111-2222-3333-4444-555555555555"
  }'

Step 3: Update the generator:

curl -X POST 'https://api.embermind.ch/api/v1/client/score-generators/update' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{
    "scoreGeneratorId": "11111111-2222-3333-4444-555555555555",
    "optCount": 5,
    "scoreValue": 20
  }'

Response:

{
  "message": "ok"
}

Now the generator will trigger when a customer uses more than 5 different cards (instead of 10) and will add 20 score points (instead of 10).

Note: Since this is a SYSTEM generator, we can only update its parameters (optCount, scoreValue, title, isActive, etc.). We cannot change targetEntityType or targetIdList for SYSTEM generators.

Example 3: Create a Custom Generator for Specific Gates

Scenario: You want stricter card limits for two high-risk gates, but keep default settings for all other gates.

Step 1: Get your gate IDs:

curl -X POST 'https://api.embermind.ch/api/v1/client/gates/get-list' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{}'

Response (excerpt):

{
  "dataList": [
    { "id": "gate-uuid-1", "title": "High Risk Gate A" },
    { "id": "gate-uuid-2", "title": "High Risk Gate B" },
    { "id": "gate-uuid-3", "title": "Regular Gate" }
  ]
}

Step 2: Create a MANUAL generator for the two high-risk gates:

curl -X POST 'https://api.embermind.ch/api/v1/client/score-generators/create' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{
    "title": "Strict card limit for high-risk gates",
    "type": "CARD_COUNT_PER_ONE_FINGERPRINT",
    "scoreValue": 40,
    "actionNoParam": "NO_SCORE",
    "isPriority": false,
    "optCount": 2,
    "targetEntityType": "GATE",
    "targetIdList": ["gate-uuid-1", "gate-uuid-2"]
  }'

Result:

Transactions on gate-uuid-1 and gate-uuid-2 → use the new MANUAL generator (trigger at 2 cards, +40 score)
Transactions on gate-uuid-3 and all other gates → use the SYSTEM generator (trigger at 10 cards, +10 score by default)

Data Migration Tip

Important: Disable scoring generators during historical data migration to improve processing speed. Scoring on historical data provides limited value since patterns are analyzed in real-time.

Contact your manager to completely disable scoring temporarily.

Next Steps

Alerts — Configure fraud alert notifications
Data Migration — Import historical transactions