MANSOQ Knowledge
← Knowledge library

Billing

Resolve a fully paid invoice that refuses UI balancing

Recognize the audited finalized-invoice payload mismatch and the separately tested, authorized status-only API continuation.

Current source · source reviewed · 7 min read

Before you begin

1. Identify the specific refusal

After Record Payment, Mark as balanced can fail with “Finalized invoice is immutable; use an authorized correction document.” The current payment sheet sends account, charge_items, note and payment_terms as well as status. The backend refuses those generic finalized-invoice edits. The synthetic test returned this refusal while preserving the receipt.

After a saved receipt, Mark as balanced sends generic invoice fields that the backend refuses on a finalized invoice. The invoice remains issued with payment retained. This screenshot records an implementation defect, not a successful balance action.
Recognize the current UI invoice balancing defect · 2026-10-18. Current audited MANSOQ application in an isolated local synthetic training environment. After a saved receipt, Mark as balanced sends generic invoice fields that the backend refuses on a finalized invoice. The invoice remains issued with payment retained. This screenshot records an implementation defect, not a successful balance action.

2. Verify payment and invoice facts first

Open the invoice and its receipt. The observed case retained Issued status with total 150 SAR, payments 150 SAR and balance zero. Independent database readback confirmed one receipt, so no duplicate payment was needed. If amounts, currency, reversals or payment validity disagree, resolve those facts before any status transition.

Following the UI balance refusal, INV-108-26 remains Issued while its recorded payments equal150 SAR and balance is zero. A zero balance does not itself change invoice status.
Read paid amounts separately from invoice lifecycle · 2026-10-18. Current audited MANSOQ application in an isolated local synthetic training environment. Following the UI balance refusal, INV-108-26 remains Issued while its recorded payments equal150 SAR and balance is zero. A zero balance does not itself change invoice status.
The separate receipt detail confirms the actual UI-created150 SARcash payment, synthetic cashier,200 SARtendered and 50 SARchange under Facility Admin authorship. It remains a simulation with no real money moved.
Verify tendered cash and change on the saved receipt · 2026-10-18. Current audited MANSOQ application in an isolated local synthetic training environment. The separate receipt detail confirms the actual UI-created150 SARcash payment, synthetic cashier,200 SARtendered and 50 SARchange under Facility Admin authorship. It remains a simulation with no real money moved.

3. Use the narrow supported update only through an authorized operator

The audited contract is PUT /api/v1/facility/{facilityId}/invoice/{invoiceId}/ with JSON body {"status":"balanced"}. The backend update schema is BaseInvoiceSpec and finalized-invoice logic explicitly separates status from generic fields. In the isolated fully paid teaching case, the existing Facility Admin authentication performed this exact normal API request and received 200. No permission or validator was bypassed. This is an integration continuation, not evidence that the UI action succeeded.

4. Read the result independently

A separate authenticated GET returned balanced, then a refreshed invoice displayed Balanced with unchanged total/payment facts. Database readback later confirmed the linked charge became paid and the account subsequently closed through the UI. If your request is refused, preserve its response and escalate with the invoice reference; do not add generic fields, mutate stored records, or force lifecycle values.

A separate authenticated normal product API PUT containing only status=balanced succeeded after the invoice was fully paid. This refreshed UI readback does not prove the defective Mark as balanced UI action works.
Read the separately verified status-only API result · 2026-10-18. Current audited MANSOQ application in an isolated local synthetic training environment. A separate authenticated normal product API PUT containing only status=balanced succeeded after the invoice was fully paid. This refreshed UI readback does not prove the defective Mark as balanced UI action works.

Version boundary

This defect and continuation were observed at the pinned source revision on an isolated synthetic self-pay invoice. Other deployed revisions may differ. Canonical insured invoices, fiscal documents, allocations and reversals retain their own prerequisites.

Troubleshooting

The UI error appears after a payment success message

The receipt save and invoice-status update are separate operations. Confirm the saved receipt and avoid recording it twice.

The status-only request is still refused

Check current state, the facility permission, invoice/payment validity and the exact server response through your approved support process. Do not bypass the refusal.

Source evidence

References are pinned to the private MANSOQ source repository. Repository access is required to open these links.