Start writing about financial entities

docs/financial/financial-entities.md

+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
+
+![Example financial accounts](/img/financial/FinancialAccount.png)
+
+##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.
+
+