Update pin gateway to add support for purchasing with card tokens

[justinjones]

I don't normally write PHP so this may be terrible, but I gave it a shot.

The example looks a bit weird as the email is still required, but is an attribute of the card with Omnipay? So it looks like this:

$gateway = GatewayFactory::create('Pin');
$gateway->setSecretKey('secret-key');

$response = $gateway->purchase([
  'description' => 'Widgets',
  'amount'      => '1.21',
  'currency'    => 'USD',
  'token'  => 'card_mcqQ_H1NtRODN1reRwEdmQ',
  'ip_address'  => '1.2.3.4',
  'card' => array('email' => 'test@example.org'),
])->send();

[amacneil]

Looks pretty good. We should probably implement store() to save tokens as well.

Wait, email is required even when charging a stored token? That is ridiculous.

[justinjones]

This is a one-time use token created with Pin.js or the card tokens API (https://pin.net.au/docs/api/cards) - email is not required.

Email is only required when you use said token to make a Charge.

[amacneil]

Oh ok, took a look at their docs, I see what you mean. This is for charging a temporary token generated by their JS library, not a stored card. In that case it's slightly less ridiculous. Still don't see why email is mandatory though.

[justinjones]

Pin sends out their own email receipts for fraud prevention/chargeback purposes. (I'm a developer @ Pin)

[prashantp26]

@nagash cheers for the quick action mate.

[amacneil]

Cheers, I've merged in. Pretty clean for someone who doesn't write PHP :) I just made a slight change to validate the card is passed in, since it's always required, and changed the test class to use 4 spaces for indentation.

On the email address - fair enough, though most gateways have that as an optional feature. I don't think I've ever seen it mandatory before. The reason email is part of the CreditCard object is that is "user input", along with the address and other details. The idea is that it's safe to mass assign to the CreditCard, whereas parameters on the Request object usually come directly from your application.