# SmartPay360 Payment + Cheque Integration

## Installation order

1. Back up the SmartPay360 database and the current `modules/payments` directory.
2. In phpMyAdmin, select the SmartPay360 database.
3. Run `database/20260725_merge_payments_with_cheques.sql`.
4. Upload the supplied `payments` directory over `modules/payments`.
5. Keep the existing canonical cheque module at `modules/cheques`.
6. Open **Payments → New Payment**, select supplier invoices, and test with one small cheque.

## What changed

- A cheque is selected from the physical `cheque_leaves` inventory inside the payment entry popup.
- The cheque number becomes the payment reference automatically.
- Cheque payments are saved as `Pending` and use planned allocations.
- Planned cheque allocations do not reduce invoice balances until the cheque is cleared.
- Pending cheque commitments reduce the amount available for another payment, preventing duplicate commitments.
- Marking a cheque `Cleared` copies planned allocations into `payment_allocations` and recalculates invoices.
- Marking a cheque `Bounced` or `Cancelled` removes effective allocations and reopens invoice balances.
- Payment and cheque lifecycle changes are logged in `payment_logs` and `payment_cheque_events`.
- The code detects either `leaf_status`, `cheque_status`, or legacy `status` on `cheque_leaves`.
- The code does not assume `cb.book_label`; it falls back to `Book #ID`.

## New database tables

- `payment_cheques`
- `payment_cheque_allocations`
- `payment_cheque_events`

## New support files

- `payments/_payment_cheque_lib.php`
- `payments/cheque_leaves_ajax.php`
- `payments/cheque_status_action.php`

## Main updated pages

- `payments/select_invoices.php`
- `payments/add.php`
- `payments/save_payment.php`
- `payments/list.php`
- `payments/view.php`
- `payments/pending_cheques.php`
- `payments/calendar.php`
- `payments/fetch_payments.php`
- `payments/payment_success.php`

## Status behavior

| Method | Saved payment status | Invoice effect |
|---|---|---|
| Cash / M-Pesa / Bank / RTGS / EFT | Cleared | Allocations apply immediately |
| Cheque issued | Pending | Planned only |
| Cheque cleared | Cleared | Planned allocations become effective |
| Cheque bounced | Bounced | Effective allocations are removed |
| Cheque cancelled | Cancelled | Effective allocations are removed |

## Important test checklist

1. Create or confirm an active bank account and cheque book in `modules/cheques`.
2. Confirm at least one available cheque leaf exists.
3. Select an unpaid supplier invoice.
4. Choose `Cheque`, select the bank account and leaf, and save.
5. Confirm the payment appears as `Pending` and the invoice remains unpaid/partially paid.
6. Open the payment and click **Mark Cleared**.
7. Confirm the payment becomes `Cleared` and invoice balances update.
8. Test another cheque and mark it `Bounced`; confirm the invoice balance remains open.

## Legacy page handling

The older duplicate cheque pages inside `modules/payments` now redirect to the canonical `modules/cheques` pages or the integrated payment workflow.
