Reconciliation Specification (Invoice ↔ Bank)

1. Goal: The Control & Truth Problem

• Definition: Answering "Has this liability actually been settled in cash — correctly, completely, and to the right counterparty?"
• Core Question: Identifying discrepancies between Payment Expectations (AP) and Cash Reality (Bank).
• Outcome: Direct close acceleration by validating paid invoices and flagging anomalies.

2. Leveraging Existing AP Assets

• Expectation Side (We already have):
  • Invoice IDs, Approved Amounts, Due Dates.
  • Vendor Master Data, Remittance Info.
  • Approval Logic (Conditions of payment).
• Missing Piece: The Cash Reality side (Bank Transactions).

3. Core Building Blocks (V1)

3.1 Data Ingestion

A) Bank Transactions (Cash Reality)

• Access: Read-only.
• Sources: Bank APIs (Preferred), MT940 / CAMT.053 / CSV (Fallback).
• Data Points:
  • transaction_id
  • transaction_date, value_date
  • amount, currency
  • counterparty_name, IBAN
  • remittance_text
  • bank_fees

B) Payment Expectations (Derived)

• Concept: The "Should Happen" side, generated for each approved invoice.
• Object Structure:
  • payment_expectation_id
  • invoice_id, vendor_id
  • expected_amount, currency
  • due_date, earliest_pay_date, latest_pay_date
  • expected_reference_texts[]
  • iban(s)
  • status: [OPEN, PARTIALLY_PAID, PAID, EXPIRED]

3.2 Matching Engine (Deterministic First)

• Logic: Match BankTransaction ↔ PaymentExpectation.
• Signals (Ranked):
  1. Amount (Exact / Tolerance)
  2. Currency
  3. Counterparty IBAN
  4. Reference Text (Invoice #)
  5. Date Proximity
  6. Vendor Name Similarity
• Match Output:
  • match_confidence (0-100)
  • match_type: [EXACT, PARTIAL, AGGREGATED, AMBIGUOUS]

3.3 LLM / Semantic Matching (The Closer)

• Use Case: When deterministic rules fail (low confidence) or return AMBIGUOUS results. Useful for:
  • Messy remittance text (typos, abbreviations).
  • Combined payments (one transaction paying 3 invoices).
  • Fuzzy counterparty names (e.g., "Acme Corp" vs "Acme Inc Berlin").
• Mechanism:
  • Input: Bank Transaction JSON + Candidate Payment Expectations (filtered by date/amount).
  • Prompt Strategy: "Analyze this remittance string against these invoice numbers. Explain the logic."
  • Output: suggested_match_ids[], reasoning_text, confidence_score.
• Guardrails:
  • LLM matches are flagged as "AI Suggested".
  • Never auto-post unless combined with a deterministic signal (e.g., Exact Amount).

3.4 Canonical Reconciliation Object: PRU

• Name: PaymentReconciliationUnit (PRU)
• Purpose: Mirrors GR/IR unit logic; holds the state of the match.
• Structure:
  • pru_id
  • invoice_id
  • bank_tx_ids[]
  • expected_amount vs paid_amount
  • open_amount
  • state
  • evidence_snapshot
• States:
  • MATCHED_PAID
  • PARTIALLY_PAID
  • OVERPAID / SHORT_PAID
  • UNMATCHED_INVOICE / UNMATCHED_PAYMENT
  • FX_DIFFERENCE / FEE_DIFFERENCE
  • BLOCKED_NEEDS_REVIEW

4. Resolution Logic (Action Catalog)

5. Product Surfaces (V1)

5.1 Payment Reconciliation Inbox

• View: Close-critical worklist.
• Columns: Vendor, Invoice, Expected vs Paid, State, Aging, Recommended Action.

5.2 Detail View

• Content:
  • Invoice Summary & Approval Context.
  • Matched Bank Transaction(s).
  • Match Explanation (Why did we match this?).
  • Action Buttons (e.g., "Post FX Diff", "Unmatch").

6. Integration with Close

• Cash Certainty: Paid invoices are confidently closed.
• Accrual Reversals: Become deterministic.
• Audit Trail: "Show me proof of payment" becomes a one-click evidence pack.

7. V2 Extensions

• Payment Runs: One payment paying multiple invoices (Batching).
• Advances: Match payment without invoice -> Hold as Prepayment Asset.
• Multi-Currency: Advanced FX logic (Expected in Invoice Currency vs Paid in Local).