Extensively re-organize payment processor content

docs/extensions/info-xml.md

@@ -63,8 +63,10 @@ Here we describe all the elements acceptable within the XML file. They are prese
 ### `<billingMode>` {:#billingMode}
 
 * Containing element: [`<typeInfo>`](#typeInfo)
-* Description: *not yet documented*
+* Description: Specifies the billing mode (aka "type") for a payment processing extension
 * Contains: text
+* Acceptable values: See [payment processor types](/extensions/payment-processors/create.md#type)
+* Example: `button`
 
 ### `<civix>` {:#civix}
 
@@ -241,7 +243,7 @@ Elements acceptable within `<maintainer>`
 ### `<passwordLabel>` {:#passwordLabel}
 
 * Containing element: [`<typeInfo>`](#typeInfo)
-* Description: *not yet documented*
+* Description: Label to use for the password field
 * Contains: text
 
 ### `<paymentType>` {:#paymentType}
@@ -294,13 +296,13 @@ Elements acceptable within `<requires>`
 ### `<signatureLabel>` {:#signatureLabel}
 
 * Containing element: [`<typeInfo>`](#typeInfo)
-* Description: *not yet documented*
+* Description: Label to use for the signature field
 * Contains: text
 
 ### `<subjectLabel>` {:#subjectLabel}
 
 * Containing element: [`<typeInfo>`](#typeInfo)
-* Description: *not yet documented*
+* Description: Label to use for the subject field
 * Contains: text
 
 ### `<typeInfo>` {:#typeInfo}
@@ -313,22 +315,22 @@ Elements acceptable within `<typeInfo>`
 
 | Element | Acceptable instances | Acceptable<br>when |
 | -- | -- | -- |
-| [`<reportUrl>`](#reportUrl) | 0 or 1 | `<extension type="report">` |
-| [`<userNameLabel>`](#userNameLabel) | 0 or 1 | `<extension type="payment">` |
+| [`<billingMode>`](#billingMode) | 0 or 1 | `<extension type="payment">` |
+| [`<isRecur>`](#isRecur) | 0 or 1 | `<extension type="payment">` |
 | [`<passwordLabel>`](#passwordLabel) | 0 or 1 | `<extension type="payment">` |
+| [`<paymentType>`](#paymentType) | 0 or 1 | `<extension type="payment">` |
+| [`<reportUrl>`](#reportUrl) | 0 or 1 | `<extension type="report">` |
 | [`<signatureLabel>`](#signatureLabel) | 0 or 1 | `<extension type="payment">` |
 | [`<subjectLabel>`](#subjectLabel) | 0 or 1 | `<extension type="payment">` |
-| [`<urlSiteDefault>`](#urlSiteDefault) | 0 or 1 | `<extension type="payment">` |
 | [`<urlApiDefault>`](#urlApiDefault) | 0 or 1 | `<extension type="payment">` |
-| [`<urlRecurDefault>`](#urlRecurDefault) | 0 or 1 | `<extension type="payment">` |
-| [`<urlSiteTestDefault>`](#urlSiteTestDefault) | 0 or 1 | `<extension type="payment">` |
 | [`<urlApiTestDefault>`](#urlApiTestDefault) | 0 or 1 | `<extension type="payment">` |
-| [`<urlRecurTestDefault>`](#urlRecurTestDefault) | 0 or 1 | `<extension type="payment">` |
 | [`<urlButtonDefault>`](#urlButtonDefault) | 0 or 1 | `<extension type="payment">` |
 | [`<urlButtonTestDefault>`](#urlButtonTestDefault) | 0 or 1 | `<extension type="payment">` |
-| [`<billingMode>`](#billingMode) | 0 or 1 | `<extension type="payment">` |
-| [`<isRecur>`](#isRecur) | 0 or 1 | `<extension type="payment">` |
-| [`<paymentType>`](#paymentType) | 0 or 1 | `<extension type="payment">` |
+| [`<urlRecurDefault>`](#urlRecurDefault) | 0 or 1 | `<extension type="payment">` |
+| [`<urlRecurTestDefault>`](#urlRecurTestDefault) | 0 or 1 | `<extension type="payment">` |
+| [`<urlSiteDefault>`](#urlSiteDefault) | 0 or 1 | `<extension type="payment">` |
+| [`<urlSiteTestDefault>`](#urlSiteTestDefault) | 0 or 1 | `<extension type="payment">` |
+| [`<userNameLabel>`](#userNameLabel) | 0 or 1 | `<extension type="payment">` |
 
 ### `<url>` {:#url}
 
@@ -373,10 +375,16 @@ Elements acceptable within `<urls>`
 * Description: *not yet documented*
 * Contains: text
 
+### `<urlSiteDefault>` {:#urlSiteTestDefault}
+
+* Containing element: [`<typeInfo>`](#typeInfo)
+* Description: The url to use to process live site transactions
+* Contains: text
+
 ### `<urlSiteTestDefault>` {:#urlSiteTestDefault}
 
 * Containing element: [`<typeInfo>`](#typeInfo)
-* Description: *not yet documented*
+* Description: The url to use to process test site transactions
 * Contains: text
 
 ### `<urlApiTestDefault>` {:#urlApiTestDefault}
@@ -416,7 +424,7 @@ Elements acceptable within `<urls>`
 ### `<userNameLabel>` {:#userNameLabel}
 
 * Containing element: [`<typeInfo>`](#typeInfo)
-* Description: *not yet documented*
+* Description: Label to use for the username field
 * Contains: text
 
 ### `<version>` {:#version}

docs/extensions/payment-processors/index.md

@@ -3,7 +3,7 @@
 This page documents payment processing in CiviCRM. The key bit to understand is the payment processor object, a civicrm-specific way of representing and integrating an actual real-life payment processor (e.g. like Paypal, etc.). The object and how it is used (as of CiviCRM 4.4) is in need of some love and refactoring, so this page hopes to provide some help in that direction.
 
 
-# Definitions
+## Definitions
 
 Some of these definitions are a bit loose, but should at least help
 clarify the use of these over-used words in the rest of the page.
@@ -32,7 +32,7 @@ fields in the user form.
 of payment processing: 'form', 'button', or 'notify'. These determine
 the user workflow required and how the CiviCRM code works.
 
-# Payment Processors
+## Processors
 
 Online payment processing is a relatively recent innovation and is still
 evolving. The earliest widely used, and still most widely used payment
@@ -75,7 +75,7 @@ module](http://drupal.org/project/commerce), and the
 [omnipay
 project](https://github.com/thephpleague/omnipay).
 
-# Payment Class
+## Payment Class
 
 CiviCRM's integration of a payment processor is based on subclassing the
 abstract class CRM_Core_Payment. That class is defined by the file
@@ -125,7 +125,7 @@ At the end of this process, you have a payment object that includes
 payment processor specific methods and a reasonably simple payment
 processor object attached to it.
 
-# Payment Processor Objects, and in the Database
+## Payment Processor Objects, and in the Database
 
 Most object instantiations in CiviCRM correspond to a row in a similarly
 named table. Payment processors are also like this, but just a little
@@ -133,7 +133,7 @@ more complicated.
 
 The key tables are:
 
-**civicrm_payment_processor_type** This table provides some
+`civicrm_payment_processor_type` This table provides some
 db-configurable values for a "payment processor" as defined above. For
 example - the labels for the account name and passwd and the urls used
 with that service. Is also contains fields with default values for the
@@ -141,7 +141,7 @@ billing mode, payment type and whether it supports recurring billing.
 Most importantly, it contains the class name of the payment processor
 that corresponds to the file defining the class.
 
-**civicrm_payment_processor** This table provides the
+`civicrm_payment_processor` This table provides the
 organization-specific implementation details of the payment processor -
 most notably the account name and passwd. It has a foreign key into the
 payment processor type table, and fields that allow for service-specific
@@ -149,7 +149,7 @@ overrides of the billing mode, payment type and whether it supports
 recurring billing. This is the table that provides the row that helps
 instantiate the payment processor object.
 
-# Payment Objects in Code
+## Payment Objects in Code
 
 As hinted at above, how the payment object is used in the code base is
 the most challenging part, particularly how it deals with the variety of
@@ -177,7 +177,7 @@ Some other examples are:
     processor, but built into the code, with all kinds of configuration
     bits in different places.
 
-# Existing Discussions
+## Existing Discussions
 
 Here's a partial list of related discussions (please contribute here):
 

docs/extensions/payment-processors/types.md

+# Payment Processor Types
+
+In CiviCRM there are four processor 'types'. These are used by CiviCRM to determine how to process a transaction.
+
+!!! note
+    "Processor type" is also referred to as "billing mode"
+
+## `form` {:#form}
+
+This mode allows the credit card information to be collected on a form within CiviCRM which is then submitted directly to the payment processor using an API. It requires an SSL connection as well as proper security compliance. The specific requirements of this method will be available from the service provider.
+
+* `billing_mode_id`: 1
+* Functions called:
+    * `doDirectPayment($params)`
+
+If you return to the calling class at the end of the function the
+contribution will be confirmed. Values from the `$params` array will be
+updated based on what you return.  If the transaction does not succeed
+you should return an error to avoid confirming the transaction.
+
+The params available to `doDirectPayment()` are: -
+
+- qfKey
+- email-(bltID)
+- billing_first_name (=first_name)
+- billing_middle_name (=middle_name)
+- billing_last_name (=last_name)
+- location_name-(bltID) = billing_first_name + billing_middle_name + billing_last_name
+- street_address
+- (bltID)
+- city-(bltID)
+- state_province_id-(bltID) (int)
+- state_province-(bltID) (XX)
+- postal_code-(bltID)
+- country_id-(bltID) (int)
+- country-(bltID) (XX)
+- credit_card_number
+- cvv2 - credit_card_exp_date - M - Y
+- credit_card_type
+- amount
+- amount_other
+- year (credit_card_exp_date => Y)
+- month (credit_card_exp_date => M)
+- ip_address
+- amount_level
+- currencyID (XXX)
+- payment_action
+- invoiceID (hex number. hash?)
+
+bltID = Billing Location Type ID. This is not actually seen by the
+payment class.
+
+## `button` {:#button}
+
+This mode utilizes a three-step method for passing information to the payment processor. The first step makes a direct connection to the payment processor API to pass initial information about the transaction. The user is then redirected to the payment processor checkout form with reference information to the transaction data previously provided to the API. In the second step, the transaction information is retrieved by the payment processor using the reference information, the user provides payment and shipping information and is then redirected back to the CiviCRM confirmation page where CiviCRM directly requests the transaction information from the payment processor API. Once the user confirms the payment, CiviCRM completes the third step by making one final direct request to the payment processor API to confirm the transaction.
+
+* `billing_mode_id`: 2
+
+The main function called by this billing mode is `setExpressCheckout($params)`. The customer is returned to `confirm.php` with the `rfp` value set to 1 and `getExpressCheckoutDetails($token)` is called when the form is processed `doExpressCheckout($params)` is called to finalise the payment - a result is returned to the civiCRM site.
+
+## `notify` {:#notify}
+
+The notify method deals with a situation where there is not a direct two way communication between your server and the processor and there is a need for your server to identify which transaction is being responded to.
+ 
+This mode posts sales information from the CiviCRM form to the service provider's checkout page where a user will complete the transaction by entering payment details. Upon success (or cancellation) the user is then returned to the original site. Notification may take place either upon the return of the user to the site, or by a separate direct connection from the payment processor API to a notification script on the site. Because this mode does not request any payment information within CiviCRM, it does not require the use of SSL. Some providers will still require testing of a payment form before authorising live transactions to be made. Specific requirements vary and will be available from the service provider.
+
+* `billing_mode_id`: 4
+* Functions called:
+    * `doTransferCheckout($params, $component)`
+
+The details from here are processor specific but you want to pass
+enough details back to your function to identify the transaction. You
+should be aiming to have these variables to passthrough the processor to
+the confirmation routine:
+
+* contactID
+* contributionID
+* contributionTypeID
+* invoiceID
+* membershipID(contribution only)
+* participantID (event only)
+* eventID (event only)
+* component (event or contribute)
+* qfkey
+
+Handling the return was the tricky part.
+
+In order to keep the return url short (because paymentexpress appends a
+long hex string) our return url goes to a file (in the extern folder )
+which redirects through to the 'main' routine in paymentExpressIPN.php
+(IPN = instant payment notification). 
+
+note - you need to  re-initialise the environment to get civi
+functions to work
+
+```php
+require_once '../civicrm.config.php';
+require_once 'CRM/Core/Config.php';
+$config =& CRM_Core_Config::singleton();
+```
+
+An appropriate structure for the return routine file is:
+
+```php
+function newOrderNotify(
+    $success,
+    $privateData,
+    $component,
+    $amount,
+    $transactionReference ) {
+  $ids = $input = $params = array( );
+}
+```
+
+this version in the paymentexpress file is not processor specific -
+pass it the variables above and it will complete the transaction.
+Success is boolean, the private data array holds, the component is
+(lower case) 'event' or 'contribute' , amount is obvious, transaction
+reference is any processor related reference.
+
+contactID, contributionID, contributionTypeID,invoiceID,
+membershipID(contribution only), participantID (event only), eventID
+(event only)
+
+static function getContext( $privateData, $orderNo)
+
+generic function - taken from google version - retrieves information
+to complete transaction (required?)
+
+private data as above
+
+orderno - transactionreference is OK
+
+```php
+static function main(blah, blah,  blah)
+```
+
+this function is processor specific - it  converts whatever form your
+processor response is into the variables required for the above
+function and if necessary redirects the browser using
+
+```php
+CRM_Utils_System::redirect( $finalURL );
+```
+
+
+## `special` {:#special}
+
+This mode is reserved exclusively for PayPal Website Payments Pro. It enables PayPal to have both a 'form' and 'button' mode available.
+
+* `billing_mode_id`: 3

mkdocs.yml

@@ -52,8 +52,8 @@ pages:
   - Advanced patterns: extensions/advanced.md
   - Payment Processors:
     - Payment Processors: extensions/payment-processors/index.md
+    - Payment Processor Types: extensions/payment-processors/types.md
     - Creating a Payment Processor: extensions/payment-processors/create.md
-    - Payment Processor Example: extensions/payment-processors/example.md
 - Testing:
   - Testing Setup: testing/setup.md
   - "PHPUnit Tests": testing/phpunit.md

redirects/wiki-crmdoc.txt

@@ -183,4 +183,4 @@ Extending+Smarty framework/templates/extending-smarty
 What+is+a+Payment+Processor extensions/payment-processors
 Create+a+Payment-Processor+Extension docs/extensions/payment-processors/create
 Testing+Processor+Plugins docs/extensions/payment-processors/create/#testing
-Example+of+creating+a+payment+processor+extension extensions/payment-processors/example
+Example+of+creating+a+payment+processor+extension extensions/payment-processors/create