Commission Setup

A commission is a fee charged for processing a transaction through a payment gate.

Overview

The antifraud system includes a built-in commission calculation mechanism with the following priority: gate → bank. If no commission tariff is configured for a gate, the system falls back to the bank's tariff.

Alternatively, you can submit pre-calculated commission values when creating a transaction. In this case, the system will store your provided values instead of calculating them.

All commissions are stored in both the transaction currency and USD.

Tip: Configure commission calculation for each gate and bank before starting data migration. Commissions will be automatically calculated and saved during migration.

Fee Calculation Algorithm

Commission settings are configured separately for ACCEPT and DECLINE transaction statuses.

Each commission rule consists of three components:

Component	Description
Fixed	A fixed value, can be absolute or a percentage of the transaction amount
Percentage	A percentage of the transaction amount
Minimum	The minimum commission amount (absolute value)

Calculation formula:

Calculate: fixed value + (percentage × transaction amount)
Compare with minimum: use whichever is greater

Create Commission Tariff

First, create a commission tariff using the Create CommissionTariff endpoint.

Request parameters:

Parameter	Type	Required	Description
`title`	string	Yes	Tariff name
`priorityOne`	string	Yes	First priority entity. Values: COUNTRY / CARD_BRAND / MCC_ID
`priorityTwo`	string	Yes	Second priority entity. Values: COUNTRY / CARD_BRAND / MCC_ID
`priorityThree`	string	Yes	Third priority entity. Values: COUNTRY / CARD_BRAND / MCC_ID

Example request:

curl -X POST 'https://api.embermind.ch/api/v1/client/commission-tariffs/create' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -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",
  "createdAt": "2024-01-15T10:25:00.027Z",
  "companyId": "7992110d-617e-40c5-82323b9a-94e8248ad2f1"
}

Create Commission Rules

Create commission rules for the tariff using the Create CommissionRule endpoint.

Request parameters:

Parameter	Type	Required	Description
`commissionTariffId`	string (uuid)	Yes	ID of the commission tariff
`direction`	string	Yes	ACCEPT or DECLINE
`percent`	number	No	Percentage of transaction amount
`fixPercent`	number	No	Fixed percentage of the transaction amount
`fixAmount`	number	No	Fixed amount
`minAmount`	number	No	Minimum commission amount
`cardBrand`	string	No	Card brand. Values: VISA / MASTERCARD / JCB / DISCOVER / AMERICAN_EXPRESS / DINERS_CLUB / UNION_PAY / MIR
`country`	string	No	Country code (e.g., RU, DE)
`mccId`	string	No	MCC for commission calculation

Example request:

curl -X POST 'https://api.embermind.ch/api/v1/client/commission-rules/create' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -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):

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "direction": "ACCEPT",
  "percent": 10,
  "fixPercent": 10,
  "fixAmount": 15,
  "minAmount": 5,
  "country": "RU",
  "cardBrand": "VISA",
  "mccId": "mccExample",
  "createdAt": "2024-01-15T10:27:00.027Z",
  "commissionTariffId": "69e45d20-98a9-4c75-ab60-1188d64d510a"
}

Create Bank

Before creating a gate, create a bank using POST /api/v1/client/banks-crud/create.

Request parameters:

Parameter	Type	Required	Description
`title`	string	Yes	Bank name
`externalId`	string	Yes	Bank external ID
`commissionTariffId`	string (uuid) \| null	Yes	ID of the commission tariff (optional)

Example request:

curl -X POST 'https://api.embermind.ch/api/v1/client/banks-crud/create' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -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",
    "titleExtra": null,
    "isDelete": false,
    "externalId": "BANK_EXTERNAL_ID",
    "createdAt": "2024-01-15T10:30:00.027Z",
    "commissionTariffId": "69e45d20-98a9-4c75-ab60-1188d64d510a"
  }
}

Create Gate

Create a gate using POST /api/v1/client/gates-crud/create.

Request parameters:

Parameter	Type	Required	Description
`title`	string	Yes	Gate name
`externalId`	string	Yes	Gate external ID
`currency`	string	Yes	Gate currency (e.g., EUR, USD)
`bankId`	string (uuid)	Yes	ID of the bank
`commissionTariffId`	string (uuid)	Yes	ID of the commission tariff (optional)

Example request:

curl -X POST 'https://api.embermind.ch/api/v1/client/gates-crud/create' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -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",
    "titleExtra": null,
    "currency": "EUR",
    "isDelete": false,
    "externalId": "GATE_EXTERNAL_ID",
    "createdAt": "2024-01-15T10:31:00.027Z",
    "commissionTariffId": "69e45d20-98a9-4c75-ab60-1188d64d510a"
  }
}

Next Steps

Customer Grouping — Configure customer identification rules
Data Migration — Import historical transactions