---
title: Claim reserves and payments retrieval
summary: Retrieves claim financial reserves (by cost category) and payment history from the claim financial data API.
status: draft
owner: SAIF Doc Gen
last_reviewed: 2026-07-30
library: SAIF.Business.View.Claim
reference_type: package
operation_id: OP-VC-02
trigger: Caller reads `clsClaimData.Reserves`/`AllReserves`/`PaymentsData`, or calls `clsClaimReservesCollection` retrieval methods directly
---

# Claim reserves and payments retrieval

This operation retrieves a claim's financial position — reserve amounts by cost category and payment/line-item history — from the claim financial data API (`CCClaimDataApi/Financial`). It is the current, API-backed financial data path and is distinct from the older stored-procedure-backed [financial transaction retrieval](financial-transaction-retrieval.md) operation, which reads individual payment transaction rows rather than aggregated reserve/payment totals.

| Field | Value |
| --- | --- |
| **Operation ID** | OP-VC-02 |
| **Trigger** | Caller reads `clsClaimData.Reserves`, `clsClaimData.AllReserves`, or `clsClaimData.PaymentsData`, or calls `clsClaimReservesCollection.GetClaimReserves`/`GetAllClaimReserves`/`GetClaimCosts` |
| **Inputs** | Claim ID; optional valuation date; optional `CombineDeathAndBurialReserve` flag |
| **Outputs** | `clsClaimReservesCollection` of `clsClaimReserves` (one per cost category), with category totals (`TotalIncurred`, `TotalPaid`, `TotalReserves`) and category-specific accessors (`MedicalReserves`, `PPDReserves`, `TDReserves`, `FatalReserves`, etc.); `PaymentsData` (last payment date, total paid, payment list with line items) |
| **Primary components** | `clsClaimReservesCollection.BeforeRetrieve`/`AfterRetrieve`, `clsClaimReserves.Load`, `clsClaimData.RetrievePaymentsData` |
| **Entry point** | `Business\SAIF.Business.View.Claim\clsClaimReservesCollection.vb`, `Business\SAIF.Business.View.Claim\clsClaimReserves.vb` |

## Steps

1. **Select the financial retrieval route.** `clsClaimReservesCollection.BeforeRetrieve` sets the API route to the claim-ID-only financials endpoint or the claim-ID-plus-valuation-date endpoint, depending on whether a valuation date was supplied.
   - Similarly, `clsClaimData.RetrievePaymentsData` builds its own request against the route pattern `v1/{controller}/Claims/{0}/Financials` using the `CCClaimDataApi`/`GeneralClaimData` client.
2. **Call the financial data API.** The request executes through `DataApiAccessLayer.ProcessRequest(Of FinancialDataResult)`, returning a `FinancialData` payload containing `ClaimReserves` (a `ReserveData`) and `ClaimPayments` (a `PaymentsData`).
3. **Map reserves.** `AfterRetrieve` reads `ResponseData(Of FinancialData)`, then constructs one `clsClaimReserves` per `Reserve` row in `ClaimReserves.Reserves`, using `clsClaimReserves.Load(reserve, claimCostsDate, totalLossDays)` to map category, incurred/paid/reserve amounts, and time-loss days.
   - `IsMedicalReserve` is derived by comparing the mapped category code to the medical cost-category constant.
4. **Exclude non-chargeable expense categories.** Reserve rows whose category is a legal or other non-chargeable expense are removed from the collection before totals are computed ([BR-005](../business-rules.md#br-005-claim-reserve-totals-exclude-non-chargeable-expense-categories)).
5. **Combine death and burial reserves, if requested.** When the caller sets `CombineDeathAndBurialReserve`, burial amounts are folded into the death-benefit category total instead of being reported separately ([BR-006](../business-rules.md#br-006-death-and-burial-reserves-are-combined-only-when-the-caller-opts-in)).
6. **Aggregate loss-days by category.** Payment loss-day figures are aggregated and attributed to the matching reserve category so each `clsClaimReserves` row also exposes `TLDays`.
7. **Map payments.** `clsClaimData.RetrievePaymentsData` reads `financialData?.ClaimPayments` from the API result and exposes it as `PaymentsData`, including `LastPaymentDate`, `TotalPaid`, and the `Payments` list (each with `LineItems`).
8. **Expose category accessors and totals.** The collection exposes convenience accessors per category (`TDReserves`, `MedicalReserves`, `ChargeExpReserves`, `PPDReserves`, `PTDReserves`, `FatalReserves`, `VocServReserves`, `VocTDReserves`, `NoneReserves`, `OtherReserves`) plus `TotalIncurred`, `TotalPaid`, and `TotalReserves` computed across the (filtered, possibly combined) reserve rows.

## Process flow

The following diagram visualizes this operation's control flow.

```mermaid
flowchart TD
	Start([Caller reads Reserves,<br>AllReserves, or PaymentsData]) --> Route{Valuation date supplied?}
	Route -->|Yes| RouteDate[Route: claim id + valuation date]
	Route -->|No| RouteId[Route: claim id only]
	RouteDate --> Call[Call Financials API]
	RouteId --> Call
	Call --> MapReserves[Map Reserve rows to clsClaimReserves]
	MapReserves --> Exclude[Exclude non-chargeable expense categories]
	Exclude --> Combine{Combine death and burial requested?}
	Combine -->|Yes| Merge[Merge burial into death-benefit total]
	Combine -->|No| Keep[Keep categories separate]
	Merge --> Totals[Compute category totals]
	Keep --> Totals
	Call --> MapPayments[Map ClaimPayments to PaymentsData]
	Totals --> Done([Return reserve collection and payments data])
	MapPayments --> Done
```

## Failure and edge-case behavior

- Reserve category totals silently exclude legal and other non-chargeable expense rows; callers expecting a full expense ledger must query those categories separately if a source becomes available.
- The combine-death-and-burial behavior depends entirely on the caller passing the flag; omitting it yields separate category totals even for claims where the two would otherwise be treated as one benefit.
- `PaymentsData` and `ClaimReserves` are both read from a single `FinancialData` API response, so an API failure affects both reserves and payments together rather than independently.*

## Related documentation

- [Operations and processes](../operations-processes.md)
- [Business rules](../business-rules.md)

> **Note:** Statements marked with `*` were inferred from code structure, naming
> conventions, or contextual evidence where direct confirmation was not available
> in source artifacts.

## Sources

- `Business\SAIF.Business.View.Claim\clsClaimReserves.vb`
- `Business\SAIF.Business.View.Claim\clsClaimReservesCollection.vb`
- `Business\SAIF.Business.View.Claim\clsClaimData.vb`
- `Business\SAIF.Business.View.Claim\CCClaimDataApi\Financial\FinancialData.vb`
- `Business\SAIF.Business.View.Claim\CCClaimDataApi\Financial\FinancialDataResult.vb`
- `Business\SAIF.Business.View.Claim\CCClaimDataApi\Financial\ReserveData.vb`
- `Business\SAIF.Business.View.Claim\CCClaimDataApi\Financial\Reserve.vb`
- `Business\SAIF.Business.View.Claim\CCClaimDataApi\Financial\PaymentsData.vb`
- `Business\SAIF.Business.View.Claim\CCClaimDataApi\Financial\Payment.vb`
- `Business\SAIF.Business.View.Claim\CCClaimDataApi\Financial\LineItem.vb`