# CancelOutgoingPayment

## Permission Scope

outgoingPayment

## Overview

cancelOutgoingPayment cancels a DRAFT payment before it has accounting or settlement effect. The payment and its settlement rows are retained as immutable history.

## Business Rules

- Input includes payment `id`
- Only a DRAFT payment can be cancelled
- Cancellation changes status to CANCELLED and records `cancelledAt`
- Cancellation does not create or post a journal entry
- Settlement rows are retained and become immutable with the parent payment

## Process Flow

```mermaid
flowchart TD
    A[Receive cancel request] --> B{Payment exists?}
    B -->|No| X[Return not found]
    B -->|Yes| C{Status is DRAFT?}
    C -->|No| Y[Return invalid status]
    C -->|Yes| D[Set CANCELLED and cancelledAt]
    D --> E[Return cancelled payment]
```

## External Dependencies

- None

## Error Scenarios

- **OUTGOING_PAYMENT_NOT_FOUND**: Payment does not exist
- **OUTGOING_PAYMENT_INVALID_STATUS**: Payment status does not allow this operation

## Test Cases

- cancels a DRAFT payment and retains its settlements
- returns error when payment does not exist
- returns error when payment is POSTED or CANCELLED