Support token parameter for providing opaque data.

Author: judgej

README.md

@@ -39,7 +39,7 @@ and for creating transactions using a card token.
 ## API Authorize/Purchase (Credit Card)
 
 The following example is a simple authorize with supplied card details.
-You would normally avoid allowing card details near your merchanet site
+You would normally avoid allowing card details near your merchant site
 back end for PCI compliance reasons,
 supplying a tokenised card reference instead (see later section for this).
 
@@ -236,13 +236,22 @@ or
 $request->setOpaqueData($opaqueDataDescriptor, $opaqueDataValue);
 ```
 
-The authorizatiob or purchase should then go ahead as though the card
+or join with a colon (:) to handle as a card token:
+
+```php
+$request->setToken($opaqueDataDescriptor . ':' . $opaqueDataValue);
+```
+
+The authorize or purchase should then go ahead as though the card
 details were provided directly. In the result, the last four digits
 of the card will be made available in case a refund needs to be performed.
 
 Further details can be 
 [fouund in the officual documentation](https://developer.authorize.net/api/reference/features/acceptjs.html).
 
+Note also that the opaque data is used for other payment sources, such as
+bank accounts and PayPal.
+
 ## API Void
 
 An authorized transaction can be voided:

src/Message/AuthorizeRequest.php

@@ -29,6 +29,12 @@
 
 class AuthorizeRequest extends AbstractRequest
 {
+    /**
+     * @var string The separator used to join the opaque data
+     * descriptor and value, when used as a card token.
+     */
+    const CARD_TOKEN_SEPARATOR = ':';
+
     /**
      * Return the complete transaction object which will later be wrapped in
      * a \Academe\AuthorizeNet\Request\CreateTransaction object.
@@ -309,8 +315,34 @@ public function getOpaqueDataValue()
      */
     public function setOpaqueData($descriptor, $value)
     {
-        $this->setOpaqueDataValue($value);
         $this->setOpaqueDataDataDescriptor($descriptor);
+        $this->setOpaqueDataValue($value);
+
         return $this;
     }
+
+    /**
+     * The opaque data comes in two parts, but Omnipay uses just
+     * one parameter for a card token.
+     * Join the descriptor and the value with a colon.
+     */
+    public function setToken($value)
+    {
+        list($opaqueDataDescriptor, $opaqueDataValue) = explode(static::CARD_TOKEN_SEPARATOR, $value, 2);
+
+        $this->setOpaqueDataDescriptor($opaqueDataDescriptor);
+        $this->setOpaqueDataValue($opaqueDataValue);
+
+        return $this;
+    }
+
+    public function getToken()
+    {
+        $opaqueDataDescriptor = $this->getOpaqueDataDescriptor();
+        $opaqueDataValue = $this->getOpaqueDataValue();
+
+        if ($opaqueDataDescriptor && $opaqueDataValue) {
+            return $opaqueDataDescriptor . static::CARD_TOKEN_SEPARATOR . $opaqueDataValue;
+        }
+    }
 }

tests/Message/AuthorizeRequestTest.php

@@ -0,0 +1,53 @@
+<?php
+
+namespace Omnipay\AuthorizeNetApi;
+
+use Omnipay\Tests\TestCase;
+
+class AuthorizeRequestTest extends TestCase
+{
+    public function setUp()
+    {
+        parent::setUp();
+
+        $this->gateway = new ApiGateway(
+            $this->getHttpClient(),
+            $this->getHttpRequest()
+        );
+    }
+
+    public function testOpaqueData()
+    {
+        $opaqueDescriptor = 'COMMON.ACCEPT.INAPP.PAYMENT';
+        $opaqueValue = str_shuffle(str_repeat('1234567890ABCDEFGHIJ', 10));
+
+        $cardToken = $opaqueDescriptor . ':' . $opaqueValue;
+
+        $request = $this->gateway->authorize([
+            'opaqueDataDescriptor' => $opaqueDescriptor,
+            'opaqueDataValue' => $opaqueValue,
+        ]);
+
+        $this->assertSame($cardToken, $request->getToken());
+
+        $this->assertSame($opaqueDescriptor, $request->getOpaqueDataDescriptor());
+        $this->assertSame($opaqueValue, $request->getOpaqueDataValue());
+    }
+
+    public function testCardToken()
+    {
+        $opaqueDescriptor = 'COMMON.ACCEPT.INAPP.PAYMENT';
+        $opaqueValue = str_shuffle(str_repeat('1234567890ABCDEFGHIJ', 10));
+
+        $cardToken = $opaqueDescriptor . ':' . $opaqueValue;
+
+        $request = $this->gateway->authorize([
+            'token' => $cardToken,
+        ]);
+
+        $this->assertSame($cardToken, $request->getToken());
+
+        $this->assertSame($opaqueDescriptor, $request->getOpaqueDataDescriptor());
+        $this->assertSame($opaqueValue, $request->getOpaqueDataValue());
+    }
+}