Overview

Affordability reports are produced per user. A user may have multiple accounts (for example, a current account and a credit card); the report aggregates enriched transactions and regular-transaction predictions across all of that user's accounts.

To request a report, publish a message to the affordability calculate topic. The affordability worker reads the user's data from storage, computes the report, and publishes the result to the affordability result topic.

When ENABLE_REGULAR_TRANSACTIONS_REQUEST_AFFORDABILITY_REPORT_ON_COMPLETION is enabled for regular transactions (see Configuration in the regular transactions schema), the regular-transactions worker publishes calculate messages automatically after successful detection; manual publishing is not required in that case.

Request message (affordability-calculate)

The Kafka message value must be a JSON object:

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

Example (request message)

{
  "userId": "550e8400-e29b-41d4-a716-446655440000"
}

Result topic (affordability-result)

The affordability worker publishes successful calculation results to the affordability result topic.

Topic names are configurable per environment. Failed messages are sent to the affordability dead-letter topic (affordability-dead-letter / external-affordability-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 affordability worker after processing an affordability-calculate message:

At least one of userId or accountId is present, matching the calculate request. The message key is copied from the triggering affordability-calculate message when present; otherwise a new UUID is generated.

Report object (fullAffordabilityReport)

The report analyses up to 12 months of transaction history across accounts in scope for the request, ending on the calculation date. Amounts are plain numbers in major currency units (for example, pounds rather than pence).

Missing sections may be omitted when the calculator does not produce them.

income

income.categoriesUsed[]

income.longevity

Each longevity sub-object has a months integer field.

income.primaryIncomeAccount

income.regularIncome

income.regularIncome.predicted.monthly

expenditure

Each category object contains a median amount (negative for outflows).

Expenditure category object

transfers

transfers.out

gambling

gambling.out

loans

loans.opened.details[]

One entry per loan type and loan window (30, 90, 180, and 365 days).

loans.repayments

returnedPayments

returnedPayments.details[]

One entry per affordability category and period (30, 90, 180, and 365 days).

overdrafts.usage.details[]

overdrafts.usage.details[].periodsInOverdraft[]

unarrangedOverdraft

Each periods[] element has start, end, days, and minimumBalance fields (plain-number balances).

Example (result message body)

{
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "fullAffordabilityReport": {
    "income": {
      "median": 2403.74,
      "medianIncludingTransfers": 2403.74,
      "amountConsistency": 0.99,
      "categoriesUsed": [
        {
          "uid": "27",
          "key": "deposits"
        }
      ],
      "longevity": {
        "consecutiveIncome": {
          "months": 12
        },
        "incomePeriodLength": {
          "months": 12
        }
      },
      "primaryIncomeAccount": {
        "uid": "b874c5fe-3dc1-4752-a93f-26b99320430c"
      },
      "regularIncome": {
        "isDetected": true,
        "predicted": {
          "monthly": {
            "amount": 2403.74
          }
        }
      }
    },
    "expenditure": {
      "cashWithdrawals": {
        "median": -161.32
      },
      "discretionary": {
        "median": -516.77
      },
      "fixed": {
        "median": -1455.11
      },
      "flexible": {
        "median": -808.26
      },
      "nonDiscretionary": {
        "median": -1748.96
      }
    },
    "transfers": {
      "median": -51.22,
      "out": {
        "median": -203.25
      }
    },
    "gambling": {
      "out": {
        "median": -100.26
      }
    },
    "loans": {
      "opened": {
        "details": []
      },
      "repayments": {
        "median": -283.35
      }
    },
    "returnedPayments": {
      "count": 0,
      "period": {
        "months": 11
      },
      "details": []
    },
    "overdrafts": {
      "usage": {
        "details": []
      }
    }
  }
}