Skip to main content
Financial evidence and lifecycle changes use explicit operations instead of rewriting Matter history.

Payment observations

Use a Payment observation when the partner has evidence of an external payment, refund, or reversal.
The path externalPaymentId is the partner’s stable opaque identifier for one observation. Do not encode names, account numbers, bank references, or other raw reconciliation data in it.

Record a payment

resultingOutstandingAmount is required. CasePath IQ calculates the post-apply balance under the Matter lock and rejects a stale or incorrect assertion with 409 balance_mismatch. The observation and balance update commit together or not at all. A first accepted PUT returns 201 Created. The same ID and identical normalized content returns 200 without duplicate evidence. Different content under the same ID returns 409 payment_observation_conflict. GET returns the accepted partner-facing observation. Payments never create Matters, and closed Matters still accept later evidence for reconciliation.

Correct payment evidence

Accepted observations are immutable.
1

Reverse the incorrect observation

Create a new reversal observation that names the original externalPaymentId and exactly undoes its signed balance effect.
2

Record the corrected evidence

Create a new payment or refund observation with its own stable external payment ID.
Use Matter PUT—not a Payment observation—to correct a mistaken opening balance or currency, and only before CasePath IQ records recovery activity.

Lifecycle operations

Use lifecycle commands to pause, clear a pause, close, or reopen a Matter.
operation is one of pause, clear-pause, close, or reopen.

Submit a command

1

Read the current Matter

GET the Matter and copy its current server-issued lifecycleStateId.
2

Send the predecessor

Send this body to the pause operation. CasePath IQ accepts the transition only when the predecessor identifies the current lifecycle head, unless the request is an exact lost-response retry of the still-current occurrence.
3

Store the new head

An accepted command returns a new lifecycleOccurrenceId as the Matter’s current lifecycleStateId. Use it as the predecessor of the next command.

Transition rules

Pause reasons are client_instruction, dispute, payment_arrangement, legal_review, and other. Close reasons are satisfied, withdrawn, written_off, and transferred. clear-pause and reopen target the current hold created by the same Source integration. Reopen also asserts the current positive outstandingAmount and currency.

Business date and immediate effect

effectiveOn records the partner’s claimed business date. It does not schedule a transition. Past, current, and future real dates apply the lifecycle change and safety fence immediately when accepted. The date must be on or after 2000-01-01 and no more than 31 days after today (UTC); otherwise the request returns 400 effective_date_out_of_range. The same window applies to Payment observations. Clearing a pause or reopening never automatically resumes legal progression or outbound communication. CasePath IQ re-evaluates readiness and staff controls.

Retry a lifecycle command

If a response is lost, retry the exact same operation, predecessor, and normalized body. CasePath IQ returns the accepted occurrence with 200 while that occurrence remains the current lifecycle head. Do not change the command blindly after a 409 stale_lifecycle_precondition or 409 stale_lifecycle_retry. GET the Matter, reconcile its current lifecycle state, and decide the next intended transition.

Next