Overview

Regular transaction series detection is user-scoped: every detect and result message includes a userId, and result egress is always shaped as { userId, accounts[] }. A user may have multiple accounts (for example, a current account and a credit card).

How many accounts are processed in each detect message — and therefore how detection is batched — is configurable. The daily regular-transactions orchestrator controls this via REGULAR_TRANSACTIONS_GROUP_BY_USER_ID (see Orchestrator detect batching):

Manual publishes to the detect topic may use either shape, provided accounts contains at least one entry.

To request detection, publish a message to the regular-transactions detect topic. The worker reads transactions for each listed account, detects series, persists predictions, and publishes a user-scoped result to the regular-transactions result topic.

This mirrors the affordability interface: one userId in, one user-scoped message out per detect message processed.

Configuration

Several deployment options affect how detect messages are produced and whether affordability is triggered automatically. These are configured by Moneyhub for your environment; see List of configurable features.

Orchestrator detect batching

Controlled by REGULAR_TRANSACTIONS_GROUP_BY_USER_ID on the orchestrator (default: false).

The daily regular-transactions orchestrator publishes detect messages to the regular-transactions-detect topic. The message schema is always { userId, accounts[] }, but the number of accounts in each message is configurable:

In per user mode, the orchestrator also pages and buckets by userId rather than accountId.

Example (detect message — per account mode)

When batching is set to per account, each detect message contains one account:

{
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "accounts": [
    {
      "accountId": "090ea264-eb48-494c-9d59-1b10b322c3e1",
      "mode": "full"
    }
  ]
}

Example (detect message — per user mode)

When batching is set to per user, one message lists every account for that user in the batch:

{
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "accounts": [
    {
      "accountId": "090ea264-eb48-494c-9d59-1b10b322c3e1",
      "mode": "full"
    },
    {
      "accountId": "de4be182-efb4-4aad-b221-fa29631e6653",
      "mode": "incremental",
      "updatedAt": "2026-06-01T12:00:00.000Z"
    }
  ]
}

Manual publishes to the detect topic may use either shape, provided accounts contains at least one entry.

Affordability auto-trigger

Controlled by ENABLE_REGULAR_TRANSACTIONS_REQUEST_AFFORDABILITY_REPORT_ON_COMPLETION on the regular-transactions worker (default: false).

The regular-transactions worker can be configured to automatically request an affordability report after it successfully processes a detect message for a user.

When enabled, one affordability calculate message is sent per user detect message processed, regardless of how many accounts were in accounts[]. See Affordability result schema for the calculate and result message formats.

Request message (regular-transactions-detect)

The Kafka message value must be a JSON object:

Each element of accounts[]:

In full mode the worker loads the configured retention window of transaction history. In incremental mode it loads transactions from updatedAt onwards and merges with existing predictions.

The message key should be a unique identifier (UUID recommended). It is copied to the corresponding result message.

See Configuration for how the orchestrator groups accounts when publishing detect messages.

Result topic (regular-transactions-result)

Topic names are configurable per environment. Failed messages are sent to the regular-transactions dead-letter topic (regular-transactions-dead-letter / external-regular-transactions-dead-letter); see Errors for the general dead-letter envelope shape.

Result message envelope

The Kafka message value is a JSON object produced by the regular-transactions worker after processing a regular-transactions-detect message:

The message key is copied from the triggering detect message when present; otherwise a new UUID is generated.

Account result (accounts[])

Series object (predictions[])

Each element matches the object built in the worker's result-formatting stage.

Transaction object (transactions[])

Example (result message body)

{
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "accounts": [
    {
      "accountId": "090ea264-eb48-494c-9d59-1b10b322c3e1",
      "predictions": [
        {
          "seriesId": "45f004dc-254f-5d09-b07f-8d4de4487781",
          "accountId": "090ea264-eb48-494c-9d59-1b10b322c3e1",
          "userId": "550e8400-e29b-41d4-a716-446655440000",
          "type": "payment",
          "subtype": "frequentVisit",
          "frequency": "quarterly",
          "description": "Dentist Checkup",
          "cleanedDescription": "Dentist Checkup",
          "numTxMatchedInSeries": 4,
          "gapLengthInFreqUnits": 0,
          "dateAnomaliesCount": 0,
          "numReturnedTxs": 0,
          "lastDate": "2026-01-20",
          "predictedDate": "2026-04-20",
          "predictedDateEarliest": "2026-04-20",
          "predictedDateLatest": "2026-04-21",
          "predictedTxLateOrNotDetected": false,
          "predictedAmount": -65,
          "predictedAmountLower": -65,
          "predictedAmountUpper": -65,
          "currency": "GBP",
          "counterpartyId": "203d5a9a-d4dd-5ce5-ab60-60f740336dea",
          "predictedCategoryId": "11",
          "l3CounterpartyCategory": null,
          "transactions": [
            {
              "uid": "TXN-090ea264-775",
              "date": "2026-01-20",
              "description": "Dentist Checkup",
              "amount": -65,
              "categoryId": "11",
              "cleanedDescription": "Dentist Checkup",
              "txCode": null,
              "cardPresent": false,
              "l3CounterpartyCategory": null
            },
            {
              "uid": "TXN-090ea264-774",
              "date": "2025-10-20",
              "description": "Dentist Checkup",
              "amount": -65,
              "categoryId": "11",
              "cleanedDescription": "Dentist Checkup",
              "txCode": null,
              "cardPresent": false,
              "l3CounterpartyCategory": null
            }
          ]
        }
      ]
    },
    {
      "accountId": "de4be182-efb4-4aad-b221-fa29631e6653",
      "predictions": []
    }
  ]
}