diff --git a/docs/financial/financial-entities.md b/docs/financial/financial-entities.md new file mode 100644 index 0000000000000000000000000000000000000000..6bb199badaa7eaf6e3d0167c68fe895361f0cdb6 --- /dev/null +++ b/docs/financial/financial-entities.md @@ -0,0 +1,61 @@ +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. + +It is a work in progress! + +The original file for tracking these is https://wiki.civicrm.org/confluence/display/CRM/CiviAccounts+Data+Flow + +##Financial accounts + +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 thee 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 + + + +##Financial transactions + +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) +- 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) + +## Payments + +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 + +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. + + diff --git a/docs/img/financial/FinancialAccount.png b/docs/img/financial/FinancialAccount.png new file mode 100644 index 0000000000000000000000000000000000000000..43e3439ac10ca8827f19233482e6ebdd29a1e6cd Binary files /dev/null and b/docs/img/financial/FinancialAccount.png differ