diff --git a/docs/financial/financialentities.md b/docs/financial/financialentities.md new file mode 100644 index 0000000000000000000000000000000000000000..cbb2e5812e182cb71ddba23cfa0ea561c7cbb57f --- /dev/null +++ b/docs/financial/financialentities.md @@ -0,0 +1,63 @@ +!!! 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. + +It is a work in progress! + +The original file for tracking these is [on the old CiviCRM Wik](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 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 + + + +## 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](#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/financial/OrderAPI.md b/docs/financial/orderAPI.md similarity index 100% rename from docs/financial/OrderAPI.md rename to docs/financial/orderAPI.md diff --git a/docs/financial/PaymentAPI.md b/docs/financial/paymentAPI.md similarity index 100% rename from docs/financial/PaymentAPI.md rename to docs/financial/paymentAPI.md 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 diff --git a/mkdocs.yml b/mkdocs.yml index b4df2b11e843bd77119f79c52bf304b1f30a88c3..013f4b09079c829e132106f73d6478b12ab29a05 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -32,8 +32,9 @@ pages: - Release Process: core/release-process.md - Financial: - Overview: financial/overview.md - - Order API: financial/OrderAPI.md - - Payments API: financial/PaymentAPI.md + - Order API: financial/orderAPI.md + - Payment API: financial/paymentAPI.md + - Entities: financial/financialentities.md - Extensions: - Basics: extensions/index.md - Packaging Options: extensions/packaging.md