# UpdateOutgoingPayment

## Permission Scope

outgoingPayment

## Overview

updateOutgoingPayment edits a DRAFT payment header and applies incremental settlement changes. Header identity fields remain fixed. Settlement rows omitted from the request remain unchanged.

## Business Rules

- Input includes payment `id`, an optional header patch, optional `addSettlements`, optional `updateSettlements`, and optional `removeSettlementIds`
- The header patch may change only `paymentDate`, `totalAmount`, and `paymentAccountId`
- The payment must be DRAFT
- Updated total and every added or updated settlement amount must be positive
- The resulting payment account, whether changed or unchanged, must exist, be ACTIVE, and belong to the payment company
- An updated or removed settlement must belong to this payment
- The resulting settlement set cannot contain duplicate due schedule lines
- Each settlement in the resulting set must reference a due schedule line owned by a POSTED INVOICE or CREDIT_MEMO for the payment's company, supplier, and currency
- Settlement amounts remain positive magnitudes; the target document's `documentType` supplies the AP balance direction
- Add, update, and remove operations in one request must not conflict with each other
- Due-schedule eligibility is revalidated at posting; equality between settlement sum and payment total and remaining-balance enforcement are enforced at posting

## Process Flow

```mermaid
flowchart TD
    A[Receive update request] --> B{Payment exists and is DRAFT?}
    B -->|No| X[Return payment error]
    B -->|Yes| C{Header patch valid?}
    C -->|No| Y[Return validation or account error]
    C -->|Yes| D{Settlement mutations reference owned rows and do not conflict?}
    D -->|No| Z[Return settlement error]
    D -->|Yes| E[Apply header patch]
    E --> F[Add update and remove requested settlements]
    F --> G[Return updated payment]
```

## External Dependencies

- [coa-management::GetAccount](../../../coa-management/docs/query/GetAccount.md) - Revalidates the resulting payment account

## Error Scenarios

- **OUTGOING_PAYMENT_NOT_FOUND**: Payment does not exist
- **OUTGOING_PAYMENT_INVALID_STATUS**: Payment status does not allow this operation
- **OUTGOING_PAYMENT_INVALID_AMOUNT**: Payment total or settlement amount is not positive
- **OUTGOING_PAYMENT_SETTLEMENT_NOT_FOUND**: Updated or removed settlement does not belong to the payment
- **OUTGOING_PAYMENT_SETTLEMENT_INVALID**: Settlement set is empty where required, duplicated, or internally inconsistent
- **OUTGOING_PAYMENT_TARGET_INELIGIBLE**: Settlement target is not an eligible AP due schedule
- **ACCOUNT_NOT_FOUND**: Referenced GL account does not exist
- **ACCOUNT_INACTIVE**: Referenced GL account is not ACTIVE
- **ACCOUNT_COMPANY_MISMATCH**: Referenced account belongs to a different company

## Test Cases

- updates the editable header fields of a DRAFT payment
- incrementally adds, updates, and removes settlements while preserving omitted rows
- returns error when payment does not exist or is not DRAFT
- returns error for a non-positive total or settlement amount
- returns error when the resulting payment account is missing, inactive, or company-incompatible
- returns error when updating or removing a settlement owned by another payment
- returns error for conflicting mutations or duplicate due-schedule allocations
- returns error when an added settlement target is ineligible
- allows resulting settlements to target an AP-increasing INVOICE correction
- allows resulting settlements to target a posted CREDIT_MEMO