# postIncomingPayment

## Overview

Posts a **DRAFT** incoming payment to the general ledger, transitioning the `IncomingPayment` from DRAFT to POSTED. The native command resolves the accounting period for the payment date, builds a **balanced `JournalEntry`** — debiting the cash/bank payment account and crediting the receivable control account for the settled amount, direction-aware when the payment settles credit memos as well as invoices — and posts it directly in financial-accounting within the same transaction. The entry carries `sourceDocumentType = INCOMING_PAYMENT` and `sourceDocumentId` equal to the payment id. Posting also applies each settlement against its target `AccountReceivableDueScheduleLine`, reducing that open item's balance. It rejects over-settlement (receiving more than a line's open balance), a total that does not reconcile with the settlements, ineligible targets (for example an invoice that is not itself posted), and a payment currency that differs from the company base currency.

## Modules Commands Used

- [account-receivable] postIncomingPayment

## Exception Handling

| Error Code | Description |
| --- | --- |
| ACCOUNT_RECEIVABLE_INCOMING_PAYMENT_NOT_FOUND | No incoming payment exists for the given ID. |
| ACCOUNT_RECEIVABLE_INCOMING_PAYMENT_INVALID_STATUS | The payment is not in DRAFT status; only DRAFT payments can be posted. |
| ACCOUNT_RECEIVABLE_INCOMING_PAYMENT_OVER_SETTLEMENT | A settlement exceeds the open balance of its target due-schedule line. |
| ACCOUNT_RECEIVABLE_INCOMING_PAYMENT_TOTAL_MISMATCH | The payment total does not reconcile with the sum of its settlements. |
| ACCOUNT_RECEIVABLE_INCOMING_PAYMENT_TARGET_INELIGIBLE | A settlement target is not eligible (for example, the invoice is not posted). |
| ACCOUNT_RECEIVABLE_INCOMING_PAYMENT_SETTLEMENT_INVALID | A settlement allocation is invalid. |
| ACCOUNT_RECEIVABLE_INCOMING_PAYMENT_INVALID_AMOUNT | The payment amount is not a positive value. |
| ACCOUNT_RECEIVABLE_INCOMING_PAYMENT_ACCOUNTING_PERIOD_NOT_FOUND | No accounting period covers the payment date. |
| ACCOUNT_RECEIVABLE_INCOMING_PAYMENT_JOURNAL_ENTRY_CREATE_FAILED | The journal entry could not be created. |
| ACCOUNT_RECEIVABLE_INCOMING_PAYMENT_JOURNAL_ENTRY_POST_FAILED | The journal entry could not be posted to the general ledger. |