MerchantAccount Entity

The MerchantAccount entity represents an aggregate that manages all financial transactions and balance accounts for a specific merchant. It implements event sourcing and command handling patterns to ensure data consistency and auditability. Merchant may have multiple merchantAccounts, one per currency.

Properties

Name	Type	Required	Description
`id`	`uuid`	Required	Unique identifier for the account (UUID format)
`owner_id`	`uuid`	Required	Foreign key reference to the account owner
`currency`	`string`	Required	The currency in which the account operates (ISO 4217, 3 characters)
`delay`	`decimal`	Required	Delay configuration for the account (numeric 2,0)
`country`	`string`	Required	Country code where the account operates (ISO 3166, 3 characters)
`iban`	`string`	Required	International Bank Account Number (max 34 characters)
`bic`	`string`	Required	Bank Identifier Code (max 34 characters)

Schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "title": "MerchantAccount",
  "description": "Represents a merchant account aggregate that manages financial transactions and balances for a specific merchant",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "description": "Unique identifier for the account (UUID format)",
      "example": "550e8400-e29b-41d4-a716-446655440000"
    },
    "owner_id": {
      "type": "string",
      "format": "uuid",
      "description": "Foreign key reference to the account owner",
      "example": "660e8400-e29b-41d4-a716-446655440001"
    },
    "currency": {
      "type": "string",
      "pattern": "^[A-Z]{3}$",
      "description": "The currency in which the account operates (ISO 4217, 3 characters)",
      "example": "NOK"
    },
    "delay": {
      "type": "integer",
      "description": "Delay configuration for the account",
      "example": 2
    },
    "country": {
      "type": "string",
      "pattern": "^[A-Z]{3}$",
      "description": "Country code where the account operates (ISO 3166, 3 characters)",
      "example": "NOR"
    },
    "iban": {
      "type": "string",
      "maxLength": 34,
      "description": "International Bank Account Number (max 34 characters)",
      "example": "NO9386011117947"
    },
    "bic": {
      "type": "string",
      "maxLength": 34,
      "description": "Bank Identifier Code (max 34 characters)",
      "example": "DNBANOKKXXX"
    }
  },
  "required": ["id", "owner_id", "currency", "delay", "country", "iban", "bic"],
  "additionalProperties": false
}

Managed Account Types

The MerchantAccount aggregate manages multiple types of balance accounts:

MerchantDebt: Tracks outstanding debt to the merchant
ClientFunds: Manages client funds held in custody
PSPReceivable: Tracks amounts receivable from Payment Service Providers
Escrow: Manages escrowed funds
Caps: Handles transaction caps and limits
Revenue: Tracks revenue generated

Supported Operations

Account creation and management
Transaction posting with double-entry bookkeeping
Amount reservation and release
Balance notifications and triggers
Pending refund eligibility tracking and authorization
Ledger updates and account definition management

Event Sourcing

The MerchantAccount aggregate uses event sourcing to maintain its state through a series of events:

AccountCreatedEvent
AccountDefinitionAddedEvent
LedgerIdUpdatedEvent
TransactionPostedEvent
AmountReservedEvent
ReservationReleasedEvent
UpdateEligiblePendingRefundsArmedEvent
RemovePendingRefundEvent
ScheduleAuthorizeForEligibleRefundsEvent
BalanceUpdatedEvent

Business Rules

Maintains double-entry bookkeeping principles
Enforces sufficient balance checks for liability accounts
Supports currency validation
Implements transaction type validation
Manages remittance order dates and due dates
Enables automatic refund authorization based on available balance
Tracks eligible pending refunds using FIFO approach

MerchantAccount (v1.0.0)

Represents a merchant account aggregate that manages financial transactions and balances for a specific merchant