docs/extensions/troubleshooting.md

 # Troubleshooting
 
-If you are struggling, the best thing to do is reach out to the [CiviCRM community](/basics/community.md).
+If you are struggling, the best thing to do is reach out to the [CiviCRM community](../basics/community.md).
 
 If you cannot find the answer in this guide or by searching in the [CiviCRM StackExchange site](http://civicrm.stackexchange.com/) then please [ask](http://civicrm.stackexchange.com/questions/ask). Asking questions on StackExchange not only helps you but may well help others who follow you.
 
@@ -22,7 +22,7 @@ A: You might have missed the step about setting 'civicrm\_api3\_conf\_path' ([ht
 
 Q: I've tried to generate a page/report/search/upgrader/etc with civix but it's not working.
 
-A: For all of the various types, you must first run [generate:module](http://generatemodule), and then \`cd\` into the folder (e.g. com.example.myextension) before running one of the other \`generate:\` commands.
+A: For all of the various types, you must first run [generate:module](civix.md#generate-module), and then \`cd\` into the folder (e.g. com.example.myextension) before running one of the other \`generate:\` commands.
 
 ## Out-of-date templates
 

docs/financial/overview.md

+The financial subsystem in civicrm encompasses:
+
+- contributions
+- recurring contributions
+- payments
+- refunds
+- prices
+- discounts
+- premiums (things given away to contacts who donate a lot)
+- accounting information
+- integrations with payment processors
+- integrations with accounting systems
+
+There are strong relationships between the financial area of CiviCRM and memberships, event registrations, and pledges.
+
+Due to the importance of data integrity, the tight coupling of related business operations, and large number of tables in the implementation, there is a strong focus on using higher level business APIs rather than lower level table oriented operations. 
+
+Key concepts include:
+
+- order (sometimes called invoice)
+- line item
+- bookkeeping entries which encompass at a minimum a debit and credit financial account, an amount and a date
+- financial account, which corresponds to an account in a financial system's (like QuickBooks) chart of accounts
+- financial type, which organisations can use to categorise their contributions (like "Donation") for their own management purposes (e.g. "Donation for X"), accounting purposes (which financial accounts are used) and regulartory requirements (e.g. to identify taxable contributions)
+
+The main purpose of this documentation is to support
+
+- non-core systems for creating orders, eg a Drupal webform or WordPress Caldera Forms replacement of CiviCRM Contribution and Event Pages.
+- payment processor integrations in all of their variety.

docs/financial/paymentAPI.md

+## Payment API
+
+Historically, one recorded a payment against a contribution by changing its payment status, for example from Pending to Completed. 
+
+It is now best practice to use the Payment.create API call.
+
+Note that paymentprocessor.pay handles the communication with a payment processor to instigate a payment. Similarly, paymentprocessor.refund handles the communication with a payment processor to instigate a refund.
+
+After a contribution has been created, for example using the best practice Order.create API call, use the Payment.create API action to
+
+* record a payment against the contribution - either fully or partially paying the contribution amount
+* record a refund against the contribution
+
+Use the Payment.cancel api to reverse a refunded payment.
+