---
title: Retrieve ClaimCenter payment history
summary: Calls the ClaimCenter API to retrieve payment history for a provider tax ID, with configurable inclusion of zero-pay and any-status payments.
status: draft
owner: SAIF
last_reviewed: 2026-07-30
library: SAIF.Business.Provider
reference_type: package
operation_id: OP-PRV-13
trigger: Caller invokes clsPaymentApi.GetPayments with a tax ID
---

# Retrieve ClaimCenter payment history

`clsPaymentApi` is a read-only REST client wrapper — it touches no database table directly — that queries ClaimCenter's `payments` endpoint for the payment history associated with a tax ID, and is reused internally by `clsProviderTaxID.HasPayment` to test whether a TIN has associated payment activity.

| Field | Value |
| --- | --- |
| **Operation ID** | OP-PRV-13 |
| **Trigger** | Caller invokes `clsPaymentApi.GetPayments(inDataPortalInfo, inTaxId, [inMaxNumberResults], [inIncludeZeroPays], [inIncludePaymentsInAnyStatus], [inPaymentIdOnly])` |
| **Inputs** | `TaxId`, `MaxNumberResults` (default `1`), `IncludeZeroPays` (default `True`), `IncludePaymentsInAnyStatus` (default `True`), `PaymentIdOnly` (default `True`) |
| **Outputs** | `clsPaymentApi.Payments` (a `PaymentList` DTO); `HasPayments` boolean |
| **Primary components** | `clsPaymentApi.GetPayments`, `clsPaymentApi.BeforeRetrieve`, `clsPaymentApi.AfterRetrieve` |
| **Entry point** | `Business\SAIF.Business.Provider\Api\clsPaymentApi.vb` |

## Steps

1. **Caller requests payment history.** `GetPayments(...)` constructs a `Criteria` carrying the tax ID and the four query flags.
2. **Configure the request.** The criteria targets client key `ClaimCenterApi`, controller `payments`, with route template `payments?taxId={0}&maxNumberResults={1}&includeZeroPays={2}&includePaymentsInAnyStatus={3}&paymentIdOnly={4}`.
3. **Build the route.** `BeforeRetrieve()` formats the route template with the supplied values, lowercasing the boolean flags via `ToLowerInvariant()` so they serialize as `true`/`false` in the query string.
4. **Execute the call.** `DataApiAccessLayer.RetrieveObject(...)` issues an HTTP GET against the configured ClaimCenter API route.
5. **Parse the response.** `AfterRetrieve()` calls `apiResult.GetResults(Of PaymentList)`; if the result is a nonempty array, the first item is stored in `Payments`.
6. **Expose a convenience flag.** `HasPayments` returns `True` only when `Payments` is not `Nothing` and `Payments.payments.Count > 0` — a pure in-memory check on the already-retrieved list.
7. **Reuse by TIN validation.** `clsProviderTaxID.HasPayment` calls `GetPayments` twice with the same tax ID formatted two ways — `00-0000000` (EIN) and `000-00-0000` (SSN) — to account for ClaimCenter potentially indexing the TIN under either format; no business rule in `clsProviderTaxID` currently consumes this result to block a save, so it functions as an on-demand check available to callers.*

## Process flow

```mermaid
flowchart TD
	Start([Caller calls GetPayments]) --> BuildRoute[Format payments route<br>with taxId and query flags]
	BuildRoute --> Call[HTTP GET via ClaimCenterApi client]
	Call --> Parse{Response contains payments?}
	Parse -->|Yes| Store[Store first PaymentList item]
	Parse -->|No/empty| Empty([Payments remains unset])
	Store --> Done([Caller reads Payments / HasPayments])
	Empty --> Done
```

## Failure and edge-case behavior

- This operation performs no database access; all data originates from the external ClaimCenter API, so its availability and correctness depend entirely on that service.*
- `HasPayments` returns `False` both when no payments exist and when the API call itself failed to populate `Payments`, so callers cannot distinguish "no payments" from "retrieval failed" using this flag alone.*
- `clsProviderTaxID.HasPayment`'s dual-format lookup is a workaround for TIN formatting ambiguity in ClaimCenter rather than a guaranteed single source of truth.*

## 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.Provider\Api\clsPaymentApi.vb`
- `Business\SAIF.Business.Provider\clsProviderTaxID.vb`