Skip to content

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

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.*

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