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

# SubpoenaPaymentService

Drives the batch financial-transaction lifecycle for approved subpoenas — validating recipient addresses, generating check transactions through `IFinancialTransactionService`, advancing subpoena status, and reversing payments — while resolving the current issue date from `PaymentTransactionTypeCode`, the payment approver's mail ID via `ILegalQueryProvider`/`Employee` lookups, and posting recovery data back to Claim Center through `IFinancialDataApiClient`/`IClaimDataApiClient`. It rejects and emails notice for subpoenas whose recipient addresses fail `IProviderInformationService` validation instead of generating a check for them.

## Purpose
- Bulk-advances subpoena status between two status codes for subpoenas matching the current issue date, inside a single transaction.
- Generates check financial transactions for approved medical-records/claims subpoenas with valid addresses (advancing them to ready-to-pay), rejects those with invalid addresses back to in-progress with an email notice, and advances non-medical/claims subpoena types straight to ready-to-pay — reporting counts of each outcome via `FinancialTransactionControlStats`, and committing partial progress even on failure so restarts don't duplicate checks.
- Reverses a previously issued subpoena payment for a recipient: rejects already-returned recipients, submits an equivalent recovery-financial-data record to Claim Center when a matching legal payment exists, and zeroes the recipient's paid amount and stamps a returned date.

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

## Public members
| Member | Signature | Purpose |
| --- | --- | --- |
| SubpoenaPaymentService (constructor) | `public SubpoenaPaymentService(IUnitOfWork unitOfWork, IUserProfileService userProfileService, ProviderContract.IProviderInformationService providerInformationService, ILegalQueryProvider legalQueryProvider, UtilDocument.IDocumentService documentService, IEnvironmentService environmentService, ILogService logService, IFinancialTransactionService financialTransactionService, string developerEmails, IFinancialDataApiClient financialDataApiClient, IClaimDataApiClient claimDataApiClient)` | Wires the unit of work, current-user profile (captured as an uppercased user ID), provider address lookups, legal query provider, document/email service, environment configuration, logging, financial-transaction generation, a developer-email distribution list, and the Guidewire financial and claim data API clients; null-checks all parameters. |
| IssueDate | `public DateTime IssueDate { get; }` | The subpoena payment run's issue date, lazily resolved once per instance from the `Subpoena` payment-transaction type's next issue date (defaulting to today if none is configured). |
| UpdateSubpoenaStatus | `public long UpdateSubpoenaStatus(string fromCode, string toCode)` | Within a single transaction, moves every subpoena at `fromCode` status whose issue date matches `IssueDate` to `toCode`, stamping the update date/user, and returns the number of subpoenas updated. |
| GenerateCheckTransactionsAsync | `public async Task<FinancialTransactionControlStats> GenerateCheckTransactionsAsync(ILogWriter controlReport)` | Processes every approved subpoena due for the current issue date one at a time (each in its own transaction): for medical-records/claims subpoenas, generates check transactions via `IFinancialTransactionService.CreateSubpoenaCheckTransactions` and advances to ready-to-pay if the recipient address is valid, or rejects to in-progress with an email if not; other subpoena types advance directly to ready-to-pay. Writes progress and, on exception, a diagnostic summary to `controlReport`, commits work completed so far, and rethrows. |
| ReturnSubpoenaPaymentAsync | `public async Task<long> ReturnSubpoenaPaymentAsync(long recipientId, IMessageContainer messageContainer)` | Reverses payment for a recipient: rolls back and logs an error if the recipient is not found or was already returned; otherwise looks up the matching Claim Center legal payment by invoice number, posts a `RecoveryFinancialData` reversal via `IFinancialDataApiClient.CreateRecoveryAsync` if one exists (logging and returning `0` on failure), then zeroes the recipient's paid amount, stamps today's returned date, commits, and returns the recipient ID. |

## Behavioral notes
- A static constructor calls `SubpoenaMappingHelper.MapSubpoenaService()`, registering the AutoMapper mappings this service (and related services) rely on, once per process.
- `GenerateCheckTransactionsAsync` opens and commits a fresh `IUnitOfWork` transaction per subpoena (rather than one transaction for the whole batch) specifically to force NHibernate to re-initialize lazy proxies and avoid `LazyInitializationException`, and commits progress even when an exception is thrown partway through so restarted runs do not regenerate already-issued checks.
- `IsAddressCorrectionNeeded` treats an `InvalidPaymentAddressException` from `IProviderInformationService.GetProviderAddressForSubpoenas` as the signal to reject the subpoena rather than pay it.
- `GetApproverMailId` redirects the approver lookup to the attorney's manager when the approving employee ID is the sentinel value `"OUTSIDECNCL"`.*
- `ReturnSubpoenaPaymentAsync` hardcodes `Exposure = "GeneralDamage"` in the recovery payload because Claim Center requires a value even though this exposure detail is not tracked in this system.

## Constraints and usage notes
- All constructor parameters, including the injected `developerEmails` string, are null-checked via `Enforce.ArgumentNotNull`; a `null` value for any of them throws immediately.
- `ReturnSubpoenaPaymentAsync` and `IMessageContainer`-accepting methods throw via `Enforce.ArgumentNotNull` if `messageContainer` is `null`.
- `GenerateCheckTransactionsAsync` rethrows any caught exception (`throw ex`) after logging partial-progress statistics, resetting the original stack trace.*

> **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/Legal/Subpoenas/SubpoenaPaymentService.cs`