finan : Bank, cash and miscellaneous journal entries

This document describes what we call financial vouchers as implemented by the lino_xl.lib.finan plugin.

A tested document

This is a tested document. The following instructions are used for initialization:

>>> from lino import startup
>>> startup('lino_book.projects.pierre.settings.doctests')
>>> from lino.api.doctest import *
>>> ses = rt.login("robin")
>>> translation.activate('en')

This document is based on the following other specifications:

Vocabulary

There are three kinds of financial vouchers:

bank statement

A voucher you receive from your bank and which reports the transactions that occurred on a given bank account during a given period.

payment order

A voucher you send to your bank asking them to execute a series of payments (outgoing transactions) to third-party partners from a given bank account.

See About payment orders.

journal entry

A voucher where you declare that you move money around internally, for your own accounting.

French: "operations diverse"

About payment orders

To configure a journal of payment orders, you set the following fields:

  • voucher_type should be lino_xl.lib.ledger.VoucherTypes.bank_po

  • partner ("Organization") should point to your bank.

  • dc (Primary booking direction) should be DEBIT.

  • account should be the ledger account marked as CommonAccounts.pending_po.

A payment order clears the invoices it asks to pay. Which means for example that a provider might tell you that some invoice isn't yet paid, although your MovementsByPartner says that it is paid. The explanation for this difference is simply that the payment order hasn't yet been fully executed by your or their bank.

Lino books the sum of a payment order into a single counter-movement that will debit your bank's partner account. Your bank becomes a creditor (you owe them the sum of the payments) and you expect this amount to be cleared by an expense in a bank statement which confirms that the bank executed your payment order.

Database models

class lino_xl.lib.finan.JournalEntry

Django model to represent a journal entry.

class lino_xl.lib.finan.BankStatement

Django model to represent a bank statement.

balance1

The old (or start) balance.

balance2

The new (or end) balance.

class lino_xl.lib.finan.PaymentOrder

Django model to represent a payment order.

entry_date

The date of the ledger entry.

execution_date

The execution date of payment order. If this is empty, Lino assumes the entry_date when writing the pain_001.xml file.

total

The total amount. This is automatically computed when you register de voucher.

class lino_xl.lib.finan.JournalEntryItem

Django model to represent an individual item of a journal entry.

class lino_xl.lib.finan.BankStatementItem

Django model to represent an individual item of a bank statement.

class lino_xl.lib.finan.PaymentOrderItem

Django model to represent an individual item of a payment order.

Model mixins

class lino_xl.lib.finan.FinancialVoucher

Base class for all financial vouchers: JournalEntry, PaymentOrder and BankStatement.

item_account

The default value to use when FinancialVoucherItem.account of an item is empty.

item_remark

The default value to use when FinancialVoucherItem.remark of an item is empty.

printed
See :attr:`lino_xl.lib.excerpts.mixins.Certifiable.printed`
class lino_xl.lib.finan.DatedFinancialVoucher
A :class:`FinancialVoucher` whose items have a :attr:`date` field.
class lino_xl.lib.finan.FinancialVoucherItem

The base class for the items of all types of financial vouchers (FinancialVoucher).

account

The general account to be used in the primary booking. If this is empty, use item_account of the voucher.

project

The "project" related to this transaction. For example in Lino Welfare this is the client.

partner

The partner account to be used in the primary booking.

In Lino Welfare this field is optional and used only for transactions whose recipient is different from the client. When empty, Lino will book to the client (i.e. project).

amount

The amount to be booked. If this is empty, then the voucher cannot be registered.

dc

The direction of the primary booking to create.

remark

External reference. The description of this transation as seen by the external partner.

seqno
match

An arbitrary string used to group several movements.

A reference to the voucher that caused this voucher entry. For example the match of the payment of an invoice points to that invoice.

class lino_xl.lib.finan.DatedFinancialVoucherItem

A FinancialVoucherItem with an additional date field.

date

The value date of this item.

Plugin configuration

class lino_xl.lib.finan.Plugin

This Plugin class adds some entries to the Explorer menu. It contains the following additional attributes:

suggest_future_vouchers

Whether to suggest vouchers whose due_date is in the future.

The default value is currently False because some demo fixtures rely on this. But in most cases this should probably be set to True because of course a customer can pay an invoice in advance.

You can specify this for your application:

def setup_plugins(self):
    self.plugins.finan.suggest_future_vouchers = True
    super(Site, self).setup_plugins()

Or, as a local system administrator you can also simply set it after your SITE instantiation:

SITE = Site(globals())
...
SITE.plugins.finan.suggest_future_vouchers = True

Tables

class lino_xl.lib.finan.FinancialVouchers

Base class for the default tables of all other financial voucher types (JournalEntries , PaymentOrders and BankStatements).

class lino_xl.lib.finan.JournalEntries
class lino_xl.lib.finan.PaymentOrders

The base table of all tables on PaymentOrder.

class lino_xl.lib.finan.BankStatements

The base table of all tables on BankStatement.

class lino_xl.lib.finan.ItemsByVoucher

The base table of all tables which display the items of a given voucher.

class lino_xl.lib.finan.ItemsByJournalEntry
class lino_xl.lib.finan.ItemsByPaymentOrder
class lino_xl.lib.finan.ItemsByBankStatement
class lino_xl.lib.finan.SuggestionsByVoucher

Shows the suggested items for a given voucher, with a button to fill them into the current voucher.

This is the base class for SuggestionsByJournalEntry SuggestionsByBankStatement and SuggestionsByPaymentOrder who define the class of the master_instance (master)

This is an abstract virtual slave table.

Every row is a DueMovement object.

class lino_xl.lib.finan.SuggestionsByJournalEntry

A SuggestionsByVoucher table for a JournalEntry.

class lino_xl.lib.finan.SuggestionsByPaymentOrder

A SuggestionsByVoucher table for a PaymentOrder.

class lino_xl.lib.finan.SuggestionsByBankStatement

A SuggestionsByVoucher table for a BankStatement.

class lino_xl.lib.finan.SuggestionsByVoucherItem

Displays the payment suggestions for a given voucher item, with a button to fill them into the current item (creating additional items if more than one suggestion was selected).

class lino_xl.lib.finan.SuggestionsByJournalEntryItem
class lino_xl.lib.finan.SuggestionsByPaymentOrderItem

A SuggestionsByVoucherItem table for a PaymentOrderItem.

class lino_xl.lib.finan.SuggestionsByBankStatementItem

A SuggestionsByVoucherItem table for a BankStatementItem.

Actions

class lino_xl.lib.finan.ShowSuggestions

Show suggested items for this voucher.

class lino_xl.lib.finan.SuggestionsByVoucher
class lino_xl.lib.finan.FillSuggestionsToVoucher

Fill selected suggestions from a SuggestionsByVoucher table into a financial voucher.

This creates one voucher item for each selected row.

class lino_xl.lib.finan.FillSuggestionsToVoucherItem

Fill the selected suggestions as items to the voucher. The first selected suggestion does not create a new item but replaces the item for which it was called.

Template files

pain_001.xml

Used for writing a SEPA payment initiation.

finan/PaymentOrder/pain_001.xml