Client Payments & Reconciliation

1. Business Summary

Receives client payments, allocates to invoices, integrates with SAP for both cron-driven sync and an inbound endpoint that creates payments from SAP.

2. Business Value

Receivables control, cash application.

3. Users / Stakeholders

Finance.

4. Workflows

A. Manual creation
- Finance enters ClientPayment header + ClientPaymentDetail line items per invoice/PO.

B. SAP-driven inbound
- SapController::addClientPayment() accepts JSON: CompanyName, clientId, sap_id, issueDate, submittingDate, netAmount, currency, bank, paymentDetails[].
- Validates invoices exist + sap_posted=1; creates payment + details.

C. Reconciliation
- After invoice sync, sapInvoiceReconciliation() validates balance.

5. Sub-Features

• Auto-allocation per invoice.
• Bank/method mapping.
• Multi-currency.

6. Business Rules

• Required: CompanyName, clientId, sap_id, issueDate, submittingDate, netAmount.
• Default payment method = 2 (bank transfer).
• submitted=1 auto-set on SAP-received payments.
• Allocation cannot exceed remaining invoice balance.

7. Data Entities

ClientPayment, ClientPaymentDetail, PaymentMethod, Bank.

8. Entry Points

• finance/clientPayments, finance/clientPaymentDetails.
• sap/addClientPayment (REST).

9. Inputs & Outputs

• Inputs: payment data, allocations.
• Outputs: ClientPayment + Details, SAP IDs.

10. Integrations

• SAP.

11. Calculations / Logic

• Remaining = gross_amount - payment_amount.

12. Status Lifecycle

• created → submitted → scheduled/paid → reconciled.

13. Permissions

• Finance, brand-scoped.

14. Reports & KPIs

• DSO, allocation gaps.

15. Risks & Observations

• Inbound endpoint relies on basic auth; over-allocation only enforced in controller.

16. Source Code Evidence

• app/Plugin/finance/Model/ClientPayment.php, ClientPaymentDetail.php.
• app/Plugin/finance/Controller/ClientPaymentsController.php, ClientPaymentDetailsController.php.
• app/Controller/SapController.php :: addClientPayment, sapAddClientPayment, sapInvoiceReconciliation.