payment

When an invoice is posted, two pieces of payment intelligence appear on the form. Below the totals, a Paid on line per reconciled payment. Above them, when the customer has unapplied credits, a boxed list of outstanding entries with an Add link each. Both are the payment widget rendering two different fields.

Neither field is a one2many. invoice_payments_widget and invoice_outstanding_credits_debits_widget are computed binary fields whose value is a JSON document: a content array of line dicts, a title, a move_id, and an outstanding boolean. That last flag is the switch: outstanding: true renders the credits box with Add links, outstanding: false renders the Paid on table with info icons. The widget itself holds no accounting logic; the server compute decides what is listed, the widget decides how it looks and which server method each click calls.

Each Paid on line carries an info icon opening a popover titled Journal Entry Info: amount (with the foreign currency in parentheses when relevant), memo, date, journal and payment method, and the branch in multi-company setups. Two buttons close it out: View opens the payment's business document, and Unreconcile detaches the payment from the invoice.

This widget is where three everyday finance operations actually happen, so it pays to know its exact behavior.

Applying credits. The Add link on an outstanding credit calls js_assign_outstanding_line and reconciles that single entry against the invoice, then reloads the form. Teams that issue lots of credit notes live on this link; teams that never see the box usually have payments landing in a different partner or currency, which is a data problem, not a widget problem.

Undoing a wrong application. Unreconcile on the popover removes one partial reconciliation, not the payment itself. The money stays received; it just returns to outstanding status. Because the button only renders for users in the invoicing access group, junior roles literally cannot see the undo, which is a sensible default most companies never realize is protecting them.

Auditing what paid what. The popover's View button routes through action_open_business_doc, landing on the payment, the statement line or the entry, whichever the reconciled counterpart really is. That resolution logic is server side, so custom payment flows inherit it for free.

If your invoices come from a custom pipeline and the payment area behaves oddly, the JSON compute on the server is where to look, and adjusting it safely is standard Odoo development work.

How core wires it (invoice form)

<field name="invoice_payments_widget" colspan="2" nolabel="1"
       widget="payment"
       invisible="not invoice_payments_widget"/>

The JSON contract the widget expects

{
    "title": "Outstanding credits",
    "outstanding": true,
    "move_id": 42,
    "content": [{
        "id": 7,                     // move line to assign
        "amount": 150.0,
        "currency_id": 1,
        "date": "2026-08-01",
        "journal_name": "Customer Invoices",
        "is_refund": false,
        "is_exchange": false
    }]
}

With outstanding: false the same rows also carry the popover fields: ref, journal_name, payment_method_name, amount_company_currency, amount_foreign_currency, partial_id and account_payment_id. Amounts are formatted in the browser with each line's currency_id, dates re-formatted to the user's locale.

Reusing it on a custom model

my_payments_json = fields.Binary(compute="_compute_my_payments_json")

Emit the same JSON shape and the rendering is free. The click handlers, however, call js_assign_outstanding_line, js_remove_outstanding_partial and action_open_business_doc on your model, so those three methods must exist there for the links to work.

Every action reloads the whole record. Both Add and Unreconcile finish with a full root reload rather than surgically updating one field, because reconciliation changes amounts, statuses and both JSON payloads at once. On heavily customized forms with expensive computes this reload is what users perceive as the click being slow.

Exchange differences are lines with special treatment. Rows flagged is_exchange render as an Exchange Difference label with the amount and, notably, no Unreconcile button in the popover: currency gain or loss entries are system-generated and removing the underlying reconciliation is what removes them.

The popover flips sides in RTL. The component picks left positioning, or bottom when the interface direction is right-to-left, one of the few core widgets making an explicit RTL layout decision in JavaScript.

A dead attribute ships in the template. The outstanding-credits link carries t-att-payment-id="account_payment_id", but no such variable exists in the rendering scope, so the attribute never renders. It has survived every refactor since 16 and is still on the development branch with a modernized spelling, equally dead.

Version drift is in the type declaration, not behavior. Through 16, 17 and 18 the descriptor declared supportedTypes: ["char"] while the server field was already binary; 19 corrected it to binary. Odoo 16 also shipped a parallel legacy-view implementation, removed in 17 along with the old popover API and cached value formatting.

Odoo 20 is expected at Odoo Experience in Brussels, 24 to 26 September 2026. Everything below is read from the public development branch, which is unstable until feature freeze; the page is re-verified against the shipped release.

The field becomes a real JSON type. Both server fields switch from fields.Binary to fields.Json, and the widget's declaration follows suit with supportedTypes: ["json"]. Custom fields feeding this widget will want the same migration.

Exchange differences get aggregated and clickable. Instead of one row per exchange line, the payload gains an exchange_info dict, and the widget renders a single Exchange Difference row whose info icon calls a new action_open_exchange_items method with the exchange line ids.

Cosmetics and labels shift. The outstanding-credit link shows the entry's move_name rather than the journal name, its tooltip is rebuilt from bank_label and ref, and the FontAwesome info icon moves to the new oi icon set.

If you customized the payload compute or the popover template, expect to touch it during your Odoo 20 migration; the JSON contract is changing shape for the first time since 17.