# createIncomingPayment

## Overview

Creates an editable **DRAFT** incoming payment — the document that records receiving money from a customer and settling its open account-receivable items. The native command validates the owning company, the customer business partner, the payment currency, and the cash/bank GL account the payment is received into, then inserts an `IncomingPayment` (status DRAFT) with `paymentDate` and a positive `totalAmount`. Any supplied `settlements` are recorded as `AccountReceivableSettlement` rows, each allocating part of the payment to an `AccountReceivableDueScheduleLine` — an invoice's due installment, or a credit memo's negative installment (a payment may settle invoices and credit memos together at their signed net). Creation performs **no GL posting**; the balanced cash-receipt entry is booked later by [postIncomingPayment](./postIncomingPayment.md). Settlements may be empty at creation and edited until the payment is posted.

## Modules Commands Used

- [account-receivable] createIncomingPayment

## Exception Handling

| Error Code | Description |
| --- | --- |
| ACCOUNT_RECEIVABLE_COMPANY_NOT_FOUND | The owning company does not exist. |
| ACCOUNT_RECEIVABLE_COMPANY_INACTIVE | The owning company is not active. |
| ACCOUNT_RECEIVABLE_BUSINESS_PARTNER_NOT_FOUND | The customer business partner does not exist. |
| ACCOUNT_RECEIVABLE_INVALID_BUSINESS_PARTNER | The business partner is not a valid customer. |
| ACCOUNT_RECEIVABLE_CURRENCY_NOT_FOUND | The payment currency does not exist. |
| ACCOUNT_RECEIVABLE_ACCOUNT_NOT_FOUND | The cash/bank payment account does not exist. |
| ACCOUNT_RECEIVABLE_ACCOUNT_INACTIVE | The cash/bank payment account is not ACTIVE. |
| ACCOUNT_RECEIVABLE_ACCOUNT_COMPANY_MISMATCH | The payment account belongs to a different company. |
| ACCOUNT_RECEIVABLE_INCOMING_PAYMENT_INVALID_AMOUNT | The payment total is not a positive value. |
| ACCOUNT_RECEIVABLE_INCOMING_PAYMENT_SETTLEMENT_INVALID | A settlement allocation has an invalid amount or an ineligible target line. |
| ACCOUNT_RECEIVABLE_INCOMING_PAYMENT_TARGET_INELIGIBLE | A settlement target is not eligible (for example the invoice is not posted). |