---
title: Award benefit payment management
summary: Retrieves, updates, and deletes the benefit payment rows attached to a SAIF award, including the filtered collection used to hydrate federal awards.
status: draft
owner: SAIF Doc Gen
last_reviewed: 2026-07-30
library: SAIF.Business.Claim
reference_type: package
operation_id: OP-BC-03
trigger: A caller requests an award benefit payment or a collection of payments for an award, or saves changes to one
---

# Award benefit payment management

Benefit payments are the individual disbursement rows that hang off a SAIF award. This operation covers the single-payment object and its collection: reading an approved payment for a claim, reading all payments of selected benefit types for an award number, editing amounts and dates, and deleting a payment. The collection is the hydration source used when federal awards are loaded, so its default benefit-type filter determines which payments a federal award appears to carry.

| Field | Value |
| --- | --- |
| **Operation ID** | OP-BC-03 |
| **Trigger** | `clsAwardBenefitPayment.GetAwardBenefitPayment`, `GetAwardBenefitPaymentBySeq`, or `NewAwardBenefitPayment`; `clsAwardBenefitPaymentCollection.GetAwardBenefitPaymentCollection`; followed by `Save()` for changes |
| **Inputs** | `ClaimID`; `AwardNum`; `BenefitPaymentSeqNum`; an optional list of benefit type codes for the collection; payment fields such as issue date, amounts, and status codes; `UpdateNum` |
| **Outputs** | A populated payment object or collection; updated or deleted `CL_BENEFIT_PAYMENT` rows; error messages `UpdateError` and `DeleteError` |
| **Primary components** | `clsAwardBenefitPayment` (`BeforeRetrieve`, `BeforeUpdate`, `AfterUpdate`, `BeforeDelete`, `AfterDelete`), `clsAwardBenefitPaymentCollection` (`BeforeRetrieve`, `AfterRetrieve`, `Save`) |
| **Entry point** | `Business\SAIF.Business.Claim\clsAwardBenefitPayment.vb` |

## Steps

1. **Retrieve one approved payment for a claim.** `GetAwardBenefitPayment` runs the single-row select against the benefit payment table filtered by claim identifier and a benefit status code of `2`, meaning the payment is approved ([SQL-015](../sql/SQL-015-saif-business-claim.md), [CL_BENEFIT_PAYMENT](../database-tables.md#cl_benefit_payment)).
   - `GetAwardBenefitPaymentBySeq` uses the same statement family keyed on the claim identifier and benefit payment sequence number instead.*
2. **Retrieve a collection for an award.** `clsAwardBenefitPaymentCollection.BeforeRetrieve` starts from a select over the benefit payment table keyed on the SAIF award number whose predicate list is deliberately left incomplete, then appends a benefit type code list built from the supplied array ([SQL-016](../sql/SQL-016-saif-business-claim.md), [CL_BENEFIT_PAYMENT](../database-tables.md#cl_benefit_payment)).
   - Sub-step: each supplied benefit type code is added as its own bind parameter and appended to an `IN` list, so the statement text varies with the number of codes requested.
   - Sub-step: when the caller supplies no codes, the collection falls back to the federal benefit types `4`, `5`, and `6` ([BR-012](../business-rules.md#br-012-award-benefit-payment-collections-default-to-federal-benefit-types)).
3. **Hydrate the collection items.** `AfterRetrieve` reads the data reader row by row, building a `clsAwardBenefitPayment` for each row through the item-level load entry point and adding it to the collection.
4. **Edit and save.** The collection's `Save()` applies the pending edit level and then delegates to the framework collection save, which walks each dirty item through its own update or delete path.
5. **Update a payment.** `BeforeUpdate` writes the payment's mutable columns together with `SYSDATE`, an incremented update number, and the acting user, keyed on the SAIF award number and the prior update number so a concurrent change is detected ([SQL-030](../sql/SQL-030-saif-business-claim.md), [CL_BENEFIT_PAYMENT](../database-tables.md#cl_benefit_payment)).
   - If exactly one row is not affected: add `UpdateError` carrying the framework database contention message ([BR-008](../business-rules.md#br-008-updatedelete-row-count-must-equal-1)).
6. **Delete a payment.** `BeforeDelete` removes the row by claim identifier and benefit payment sequence number ([SQL-041](../sql/SQL-041-saif-business-claim.md), [CL_BENEFIT_PAYMENT](../database-tables.md#cl_benefit_payment)).
   - If the affected row count is `0`: add `DeleteError` carrying the framework database contention message ([BR-008](../business-rules.md#br-008-updatedelete-row-count-must-equal-1)).
7. **Create and insert are refused.** Both the item and the collection Criteria raise an application exception from their create and insert SQL properties, and the collection additionally refuses delete and update; payments are originated elsewhere and only maintained here.

## Process flow

The following diagram visualizes the retrieve and save paths.

```mermaid
flowchart TD
	Start([Caller requests a payment<br>or a payment collection]) --> Which{Single item<br>or collection?}
	Which -->|Single| One[Select the approved payment<br>for the claim]
	Which -->|Collection| Codes{Benefit type codes<br>supplied?}
	Codes -->|No| Defaults[Use federal defaults 4, 5, 6]
	Codes -->|Yes| Build[Append one bind parameter<br>per supplied code]
	Defaults --> Build
	Build --> Many[Select payments for the award<br>with the code list]
	Many --> Hydrate[Build one payment object<br>per reader row]
	One --> Edit
	Hydrate --> Edit[Caller edits payment fields]
	Edit --> Save{Save requested?}
	Save -->|Update| Upd[Update keyed on award number<br>and prior update number]
	Save -->|Delete| Del[Delete keyed on claim and<br>payment sequence number]
	Upd --> URows{Rows affected = 1?}
	Del --> DRows{Rows affected = 0?}
	URows -->|No| UErr([Add UpdateError])
	URows -->|Yes| Done([Payment persisted])
	DRows -->|Yes| DErr([Add DeleteError])
	DRows -->|No| Done
```

## Failure and edge-case behavior

- The collection retrieve statement is only valid once the benefit type clause has been appended; invoking the criteria's retrieve SQL without going through `BeforeRetrieve` produces a syntactically incomplete statement.
- A caller that supplies an empty benefit type list silently receives federal payments only, which is easy to mistake for "no payments exist" on a state claim.
- The single-item retrieve is filtered to approved payments, so payments in any other status are invisible through that entry point even though they exist for the claim.
- The update binds the issue date parameter twice; the redundant bind is harmless with named parameters but signals that the parameter list and the statement text have drifted.*
- The item `Save()` override returns `True` unconditionally, so callers must inspect the error collection rather than the return value.*
- Neither the item nor the collection registers any business rules, so field-level validity is entirely the caller's responsibility.
- Delete failure is detected only when zero rows are affected; a statement that somehow affected more than one row would be reported as success.

## Related documentation

- [Operations and processes](../operations-processes.md)
- [Business rules](../business-rules.md)
- [SQL catalog](../sql/index.md)
- [Database tables](../database-tables.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.Claim\clsAwardBenefitPayment.vb`
- `Business\SAIF.Business.Claim\clsAwardBenefitPaymentCollection.vb`