Payment Line Documentation¶

Overview¶

The Payment Line module (account.payment.line) represents individual line items within customer and supplier payments. Each line can allocate payment to invoices, record direct payments, handle prepayments, process refunds, or pay expense claims. Lines provide detailed breakdown of payment allocation and drive GL postings.

Model Information¶

Model Name: account.payment.line Display Name: Payment Line Name Field: None (no specific display field) Key Fields: None (auto-increment ID)

Features¶

✅ Multiple payment types (invoice, direct, prepay, refund, etc.)
✅ Invoice payment allocation
✅ Multi-currency support
✅ Tax handling (WHT, VAT)
✅ Tracking category support
✅ Expense claim payments
✅ Cascade delete with parent payment

Key Fields Reference¶

Core Payment Fields¶

Field	Type	Required	Description
`payment_id`	Many2One	✅	Parent payment (cascade delete)
`type`	Selection	✅	Payment type (auto-set from payment)
`description`	Text	❌	Line description
`amount`	Decimal(4)	✅	Payment amount in payment currency
`account_id`	Many2One	❌	GL account for posting

Payment Types¶

Type	Description	Usage
direct	Direct Payment	Pay without invoice reference
invoice	Invoice Payment	Allocate to specific invoice
prepay	Prepayment	Advance payment/deposit
overpay	Overpayment	Excess payment to allocate later
refund	Refund	Return payment to customer
claim	Expense Claim Payment	Pay employee expense claim
adjust	Adjustment	Payment adjustment/correction

Invoice Allocation Fields¶

Field	Type	Description
`invoice_id`	Many2One	Invoice being paid
`amount_invoice`	Decimal	Amount in invoice currency
`currency_rate`	Decimal	Conversion rate (payment→invoice)
`invoice_amount_due`	Computed	Invoice due amount

Tax Fields¶

Field	Type	Description
`tax_id`	Many2One	Tax rate for direct payments
`tax_comp_id`	Many2One	Tax component (WHT)
`tax_base`	Decimal	Taxable base for WHT
`tax_no`	Char	Tax receipt/certificate number
`tax_date`	Date	Tax date

Tracking Fields¶

Field	Type	Description
`track_id`	Many2One	Tracking category (Track-1)
`track2_id`	Many2One	Tracking category (Track-2)
`product_id`	Many2One	Related product
`contact_id`	Many2One	Related contact

API Methods¶

1. Create Payment Line¶

Method: create(vals, context)

Creates line with automatic type detection from parent payment.

Example:

# Invoice payment line
line_id = get_model("account.payment.line").create({
    "payment_id": payment_id,
    "invoice_id": invoice_id,
    "amount": 1000.00,
    "description": "Payment for INV-001"
})
# Type automatically set to "invoice"

# Direct payment line
line_id = get_model("account.payment.line").create({
    "payment_id": payment_id,
    "account_id": expense_account_id,
    "amount": 500.00,
    "description": "Office supplies",
    "tax_id": vat_rate_id
})
# Type automatically set to "direct"

Common Use Cases¶

Use Case 1: Pay Single Invoice¶

# Create payment for invoice
payment_id = get_model("account.payment").create({
    "type": "in",  # Receipt from customer
    "contact_id": customer_id,
    "account_id": bank_account_id,
    "date": "2025-01-15",
    "pay_type": "invoice",
    "lines": [
        ("create", {
            "invoice_id": invoice_id,
            "amount": 1070.00  # Invoice total
        })
    ]
})

Use Case 2: Partial Payment¶

# Pay part of invoice
get_model("account.payment.line").create({
    "payment_id": payment_id,
    "invoice_id": invoice_id,
    "amount": 500.00,  # Partial amount
    "description": "Partial payment 1 of 2"
})
# Invoice remains partially paid

Use Case 3: Pay Multiple Invoices¶

# One payment for multiple invoices
payment_id = get_model("account.payment").create({
    "type": "in",
    "contact_id": customer_id,
    "account_id": bank_account_id,
    "date": "2025-01-15",
    "pay_type": "invoice",
    "lines": [
        ("create", {
            "invoice_id": inv1_id,
            "amount": 1000.00
        }),
        ("create", {
            "invoice_id": inv2_id,
            "amount": 1500.00
        }),
        ("create", {
            "invoice_id": inv3_id,
            "amount": 800.00
        })
    ]
})
# Total payment: $3300

Use Case 4: Direct Payment with Tax¶

# Pay expense directly without invoice
payment_id = get_model("account.payment").create({
    "type": "out",  # Payment to supplier
    "contact_id": supplier_id,
    "account_id": bank_account_id,
    "date": "2025-01-15",
    "pay_type": "direct",
    "lines": [
        ("create", {
            "account_id": expense_account_id,
            "qty": 10,
            "unit_price": 50.00,
            "tax_id": vat_rate_id,
            "description": "Office supplies"
        })
    ]
})
# Creates payment with tax calculation

Use Case 5: Withholding Tax Payment¶

# Customer payment with WHT deduction
payment_id = get_model("account.payment").create({
    "type": "in",
    "contact_id": customer_id,
    "account_id": bank_account_id,
    "date": "2025-01-15",
    "pay_type": "invoice",
    "lines": [
        ("create", {
            "invoice_id": invoice_id,
            "amount": 9700.00,  # Net after WHT
            "tax_comp_id": wht_component_id,
            "tax_base": 10000.00,
            "tax_no": "WHT-2025-001",
            "tax_date": "2025-01-15"
        })
    ]
})
# Gross: $10,000
# WHT 3%: -$300
# Net received: $9,700

Best Practices¶

1. Match Currency Amounts¶

# For multi-currency payments
{
    "invoice_id": usd_invoice_id,
    "amount": 35500.00,  # THB (payment currency)
    "amount_invoice": 1000.00,  # USD (invoice currency)
    "currency_rate": 35.5  # THB per USD
}

2. Use Correct Payment Type¶

# Let system set type automatically based on pay_type
# Don't manually override "type" field

3. Provide Clear Descriptions¶

# Good: Detailed description
"description": "Payment for INV-2025-001 - Project Alpha"

# Minimal: Basic info
"description": "Invoice payment"

Model	Relationship	Description
`account.payment`	Many2One	Parent payment
`account.invoice`	Many2One	Invoice being paid
`account.account`	Many2One	GL account
`account.tax.rate`	Many2One	Tax rate
`account.tax.component`	Many2One	Tax component (WHT)
`expense.claim`	Many2One	Expense claim
`contact`	Many2One	Related contact

Version History¶

Last Updated: 2025-12-16 Model Version: account_payment_line.py Framework: Netforce

This documentation is generated for developer onboarding and reference purposes.