---
title: FinancialTransactionService
summary: API reference for FinancialTransactionService.
status: draft
owner: SAIF Doc Gen
last_reviewed: 2026-09-24
library: SAIF.Services
reference_type: package
---

# FinancialTransactionService

Implements `IFinancialTransactionService`, issuing check payments for legal bills and subpoena recipients by calling out to Guidewire's Financial Data API through `IFinancialDataApiClient`. It resolves payee mailing addresses via `IProviderInformationService` and stamps recipient payment state with the acting user from `IUserProfileService`, throwing `InvalidFinancialTransactionException` or `InvalidPaymentAddressException` when required inputs (a legal bill/subpoena or a valid provider address) are missing.

## Purpose
- Creates a check financial transaction for a legal bill's billing provider via the Guidewire Financial Data API, mapping bill services into Guidewire `Payment` line items.
- Creates check financial transactions for each unpaid subpoena recipient with a positive paid amount, marking each recipient paid after a successful Guidewire call.
- Creates a recovery financial transaction against a claim via the Guidewire Financial Data API.
- Resolves the delivery method to send with a check based on a legacy special-handling code, defaulting to standard mail when no mapping exists.
- Selects a payee mailing address by preferred address-type precedence (pay, correspondence, then physical for legal bills; correspondence, physical, then pay for subpoenas) and validates that every subpoena recipient has a resolvable provider address before issuing any payments.

## Context
- Namespace: `SAIF.Services.Claims.Payments`
- Assembly/package: `SAIF.Services` (packaged inside the `SAIF.SAIFCode.Core` NuGet package)

## Public members
| Member | Signature | Purpose |
| --- | --- | --- |
| FinancialTransactionService | `public FinancialTransactionService(IProviderInformationService providerInformationService, IUserProfileService userProfileService, IFinancialDataApiClient gwFinancialDataApiClient, IUnitOfWork unitOfWork)` | Wires the provider-information, user-profile, Guidewire Financial Data API client, and unit-of-work collaborators, and registers AutoMapper self-maps for `FinancialTransaction`/`FinancialTransactionStateless` plus claim code-table mappings via `ClaimsMappingHelper`. |
| CreateLegalCheckTransaction | `public async Task<string> CreateLegalCheckTransaction(LegalBill legalBill, DateTime issueDate, string approverId)` | Builds a Guidewire check-financial-data payload from a legal bill's provider, address, special-handling code, and bill services, submits it via `IFinancialDataApiClient.CreateCheckAsync`, and returns the resulting transaction identifier; throws `InvalidFinancialTransactionException` if `legalBill` is null or `InvalidPaymentAddressException` if no valid provider address is found. |
| CreateSubpoenaCheckTransactions | `public async Task<IList<String>> CreateSubpoenaCheckTransactions(Subpoena subpoena, DateTime issueDate, string approverId, string spendCategory)` | For each unpaid, positively-paid subpoena recipient, submits a Guidewire check-financial-data payload and marks the recipient paid on success; returns the list of resulting transaction identifiers, or an empty list if any recipient's provider address cannot be resolved; throws `InvalidFinancialTransactionException` if `subpoena` is null. |
| CreateRecoveryAsync | `public async Task<string> CreateRecoveryAsync(long claimId, FinancialDataApi.RecoveryFinancialData recoveryFinancialData)` | Submits a recovery financial transaction for the given claim via `IFinancialDataApiClient.CreateRecoveryAsync` and returns the resulting transaction identifier. |

## Behavioral notes
- All payment creation ultimately calls out to an external system (Guidewire's Financial Data API) through `IFinancialDataApiClient`; failures from that client are not caught here and propagate to the caller.
- `CreateLegalCheckTransaction` and `CreateSubpoenaCheckTransactions` both validate their required input object is non-null up front, throwing `InvalidFinancialTransactionException` before any further processing.
- `AllProviderAddressesFound` pre-validates every subpoena recipient's provider/registered-agent address by catching `InvalidPaymentAddressException` from `IProviderInformationService`, so a single unresolvable address short-circuits the entire subpoena batch before any checks are issued.
- `SetRecipientPaid` mutates the in-memory `Recipient` (`IsRecipientPaid`, `UpdateUser`, `UpdateDate`) after each successful subpoena check is created; persistence of that change is not performed by this method.*

> **Note:** Statements marked with * were inferred from code structure, naming conventions, or
> contextual evidence where direct confirmation was not available in source artifacts. Statements
> marked with ** could not be confirmed; treat as unknown until verified.

## Sources
- Services/SAIF.Services/Claims/Payments/FinancialTransactionService.cs