Configurations CRUD

Per-business financial module configuration: control which processing modules are active for each acquirer.

---

Overview

Attribute	Value
Service	src/service/FinancesConfigService.ts
Storage	MongoDB financesConfig collection
Schema	src/schema/finances_config_request.json

---

Configuration Model

Each configuration defines which financial modules are enabled for a specific business (or globally).

Field	Type	Description
_id	ObjectId	MongoDB document ID
entity_id	string	Business ID, or global for global configuration
entity_type	string	BUSINESS or GLOBAL
description	string	Human-readable description
acquirers	object	Per-acquirer module configuration (keyed by acquirer name)
created_at	string	Creation timestamp
modified_at	string	Last modification timestamp

Per-Acquirer Configuration

Each key in the acquirers object is an acquirer name (e.g., kushki, unlimit) or _default for the fallback configuration.

Field	Type	Description
fees_calculation	string[]	Journal categories that trigger fee calculation. Array of JournalCategoryEnum values.
ledger_entries	boolean	Whether to generate ledger entries and update account balances
journals_generation	boolean	Whether to generate accounting journals
daily_balances	boolean	Whether to include in daily balance snapshots

The _default Acquirer Key

When a transaction comes from an acquirer not explicitly configured, the system falls back to the _default key. If neither the specific acquirer nor _default exists, the module is considered disabled.

Example Configuration

{
  "entity_id": "business-123",
  "entity_type": "BUSINESS",
  "description": "Config for Business ABC",
  "acquirers": {
    "_default": {
      "fees_calculation": ["PAYMENT", "REFUND", "DISPUTE_WON", "DISPUTE_IN_REVIEW", "VOID"],
      "ledger_entries": true,
      "journals_generation": true,
      "daily_balances": true
    },
    "kushki": {
      "fees_calculation": ["PAYMENT", "REFUND", "DISPUTE_WON", "DISPUTE_IN_REVIEW", "VOID", "WITHDRAWAL", "TOPUP"],
      "ledger_entries": true,
      "journals_generation": true,
      "daily_balances": true
    }
  }
}

---

Endpoints

Method	Path	Description
POST	/v1/configurations	Create a new configuration
GET	/v1/configurations	List configurations with filters
GET	/v1/configurations/{id}	Get configuration by ID
PATCH	/v1/configurations/{id}	Update configuration
DELETE	/v1/configurations/{id}	Delete configuration

---

Module Impact

What happens when each module is disabled:

Module	When Disabled
fees_calculation	Fees are not calculated for the specified categories. Journals will have zero fee amounts.
journals_generation	No journals are created. No accounting record of the transaction.
ledger_entries	Journals are created but no ledger entries generated. Account balances are NOT updated.
daily_balances	Business excluded from daily balance snapshot reports.

Important: Disabling journals_generation effectively disables the entire financial processing for that acquirer, since journals are the foundation for ledger entries and settlements.

---

Global vs Business-Specific

• Business-specific (entity_id = business ID): Applies only to that business
• Global (entity_id = global): Applies to all businesses without a specific configuration

Lookup order: business-specific → global → module disabled.

---

Processing Flow