Payment Modal¶

The Payment Modal is the shared dialog used across Sofie to record and edit both customer payments (Accounts Receivable) and supplier payments (Accounts Payable). It opens automatically from the Customers, Suppliers, and Accounts screens.

This page covers the fields, the AR/AP differences, the cheque batch flow, and the more nuanced recording scenarios.

From	How
Customers → Payments tab	Click Add to create, or the ✎ button on a row to edit.
Suppliers → Payments tab	Same as Customers.
Accounts (person mode)	Click Add in the expand panel, or ✎ on a payment row.
Accounts (payment mode)	Click any row to edit that single payment.

The modal automatically switches between the AR and AP flavours:

AR flavour (Customers, Accounts AR tab) — shows the cheque section. The receive date field is labelled Date Received.
AP flavour (Suppliers, Accounts AP tab) — shows the installment-number field. The receive date field is labelled Date Paid.

Fields¶

Field	Description
Ref. order no.	Optional reference to a sale order (AR) or purchase order (AP). Use `0` if the payment is not associated with a specific order. Multiple payments sharing the same reference number are grouped together for reconciliation. Free-text — accepts any reference notation, not just numeric IDs.
Installment No. (AP only)	Free-text installment marker, e.g. `2/3` for the second of three. Useful when paying a supplier invoice in parts.
Method	Payment method. Pre-loaded suggestions: `CHEQUE`, `DINHEIRO` (cash), `PIX`, `BOLETO`, `CARTÃO` (card), `TRANSFERÊNCIA` (transfer). Type your own value if needed.
Amount	Payment amount. Always positive — even discounts (see below).
Date Due	When the payment is/was due. Optional but recommended.
Date Received (AR) / Date Paid (AP)	When the payment cleared. Leave blank for a pending payment. Hard-capped at the current moment — future dates are not accepted.
Details	Free-text notes about the payment.

Method-specific sections¶

When the Method field is set to one of the supported types, an additional section appears below:

CHEQUE (AR only) — see the Cheque batch flow below for adding new cheque payments, or the cheque fields directly when editing.
PIX, BOLETO, CARTÃO — each opens a Notes textarea for payment-method-specific information (PIX key / transaction ID / barcode / authorisation code / instalment plan, etc.). The notes are saved into the payment's Details field.

Cheque batch flow (AR only)¶

When the Method is set to CHEQUE while adding a new payment, the modal switches to batch mode — designed for the common case of a customer handing over several cheques at once that share the same order reference and due date.

Batch mode has three sections:

Session — fields shared across the whole batch:
Ref. order no.
Date Due
Cheque details — fields entered per cheque:
Amount
Date Received
Pre-dated to (date the cheque is post-dated for, if any)
CPF/CNPJ — autofill button looks up the payer's most recent cheques and offers them as a one-click pre-fill (bank, branch, account, name).
Name on cheque, Bank, Branch, Account, Cheque No.
Added — the running list of cheques queued for save, with a ✕ button on each row to remove it.

How to record a batch¶

Choose CHEQUE as the Method — the modal switches to batch layout.
Fill in the Session fields (Ref. order no. and Date Due) — these apply to every cheque in the batch.
Fill in the Cheque details for the first cheque, then click Add. The cheque appears in the Added list, and the entry fields are pre-filled with the previous values for the next cheque — only Cheque No. and Pre-dated to are cleared (they always differ per cheque).
Repeat step 3 for each cheque.
When the list is complete, click Save All (n) to record all of them. Each cheque becomes a separate payment record on the customer's account.

The first time a customer is given a cheque batch, the bank/branch/account fields are blank. After the first save, when you open the modal again for the same customer, those fields come pre-filled from the customer's most recently used cheque (looked up by CPF/CNPJ), so subsequent batches start with the bank already filled in. The Date Received field defaults to the current moment.

Cancelling out of batch mode¶

The Cancel button in batch mode is two-step:

First click — exits batch back to single mode. The Method field is cleared so you can re-pick a different method, or click Cancel again.
Second click (or the × in the header) — closes the modal.

Editing an existing CHEQUE payment¶

When editing an existing cheque payment (clicking ✎ on a row), the modal stays in single mode — you edit the one payment record including its cheque fields inline. Batch mode is for new entries only.

Permissions¶

Backdating restriction¶

The Date Received / Date Paid field cannot be set to a date before today unless the user has the owner or sales:manage privilege. Non-owners attempting to save a backdated payment receive the error "Only owners may record a payment date before today".

This applies on both create and update — a non-owner cannot move a previously pending payment to a past received date in the same edit.

Editing past payments¶

Non-owners cannot edit a payment whose Date Received is already before today (the row is shown without action buttons in the grid). Owners can edit any payment regardless of date.

Future dates¶

Future dates are blocked for everyone — there is no privilege exception. This is enforced both by the date input's max attribute on the client and by the API on save.

Quick mark-as-received¶

When the modal is opened from payment mode in the Accounts screen, the Date Received / Date Paid field is pre-filled with today's date if empty. Saving without changes records the receipt in one click. Clear the field before saving if the payment was actually received on a different date.

Recording scenarios¶

The modal is flexible — multiple payments can be combined to record more nuanced situations.

Discount applied at payment time¶

A customer's order totals 203.65 but they round it down to 200.00. Record two payments against the same order:

Ref. order no.	Method	Amount	Date Received
899	DINHEIRO	200.00	2026-04-26
899	DESCONTO	3.65	2026-04-26

Both amounts are positive — the discount is treated as a credit, not a negative entry. This way the petty-cash total reconciles cleanly. A surcharge would be the negative case.

Where to apply discounts ideally

Discounts and surcharges are usually applied directly on the order in the Orders & Quotes screen at the moment of sale. The two-payment pattern above is for situations where the order has already been delivered and cannot be modified.

Cheque + cash split¶

A customer settles a 2,550.00 order with a third-party cheque worth 2,539.10 plus 10.90 in cash. Record two payments:

Ref. order no.	Method	Amount	Date Received
657	CHEQUE	2,539.10	2026-04-26
657	DINHEIRO	10.90	2026-04-26

The CHEQUE payment opens batch mode for recording the cheque details (bank, branch, account, cheque number, payer's tax ID).

Bulk payment for multiple orders¶

A customer pays 4,000.00 toward four open orders (1055, 1066, 1111, 1212) using two cheques and the rest in cash. The cheque amounts don't divide cleanly across the four orders. Record three payments all against the first order, listing the other order numbers in Details:

Ref. order no.	Method	Amount	Date Received	Details
1055	CHEQUE	1,500.00	2026-04-26	Ref. 4 orders 1055, 1066, 1111, 1212
1055	CHEQUE	1,500.00	2026-04-26	Ref. 4 orders 1055, 1066, 1111, 1212
1055	DINHEIRO	1,000.00	2026-04-26	Ref. 4 orders 1055, 1066, 1111, 1212

Grouping all three under order 1055 keeps the customer's account ledger clean. Putting different order numbers on each row would scatter the payments across the customer's account history.

The two cheques can be entered in a single batch session — pick CHEQUE as the method, set Ref. order no. and Date Due once, then Add each cheque and Save All. The cash payment is recorded separately afterwards as a single-mode payment.