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. A corresponding result is then published to the affordability result topic.

Moneyhub can also configure regular-transaction detection to request affordability automatically after a successful run, so manual calculate publishes are not always required. See List of configurable features.

Request message

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

Successful calculation results are published to the affordability result topic. Failed messages are sent to the affordability dead-letter topic; see Errors for the general dead-letter envelope shape.

Result message envelope

The Kafka message value is a JSON object:

At least one of userId or accountId is present, matching the calculate request. The message key is copied from the triggering 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 they are not produced for the request.

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": []
      }
    }
  }
}