pay_document

Record a payment against a posted customer invoice, vendor bill, employee voucher, or credit note.

Creates a payment transaction from the specified bank/cash account to the document's A/R or A/P account. Partial payments are supported.

dry_run=true rehearses the payment without booking it: the full validation, conversion, discount, and FX pipeline runs and the response shows the proposed splits, the remaining balance after, whether the invoice would settle in full, and any account the real call would auto-create. Same inputs, same code path — a rehearsal that succeeds is a payment that will book. Recommended before complex payments (cross-currency, discounts, credit-note refunds).

For cross-currency payments where the rate moved between post-date and pay-date, a realized FX gain/loss split is booked. Pass fx_account to control routing; otherwise the server picks the unique INCOME/EXPENSE account whose leaf name matches "fx", "forex", "foreign exchange", "currency gain/loss", "exchange gain/loss", or "currency translation". When zero or multiple match, the canonical Income:Foreign Exchange Gain/Loss is used (auto-created if absent), and an fx_notice is returned listing ambiguous candidates so you can pass fx_account explicitly next time.

For invoices with early-payment-discount terms (e.g., "2/10 Net 30" = 2% off if paid within 10 days), pass apply_discount=True to settle via discount. The tool validates that the invoice has discount terms, the payment date is within the discount window, and the shortfall matches the expected discount on pre-tax principal. Each failure mode rejects with a specific error rather than silently downgrading to a partial payment. discount_account controls routing the same way fx_account does (auto-resolves to Expenses:Sales Discounts for customer payments, Income:Purchase Discounts Taken for vendor bill payments).

Args: id: Document ID (e.g., "000001"). payment_account: Bank or cash account for payment (e.g., "Assets:Checking"). amount: Payment amount as decimal string (e.g., "500.00"). payment_date: Payment date (YYYY-MM-DD). Defaults to today. description: Description for the payment transaction. Optional. document_type: "invoice", "bill", "voucher", or "credit_note" — disambiguates when IDs collide. party_type: Owner side, credit notes only. fx_account: Optional INCOME or EXPENSE account to receive realized FX gain/loss (cross-currency payments only). Accepts a full path, %short GUID, or full 32-char GUID. apply_discount: When True, treat this payment as the final settlement and absorb the early-payment discount from the invoice's billterm. Default False — explicit opt-in. Hard-rejects on credit notes (refunds don't take discounts). discount_account: Optional INCOME or EXPENSE account to receive the discount split. Auto-resolves when omitted. Accepts full path, %short GUID, or full 32-char GUID. force: Override the stale-FX-rate guard. A cross-currency payment etches the rate at pay time; if the latest price is 7–90 days from the payment date the payment is refused with stale_fx_rate unless force=True (the override is recorded as fx_stale/"forced"). A rate beyond the 90-day cap cannot be forced. memo: Optional memo for the bank-account split (e.g., check number or wire reference). description names the whole transaction; memo annotates the cash movement. dry_run: When True, rehearse without writing — returns the proposed splits and projected outcome instead of booking. Default False.

Returns: status is "paid" when the document settles to zero, "partial" when a balance remains, and "would_pay" on dry runs — plus the amount paid, remaining balance, and transaction reference.