Add ability to use payment tokens from front-end forms

This is about offering people the opportunity to use stored tokens representing their credit card data rather than re-entering it. This spec is around offering the option to pay on a front end form.

Note that the industry term for this is card on file (even though the card is not stored locally)

Tokens are stored on files in 2 different ways
1) checking a check box that says
'store my credit card for next time' - the ability to store is permission and hook controlled.

2) creating a recurring transaction.

Stephen from IATS has advised that there are not PCI rules around how this is used but we want users to be able to define permissions to choose whether to allow it AND developers to be able to alter this permission by hook.

====
Offering the option to store a credit card
====
1) On the form layer IF the user has permission to 'Store payment token '
If ($paymentProcessor->supports('cardOnFile'))

{ // add a checkbox with the text $paymentProcessor->getStoreTokenText() - with the default class text being (TBC!!!!) "store my payment details for next time" // }

the store paymentToken permission could be altered by hook
setTokenUsePermission($is_permitted, $tokenID, $tokenContactID, $action, $params);
(action would be 'save token').

2) if the checkbox is checked then it will be one of the parameters passed to doPayment by the postProcess function. Payment processor is responsible for storing the token (using a payment_token api call).

==========================
Option to pay by token
==========================
if ( If ($paymentProcessor->supports('cardOnFile')
&& validTokenExistsForLoggedInUser() )

{ // show a check box below the payment options $paymentProcessor->getOfferTokenText() //default is 'pay using credit card previously stored for BILLING_NAME with expiry of xx & masked credit card details of y }

}

Checking & unchecking this checkbox will show & hide other payment options and make that field non-compulsory.

validTokenExistsForLoggedInUser() returns all tokens that match the logged in user (must be logged in - checksum not OK and cid=0 / another contact_id is not OK) and a null or future expiry. The reason to exclude cid=0 / cid=333 is that, while we think it makes sense for a parent filling in for a child to see their own token it could be confusing for back-office staff ). We think it's complicated to come up with a generic solution but the hook implementers could override this limitation

We expect that people might pay with someone else's credit card and after discussion have decided that we will not try to control this within CiviCRM but allow sites to control with broad-brush permissions, OR by implementing a hook. We did discuss ensuring a billing_name match but agreed this logic should be implement in extensions as required.

setTokenUsePermission($is_permitted, $tokenID, $tokenContactID, $action, $params);
(action would be 'use_own_token').

======================
PostProcess
=====================
If paying by token
1) load the payment processor attached to the token.
2) call it using doTokenPayment
3) otherwise call do payment
Note we will wrap this logic into another function that the form layer always calls so none of that will need to live on the form.