> ## Documentation Index
> Fetch the complete documentation index at: https://docs.casepathiq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Payments, corrections, and lifecycle

> Record immutable payment evidence, correct opening balances, and change Matter lifecycle state.

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.

```http theme={null}
PUT /v1/clients/{clientCode}/matters/by-client-reference/{clientReferenceId}/payment-observations/{externalPaymentId}
GET /v1/clients/{clientCode}/matters/by-client-reference/{clientReferenceId}/payment-observations/{externalPaymentId}
```

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

```json theme={null}
{
  "type": "payment",
  "amount": "200.00",
  "currency": "EUR",
  "effectiveOn": "2026-09-01",
  "channel": "direct_to_creditor",
  "reference": "BP-5521",
  "resultingOutstandingAmount": "1050.00"
}
```

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

| Type | Balance effect | Additional rule |
| - | - | - |
| `payment` | Subtract `amount` | Requires `channel`; cannot underflow below `0.00` |
| `refund` | Add `amount` | Requires `channel`; cannot exceed the Money limit |
| `reversal` | Exactly undo one prior payment or refund | Requires `reversesExternalPaymentId`; omits `channel` |

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.

```http theme={null}
POST /v1/clients/{clientCode}/matters/by-client-reference/{clientReferenceId}/lifecycle/{operation}
```

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

```json theme={null}
{
  "predecessorLifecycleId": "lcy_01JEXAMPLE",
  "reason": "client_instruction",
  "effectiveOn": "2026-09-01"
}
```

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

| Current hold | `pause` | `clear-pause` | `close` | `reopen` |
| - | - | - | - | - |
| Active baseline | Paused | `409` | Closed | `409` |
| Active pause | `409` | Active baseline | Closed; pause superseded | `409` |
| Active close | `409` | `409` | `409` | Active baseline |

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

* [Understand lifecycle ownership](https://docs.casepathiq.com/concepts.md#lifecycle-state)
* [Synchronize resulting status changes](https://docs.casepathiq.com/synchronization.md)
* [Handle conflicts and safe retries](https://docs.casepathiq.com/errors-and-retries.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.