# CreateOutgoingPayment

## Permission Scope

outgoingPayment

## Overview

createOutgoingPayment creates an editable DRAFT OutgoingPayment for one company, supplier, currency, payment account, date, and positive total amount. The request may include initial settlement allocations, but an empty settlement set is allowed until posting.

## Business Rules

- Input includes `companyId`, `supplierAccountId`, `currencyId`, `paymentAccountId`, `paymentDate`, `totalAmount`, and optional `settlements`
- `totalAmount` and every supplied `settledAmount` must be positive
- The company must be ACTIVE
- The SupplierAccount must belong to the company and be available for transactions
- The currency must exist
- The payment account must exist, be ACTIVE, and belong to the company
- Initial settlements cannot contain the same due schedule line more than once
- Each initial settlement must reference a due schedule line owned by a POSTED INVOICE or CREDIT_MEMO for the same company, supplier, and currency
- Settlement amounts remain positive magnitudes; the target document's `documentType` supplies the AP balance direction
- Due-schedule eligibility is revalidated at posting; settlement-total equality and remaining-balance enforcement are deferred until posting so a DRAFT may be incomplete
- The payment is assigned DRAFT status

## Process Flow

```mermaid
flowchart TD
    A[Receive create request] --> B{Header amounts valid?}
    B -->|No| X[Return validation error]
    B -->|Yes| C{Company supplier currency and account valid?}
    C -->|No| Y[Return master-data error]
    C -->|Yes| D{Initial settlements valid and unique?}
    D -->|No| Z[Return settlement error]
    D -->|Yes| E[Create DRAFT payment]
    E --> F[Create optional settlement rows]
    F --> G[Return payment]
```

## External Dependencies

- [organization::GetCompany](../../../organization/docs/query/GetCompany.md) - Validates company existence and status
- [business-partner::GetSupplierAccount](../../../business-partner/docs/query/GetSupplierAccount.md) - Validates supplier account company and transaction availability
- [primitives::GetCurrency](../../../primitives/docs/query/GetCurrency.md) - Validates currency existence
- [coa-management::GetAccount](../../../coa-management/docs/query/GetAccount.md) - Validates the payment account

## Error Scenarios

- **COMPANY_NOT_FOUND**: Referenced company does not exist
- **COMPANY_INACTIVE**: Referenced company is not ACTIVE
- **AP_SUPPLIER_ACCOUNT_NOT_FOUND**: Referenced supplier account does not exist
- **AP_INVALID_SUPPLIER_ACCOUNT**: Business partner is unavailable for transactions or belongs to another company
- **AP_CURRENCY_NOT_FOUND**: Referenced currency does not exist
- **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
- **OUTGOING_PAYMENT_INVALID_AMOUNT**: Payment total or settlement amount is not positive
- **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

## Test Cases

- allows an active account when the partner is inactive

- creates a DRAFT payment without settlements
- creates a DRAFT payment with initial settlements
- passes custom payment and settlement fields through to inserts
- returns error for non-positive total or settlement amount
- returns error when company is missing or inactive
- returns error when supplier is missing, unavailable, or company-incompatible
- returns error when currency does not exist
- returns error when payment account is missing, inactive, or belongs to another company
- returns error when initial settlements duplicate a due schedule line
- returns error when an initial settlement target is ineligible
- allows an initial settlement to target an AP-increasing INVOICE correction
- allows an initial settlement to target a posted CREDIT_MEMO