Newer
Older
!!! abstract This area of CiviCRM code and documentation is a work-in-progress. Not all features will be documented and the core code underlying this area may change from version to version.
This file exists to give an overview of the Financial entities involved in recording Financial data in CiviCRM.
You should only interact with the Financial entities through the relevant apis - generally Order & Payment apis.
The original file for tracking these is [on the old CiviCRM Wik](https://wiki.civicrm.org/confluence/display/CRM/CiviAccounts+Data+Flow).
These are accounting financial accounts. They have fields intended to help map to an accounting package that
are not used functionally in CiviCRM but are available in various reports.
* accounting_code (free-form text)
* account_type_code (free-form text)
* financial_account_type_id (linked to the option group with the name financial_account_type)
* contact id (not used in core but can be used in extensions - e.g. this is used in the [connectors](https://github.com/eileenmcnaughton/nz.co.fuzion.connectors) extension to link some accounts to one Xero account & others to a different one).
* is_header_account
In addition there are some functional fields that affect how tax is handled:
* tax_rate
* is_deductible
* is_tax
Movements into or out of financial accounts are represented by financial transactions in the civicrm_financial_trxn table.
Each financial transaction has a `from_account_id` and a `to_account_id`. These represent movements between financial accounts.
They also have various informative fields:
* trxn_date
* fee_amount, net_amount, total_amount
* currency
* is_payment (is this a payment financial transaction - see section on [payments](#payments))
* payment_instrument_id (links to payment_instrument option group - e.g check, credit card)
* payment_processor_id (when a payment processor has processed the payment)
* card_type_id, pan_truncation, check_number - these are additional bits of information gathered about the payment
* trxn_id, trxn_result_code, order_reference - these are all generated by the payment processor (when there is one) and
stored in CiviCRM when available. The trxn_id is the processor reference for the gateway. Some processors have references
at the order level. Even though these are at the order level there could be more than one per order as more than one.
payment with more than one processor might be paid against an order (contribution), hence they are stored on the financial transaction
* status_id - the intent is that failed as well as successful payments should be stored (and appropriately filtered in bookkeeping reports)
Some financial transactions are payments and these are marked with the `is_payment` field on that table. Payments in CiviCRM are a subset
of the rows in `civicrm_financial_trxn`. You should use the Payment API to interact with these payment financial transactions.
Importantly payments will end up moving money ***to*** an account where payments are collected - ie a Bank account
or a Payment Processor account (which in the real world may be an actual account or just a clearing house for nightly payments.)
Negative payments (or refunds) will have the bank or processor account on the ***from*** side of the transaction.
Financial items exist to track how much has been paid against the various line items within an order / contribution.
In an accounting system this might be called credit-matching.
Each line item will have one or more financial items denoting payments made against it. On creation of the order there
will be a financial item for each line item and an additional item for every fee amount. Where the preferred flow is used
this item will have a status of 'Unpaid'.
!!! note
For historical reasons this may not always be true but [it's the goal](https://github.com/civicrm/civicrm-dev-docs/issues/712).
When a payment is made it might either pay off the line items, or a specific line item, in full. In that case the line item
status is updated to Paid and an `EntityFinancialTrxn` record is created in the `civicrm_entity_financial_trxn` table linking
the line item to the payment and specifying the amount paid.
If the line item is paid in part then the status is not updated and the `EntityFinancialTrxn` record specifies the portion
of the line item that has been paid by that payment.
If the line items change then the items financial items have to be updated. Generally the rule is to alter the zero out the
old line item, reverse the financial items and then create a new line item with new financial items. However, this is not
always possible as there are some scenarios where the schema does not permit this. The has led to
adjustment line items being created in these cases. The issue is that the civicrm_line_item table has a unique index for
`entity_table + entity_id + contribution_id + price_field_value_id + price_field_id`.
This means that if a line item with no `price_field_values` (i.e: a text / enter quantity line item) is altered it is not possible
to create a reversal line and a new line within the schema. The same problem occurs when changing a line item with price_field_values
***back*** to a `price_field_value` it previously held. In both these scenarios the work around is to have more than one *valid* `financial_item`
against the resulting line item with an 'adjustment' entry - ie an additional financial_item.