docs/extensions/payment-processors/overview.md

+# Payment Processor Extension
+
+A payment processor extension provides the bridge between CiviCRM 
+code and an external payment processing service (e.g Paypal, IATS etc).
+The extension is [generated as a module using `civix generate:module`
+](../civix.md#generate-module)
+and needs to implement some specific conventions to integrate with CiviCRM.
+
+## Accounts (Live / Test)
+
+Each Payment Processor in CiviCRM can be configured with a live and a test account. Internally two separate payment processor records are created.
+
+Requirements vary between providers but in general they should be able to supply you with a test account. A live account usually requires additional verification.
+
+## Requirements
+
+A payment processor integration extension typically includes:
+
+1. An [mgd](#declare-your-payment_processor_type-to-civicrm-with-an-mgd-file) file to declare the processor to CiviCRM.
+
+2. A [Payment Processor class (required)](paymentclass.md) - this provides CiviCRM with a standard interface/API bridge to the third party processor, and a way for CiviCRM to know which features are supported.
+
+3. [A handler function](#the-handlepaymentnotification-method-for-ipns-and-webhooks) for IPNs / web hooks if required for the payment processor. 
+
+4. [Unit tests](#automated-tests).
+
+5. Other libraries and helpers for the particular Payment Processor service.
+
+
+## 1. Declare your payment_processor_type to CiviCRM with an mgd file
+
+Within your extension you should have an `mgd` file (e.g. `/managed/PaymentProcessorType.mgd.php`).
+
+This file will cause the extension system to add a row to the civicrm_payment_processor_type table
+describing your processor. The file should look like:
+
+```php
+<?php
+/**
+
+ * - user_name_label, password_label, signature_label, subject_label - these
+ * are generally about telling the plugin what to call these when they pass
+ * them to Omnipay. They are also shown to users so some reformatting is done
+ * to turn it into lower-first-letter camel case. Take a look at the gateway
+ * file for your gateway. This is directly under src. Some provide more than
+ * one and the 'getName' function distinguishes them. The getDefaultParameters
+ * will tell you what to pass. eg if you see
+ * 'apiKey' you should enter 'user_name' => 'Api Key' (you might ? be able to
+ * get away with 'API Key' - need to check). You can provide as many or as few
+ * as you want of these and it's irrelevant which field you put them in but
+ * note that the signature field is the longest and that in future versions of
+ * CiviCRM hashing may be done on password and signature on the screen.
+ *
+ * - 'class_name' => 'Payment_OmnipayMultiProcessor', (always)
+ *
+ * - 'url_site_default' - this is ignored. But, by giving one you make it
+ * easier for people adding processors
+ *
+ * - 'billing_mode' - 1 = onsite, 4 = redirect offsite (including transparent
+ * redirects).
+ *
+ * - payment_mode - 1 = credit card, 2 = debit card, 3 = transparent redirect.
+ * In practice 3 means that billing details are gathered on-site so it may also
+ * be used with automatic redirects where address fields need to be mandatory
+ * for the signature.
+ *
+ * The record will be automatically inserted, updated, or deleted from the
+ * database as appropriate. For more details, see "hook_civicrm_managed" at:
+ * http://wiki.civicrm.org/confluence/display/CRMDOC/Hook+Reference
+ */
+return [
+  [
+    'name' => 'MyProcessor',
+    'entity' => 'payment_processor_type',
+    'params' => [
+      'version' => 3,
+      'title' => 'My Processor',
+      'name' => 'MyProcessor',
+      'description' => 'My processor',
+      // this will cause the user to be presented with a field,
+      //  when adding this processor, labelled
+      // api key which will save to civicrm_payment_processor.user_name
+      // on save
+      'user_name_label' => 'apiKey',
+      // as per user_name_label, but saves to password
+      'password_label' => 'secret',
+      // as per user_name_label, but saves to signature
+      'signature_label' => 'signature',
+      // prefix of CRM_Core is implicit so the class ie CRM_Core_Payment_MyProcessor
+      'class_name' => 'Payment_MyProcessor',
+      // Any urls you might need stored for the user to be redirect to, for example.
+      // Note it is quite common these days to hard code the urls in the processors
+      // as they are not necessarily seen as configuration. But, if you enter
+      // something here it will be the default for data entry.
+      'url_site_default' => 'https://example.com',
+      'url_api_default' => 'https://example.com',
+      // this is a deprecated concept and these docs recommend you override
+      // anything that references it. However, if you redirect the user offsite
+      // enter 4 and if not enter 1 here.
+      'billing_mode' => 4,
+      // Generally 1 for credit card & 2 for direct debit. This will ideally 
+      // become an option group at some point but also note that it's mostly
+      // or possibly only used from functions that this documentation recommends
+      // you override (eg. `getPaymentTypeLabel`)
+      'payment_type' => 1,
+    ],
+  ],
+];
+```

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

@@ -6,7 +6,7 @@ The financial subsystem in civicrm encompasses:
 - refunds
 - prices
 - discounts
-- premiums (things given away to contacts who donate alot)
+- premiums (things given away to contacts who donate a lot)
 - accounting information
 - integrations with payment processors
 - integrations with accounting systems

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.
+